@mrclrchtr/supi-code-intelligence 6.1.0 → 6.2.0

package/node_modules/@mrclrchtr/supi-lsp/src/summary.ts

@@ -3,6 +3,7 @@ import type {
   ActiveCoverageSummaryEntry,
   OutstandingDiagnosticSummaryEntry,
 } from "./manager/manager-types.ts";
+import type { AutomaticLspPathPolicy } from "./workspace-path-policy.ts";
 
 /**
  * Display form for a file path used both for human-readable LSP output and as
@@ -67,9 +68,14 @@ export function normalizeRelevantPaths(relevantPaths: string[]): string[] {
  *  - candidate has no "/" and no ".": treat as a directory name anywhere in the path
  *  - otherwise: treat as a filename and match the basename
  */
-export function isPathRelevant(filePath: string, relevantPaths: string[], cwd: string): boolean {
+export function isPathRelevant(
+  filePath: string,
+  relevantPaths: string[],
+  cwd: string,
+  policy: AutomaticLspPathPolicy,
+): boolean {
   const normalizedFilePath = normalizeRelevantPath(filePath);
-  if (shouldIgnoreLspPath(normalizedFilePath, cwd)) return false;
+  if (shouldIgnoreLspPath(normalizedFilePath, cwd, policy)) return false;
 
   return relevantPaths.some((candidate) => {
     if (normalizedFilePath === candidate) return true;
@@ -86,48 +92,21 @@ export function isPathRelevant(filePath: string, relevantPaths: string[], cwd: s
 
 import { isFileExcludedByTsconfig } from "./config/tsconfig-scope.ts";
 
-/** Check whether a file path is inside the project tree (within cwd, not node_modules/.pnpm/out-of-tree).
- *  Does NOT check tsconfig exclusion — use `shouldIgnoreLspPath` for diagnostics/guidance filtering. */
-export function isInProjectTree(filePath: string, cwd: string): boolean {
-  const normalized = normalizeRelevantPath(filePath);
-  if (
-    normalized === "node_modules" ||
-    normalized.startsWith("node_modules/") ||
-    normalized.includes("/node_modules/") ||
-    normalized === ".pnpm" ||
-    normalized.startsWith(".pnpm/") ||
-    normalized.includes("/.pnpm/")
-  ) {
-    return false;
-  }
-
-  const absolutePath = path.resolve(cwd, filePath);
-  const relativePath = path.relative(cwd, absolutePath);
-  return !(relativePath.startsWith(`..${path.sep}`) || relativePath === "..");
+/** Check whether the supplied automatic path policy allows a file path. */
+export function isInProjectTree(filePath: string, policy: AutomaticLspPathPolicy): boolean {
+  return policy.isEligible(filePath);
 }
 
-/** Check whether a file path is inside the current project (not ignored and within cwd). */
-export function isProjectSource(filePath: string, cwd: string): boolean {
-  return isInProjectTree(filePath, cwd);
-}
-
-export function shouldIgnoreLspPath(filePath: string, cwd: string): boolean {
-  if (!isInProjectTree(filePath, cwd)) return true;
+/** Check automatic and tsconfig diagnostic scope for one file path. */
+export function shouldIgnoreLspPath(
+  filePath: string,
+  cwd: string,
+  policy: AutomaticLspPathPolicy,
+): boolean {
+  if (!isInProjectTree(filePath, policy)) return true;
 
   const normalized = normalizeRelevantPath(filePath);
-  if (
-    normalized === "node_modules" ||
-    normalized.startsWith("node_modules/") ||
-    normalized.includes("/node_modules/") ||
-    normalized === ".pnpm" ||
-    normalized.startsWith(".pnpm/") ||
-    normalized.includes("/.pnpm/") ||
-    isFileExcludedByTsconfig(normalized, cwd)
-  ) {
-    return true;
-  }
-
-  return false;
+  return isFileExcludedByTsconfig(normalized, cwd);
 }
 
 function normalizeRelevantPath(filePath: string): string {

package/node_modules/@mrclrchtr/supi-lsp/src/utils.ts

@@ -3,12 +3,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-export {
-  fileToUri,
-  resolveToolPath as resolveSessionPath,
-  uriToFile,
-} from "@mrclrchtr/supi-core/path";
-
 // ── Language ID Detection ─────────────────────────────────────────────
 
 const EXT_TO_LANGUAGE: Record<string, string> = {
@@ -68,11 +62,6 @@ export function detectLanguageId(filePath: string): string {
   return EXT_TO_LANGUAGE[ext] ?? ext;
 }
 
-/** Get the file extension (without dot) from a file path. */
-export function getFileExtension(filePath: string): string {
-  return path.extname(filePath).slice(1).toLowerCase();
-}
-
 // ── PATH Validation ───────────────────────────────────────────────────
 
 /**
@@ -80,9 +69,9 @@ export function getFileExtension(filePath: string): string {
  * Uses synchronous check to avoid complexity.
  */
 export function commandExists(command: string): boolean {
-  // If it's an absolute path, check directly
+  // If it is an absolute path, validate the exact executable file.
   if (path.isAbsolute(command)) {
-    return fs.existsSync(command);
+    return isExecutableFile(command);
   }
 
   const pathDirs = (process.env.PATH ?? "").split(path.delimiter);
@@ -92,13 +81,18 @@ export function commandExists(command: string): boolean {
   for (const dir of pathDirs) {
     for (const ext of extensions) {
       const fullPath = path.join(dir, command + ext);
-      try {
-        fs.accessSync(fullPath, fs.constants.X_OK);
-        return true;
-      } catch {
-        // Not found here, continue
-      }
+      if (isExecutableFile(fullPath)) return true;
     }
   }
   return false;
 }
+
+function isExecutableFile(filePath: string): boolean {
+  try {
+    if (!fs.statSync(filePath).isFile()) return false;
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/node_modules/@mrclrchtr/supi-lsp/src/workspace-path-policy.ts

@@ -0,0 +1,287 @@
+import { type Dirent, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import * as path from "node:path";
+import ignore from "ignore";
+import { loadLspSettings } from "./config/lsp-settings.ts";
+
+/** Directory names that automatic LSP work never enters or selects. */
+export const AUTOMATIC_LSP_EXCLUDED_DIRECTORIES: readonly string[] = Object.freeze([
+  ".git",
+  ".cache",
+  ".pi",
+  ".pnpm",
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  "__pycache__",
+]);
+
+const BUILT_IN_EXCLUSIONS = new Set(AUTOMATIC_LSP_EXCLUDED_DIRECTORIES);
+
+/** Automatic path rules for one Workspace LSP runtime. The rules do not change. */
+export interface AutomaticLspPathPolicy {
+  /** Canonical absolute workspace root used for all matching. */
+  readonly workspaceRoot: string;
+  /** True when automatic LSP work can use the path. */
+  isEligible(candidate: string, kind?: "file" | "directory"): boolean;
+}
+
+/** Create the automatic path rules for one Workspace LSP runtime. */
+export function createAutomaticLspPathPolicy(
+  workspaceRoot: string,
+  excludePatterns: readonly string[],
+): AutomaticLspPathPolicy {
+  const canonicalRoot = canonicalPath(workspaceRoot);
+  const configuredExclusions = createIgnoreMatcher([...excludePatterns]);
+  const repositoryRules = compileRepositoryRules(canonicalRoot, configuredExclusions);
+  return Object.freeze({
+    workspaceRoot: canonicalRoot,
+    isEligible(candidate: string, kind: "file" | "directory" = "file"): boolean {
+      const relativePath = normalizeCandidate(canonicalRoot, workspaceRoot, candidate);
+      if (
+        relativePath === null ||
+        !isAutomaticCandidateAllowed(workspaceRoot, relativePath, kind)
+      ) {
+        return false;
+      }
+      return isEligibleRelativePath(
+        relativePath,
+        kind === "directory",
+        configuredExclusions,
+        repositoryRules,
+      );
+    },
+  });
+}
+
+/**
+ * Create path rules for an automatic LSP helper used outside a runtime.
+ * Runtime-owned operations should pass the rules created at startup instead.
+ */
+export function createDefaultAutomaticLspPathPolicy(workspaceRoot: string): AutomaticLspPathPolicy {
+  return createAutomaticLspPathPolicy(workspaceRoot, loadLspSettings(workspaceRoot).exclude);
+}
+
+/**
+ * Walk paths allowed by the policy without visiting symbolic-link directories.
+ *
+ * The visitor receives only entries that the automatic LSP policy allows.
+ * Return `true` from the visitor to stop the walk after that directory.
+ */
+export function walkAutomaticLspTree(
+  policy: AutomaticLspPathPolicy,
+  directory: string,
+  depth: number,
+  onDirectory: (directory: string, entries: readonly Dirent[]) => boolean | undefined,
+): void {
+  walkDirectoryTree({
+    directory,
+    depth,
+    includeEntry: (candidate, entry) =>
+      policy.isEligible(candidate, entry.isDirectory() ? "directory" : "file"),
+    onDirectory,
+  });
+}
+
+interface DirectoryWalkOptions {
+  directory: string;
+  depth: number;
+  includeEntry: (candidate: string, entry: Dirent) => boolean;
+  onDirectory: (directory: string, entries: readonly Dirent[]) => boolean | undefined;
+  beforeFilter?: (directory: string) => void;
+}
+
+function walkDirectoryTree(options: DirectoryWalkOptions): boolean {
+  const { directory, depth, includeEntry, onDirectory, beforeFilter } = options;
+  beforeFilter?.(directory);
+  let entries: Dirent[];
+  try {
+    entries = [...readdirSync(directory, { withFileTypes: true })].sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+  } catch {
+    return false;
+  }
+
+  const eligibleEntries = entries.filter((entry) =>
+    includeEntry(path.join(directory, entry.name), entry),
+  );
+  if (onDirectory(directory, eligibleEntries) === true) return true;
+  if (depth <= 0) return false;
+
+  for (const entry of eligibleEntries) {
+    if (!entry.isDirectory()) continue;
+    if (
+      walkDirectoryTree({
+        ...options,
+        directory: path.join(directory, entry.name),
+        depth: depth - 1,
+      })
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+type IgnoreMatcher = ReturnType<typeof ignore>;
+
+function createIgnoreMatcher(patterns: string | readonly string[]): IgnoreMatcher {
+  return ignore({ ignorecase: false }).add(patterns);
+}
+
+interface RepositoryIgnoreRules {
+  readonly base: string;
+  readonly matcher: IgnoreMatcher;
+}
+
+function compileRepositoryRules(
+  workspaceRoot: string,
+  configuredExclusions: IgnoreMatcher,
+): readonly RepositoryIgnoreRules[] {
+  const rules: RepositoryIgnoreRules[] = [];
+
+  walkDirectoryTree({
+    directory: workspaceRoot,
+    depth: Number.MAX_SAFE_INTEGER,
+    includeEntry: (candidate, entry) => {
+      if (entry.isSymbolicLink() || !entry.isDirectory()) return false;
+      const relativePath = path.relative(workspaceRoot, candidate).split(path.sep).join("/");
+      return isEligibleRelativePath(relativePath, true, configuredExclusions, rules);
+    },
+    onDirectory: () => undefined,
+    beforeFilter: (directory) => {
+      const relativeDirectory = path.relative(workspaceRoot, directory).split(path.sep).join("/");
+      const nestedRules = readRepositoryIgnore(directory, relativeDirectory);
+      if (nestedRules) rules.push(nestedRules);
+    },
+  });
+
+  return Object.freeze([...rules]);
+}
+
+function readRepositoryIgnore(
+  directory: string,
+  relativeDirectory: string,
+): RepositoryIgnoreRules | null {
+  try {
+    const matcher = createIgnoreMatcher(readFileSync(path.join(directory, ".gitignore"), "utf-8"));
+    return Object.freeze({ base: relativeDirectory, matcher });
+  } catch {
+    return null;
+  }
+}
+
+function isEligibleRelativePath(
+  relativePath: string,
+  directory: boolean,
+  configuredExclusions: IgnoreMatcher,
+  repositoryRules: readonly RepositoryIgnoreRules[],
+): boolean {
+  const segments = relativePath.split("/");
+  if (
+    segments.some(
+      (segment, index) =>
+        BUILT_IN_EXCLUSIONS.has(segment) && (directory || index < segments.length - 1),
+    )
+  ) {
+    return false;
+  }
+  if (relativePath === "") return true;
+
+  const matchPath = directory ? `${relativePath}/` : relativePath;
+  if (configuredExclusions.ignores(matchPath)) return false;
+  return !isRepositoryIgnored(relativePath, directory, repositoryRules);
+}
+
+function isRepositoryIgnored(
+  relativePath: string,
+  directory: boolean,
+  repositoryRules: readonly RepositoryIgnoreRules[],
+): boolean {
+  let ignored = false;
+  for (const rules of repositoryRules) {
+    const localPath = relativeToRuleBase(rules.base, relativePath);
+    if (localPath === null || localPath === "") continue;
+    const result = rules.matcher.test(directory ? `${localPath}/` : localPath);
+    if (result.ignored) ignored = true;
+    else if (result.unignored) ignored = false;
+  }
+  return ignored;
+}
+
+function relativeToRuleBase(base: string, relativePath: string): string | null {
+  if (base === "") return relativePath;
+  if (relativePath === base) return "";
+  return relativePath.startsWith(`${base}/`) ? relativePath.slice(base.length + 1) : null;
+}
+
+function isAutomaticCandidateAllowed(
+  suppliedRoot: string,
+  relativePath: string,
+  kind: "file" | "directory",
+): boolean {
+  if (relativePath === "") return true;
+  let current = path.resolve(suppliedRoot);
+  const segments = relativePath.split("/");
+
+  for (const [index, segment] of segments.entries()) {
+    current = path.join(current, segment);
+    let link: ReturnType<typeof lstatSync>;
+    try {
+      link = lstatSync(current);
+    } catch {
+      return true;
+    }
+    if (!link.isSymbolicLink()) continue;
+    if (index < segments.length - 1) return false;
+
+    try {
+      const target = statSync(current);
+      return kind === "file" && target.isFile();
+    } catch {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function canonicalPath(candidate: string): string {
+  try {
+    return realpathSync(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+
+function normalizeCandidate(
+  canonicalRoot: string,
+  suppliedRoot: string,
+  candidate: string,
+): string | null {
+  const absoluteCandidate = path.isAbsolute(candidate)
+    ? mapSuppliedRootToCanonical(canonicalRoot, suppliedRoot, candidate)
+    : path.resolve(canonicalRoot, candidate);
+  const relativePath = path.relative(canonicalRoot, absoluteCandidate);
+  if (relativePath === "") return "";
+  if (relativePath === ".." || relativePath.startsWith(`..${path.sep}`)) return null;
+  return relativePath.split(path.sep).join("/");
+}
+
+function mapSuppliedRootToCanonical(
+  canonicalRoot: string,
+  suppliedRoot: string,
+  candidate: string,
+): string {
+  const resolvedSuppliedRoot = path.resolve(suppliedRoot);
+  const relativePath = path.relative(resolvedSuppliedRoot, path.resolve(candidate));
+  if (relativePath === "" || (relativePath !== ".." && !relativePath.startsWith(`..${path.sep}`))) {
+    return path.resolve(canonicalRoot, relativePath);
+  }
+  return path.resolve(candidate);
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/README.md

@@ -25,7 +25,6 @@ npm install @mrclrchtr/supi-tree-sitter
 
 This package provides the parser-backed structural substrate consumed by `@mrclrchtr/supi-code-intelligence`:
 
-- a shared session-scoped Tree-sitter service for structural analysis
 - an owned parsing session API for direct library consumers
 - a `StructuralProvider` adapter published through `./provider/tree-sitter-provider`
 - a long-lived owned Structural Worker that keeps Pi responsive during parser-backed work
@@ -59,18 +58,20 @@ Outline collection supports every listed family. HTML outlines contain elements
 `@mrclrchtr/supi-tree-sitter` is the **structural substrate** in SuPi's
 code-understanding stack. It depends on `@mrclrchtr/supi-core` and
 `@mrclrchtr/supi-code-runtime` for shared contracts, and provides structural
-analysis via a session-scoped Tree-sitter service that publishes its
-capabilities into the shared workspace runtime.
+analysis via a lifecycle controller that publishes its capabilities into
+the shared workspace runtime.
 
 ```text
 supi-code-runtime  ← shared contracts + workspace runtime
     ↑
-supi-tree-sitter  ← one owned Structural Worker + session-scoped service + runtime capabilities
+supi-tree-sitter  ← one owned Structural Worker + runtime capabilities
 ```
 
 ## Package surfaces
 
-- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory, shared session-scoped structural service access, and shared result types
+There is no package-root export. Use one of these explicit subpaths:
+
+- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory, lifecycle controller, language helpers, and shared result types
 - `@mrclrchtr/supi-tree-sitter/provider/tree-sitter-provider` — shared StructuralProvider adapter
 
 This is a **library-only** package. Public tool registration and pi event handlers belong to `@mrclrchtr/supi-code-intelligence`.
@@ -89,17 +90,6 @@ const callees = await session.calleesAt("src/index.ts", 42, 10);
 await session.dispose();
 ```
 
-Shared session-scoped service example:
-
-```ts
-import { getSessionTreeSitterService } from "@mrclrchtr/supi-tree-sitter/api";
-
-const state = getSessionTreeSitterService("/project");
-if (state.kind === "ready") {
-  const outline = await state.service.outline("src/index.ts");
-}
-```
-
 ## Structural performance baseline
 
 Run the stable outline fixture on the same machine and dependency versions:
@@ -117,7 +107,6 @@ All structural service operations accept optional `CodeRequestControl`. The pare
 ## Source
 
 - `src/api.ts` — public library entrypoint
-- `src/index.ts` — re-export surface
 - `src/worker/bootstrap.mjs` — package-owned Worker bootstrap and direct `jiti` loader
 - `src/worker/runtime.ts` — Worker-only parser and query runtime
 - `src/worker/parsed-file-store.ts` — Worker-only parsed-file and compiled-query reuse
@@ -125,6 +114,5 @@ All structural service operations accept optional `CodeRequestControl`. The pare
 - `src/session/runtime-controller.ts` — generation-fenced shared Worker lifecycle
 - `src/session/session.ts` — asynchronous Worker-proxy service and owned session API
 - `src/operation-support.ts` — authoritative operation-specific extension support
-- `src/session/service-registry.ts` — shared session-scoped structural service registry
 - `src/provider/tree-sitter-provider.ts` — `StructuralProvider` adapter consumed by `@mrclrchtr/supi-code-intelligence`
 - `src/tool/outline.ts`, `src/tool/outline-*.ts`, `src/tool/imports.ts`, `src/tool/exports.ts`, `src/tool/node-at.ts`, `src/tool/callees.ts`, `src/tool/call-sites.ts` — Worker-internal structural analyses

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/debug-identity.ts

@@ -0,0 +1,11 @@
+/** Maximum UTF-16 code-unit length of one debug identity string. */
+export const MAX_DEBUG_IDENTITY_STRING = 512;
+
+/** Marker appended to a truncated debug identity string. */
+export const DEBUG_IDENTITY_TRUNCATION_MARKER = "…";
+
+/** Bound one debug identity string, including its truncation marker. */
+export function truncateDebugIdentity(value: string): string {
+  if (value.length <= MAX_DEBUG_IDENTITY_STRING) return value;
+  return `${value.slice(0, MAX_DEBUG_IDENTITY_STRING - 1)}${DEBUG_IDENTITY_TRUNCATION_MARKER}`;
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/debug.ts

@@ -3,6 +3,11 @@
 // Kept separate from debug-registry.ts so debug-timing.ts can import the
 // registry without creating an import cycle through the barrel re-export.
 
+export {
+  DEBUG_IDENTITY_TRUNCATION_MARKER,
+  MAX_DEBUG_IDENTITY_STRING,
+  truncateDebugIdentity,
+} from "./debug-identity.ts";
 // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point

package/node_modules/@mrclrchtr/supi-tree-sitter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Structural AST analysis for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -30,14 +30,13 @@
     "src/**/*.mjs",
     "src/**/*.json",
     "resources",
-    "scripts/*.mjs",
     "!__tests__"
   ],
   "dependencies": {
     "jiti": "^2.7.0",
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-code-runtime": "6.1.0",
-    "@mrclrchtr/supi-core": "6.1.0"
+    "@mrclrchtr/supi-code-runtime": "6.2.0",
+    "@mrclrchtr/supi-core": "6.2.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",
@@ -45,7 +44,6 @@
     "jiti",
     "web-tree-sitter"
   ],
-  "main": "src/api.ts",
   "exports": {
     "./api": "./src/api.ts",
     "./package.json": "./package.json",

package/node_modules/@mrclrchtr/supi-tree-sitter/src/api.ts

@@ -1,4 +1,4 @@
-// Public tree-sitter session factory, shared session service access, and shared types.
+// Public Tree-sitter session factory, lifecycle controller, and shared types.
 //
 // This package is library-only — no pi extension surface.
 // Exports structured runtime/service APIs only.
@@ -7,19 +7,11 @@
 // Language detection helpers
 export {
   detectGrammar,
-  getSupportedExtension,
   getSupportedExtensions,
-  isJsTsGrammar,
-  isSupportedFile,
 } from "./language.ts";
 export type { StructuralSearchOperation } from "./operation-support.ts";
 export { getStructuralSearchSupportedExtensions } from "./operation-support.ts";
-export type {
-  TsControllerState,
-  TsStartResult,
-} from "./session/runtime-controller.ts";
 export { TreeSitterRuntimeController } from "./session/runtime-controller.ts";
-export { getSessionTreeSitterService } from "./session/service-registry.ts";
 export { createTreeSitterSession } from "./session/session.ts";
 
 // Shared types
@@ -32,8 +24,6 @@ export type {
   NodeAtResult,
   OutlineItem,
   QueryCapture,
-  SessionTreeSitterService,
-  SessionTreeSitterServiceState,
   SourceRange,
   SupportedExtension,
   TreeSitterResult,

package/node_modules/@mrclrchtr/supi-tree-sitter/src/coordinates.ts

@@ -81,6 +81,25 @@ export function nodeToRange(
   };
 }
 
+/** Validate that a public position exists in the source bounds. */
+export function validatePublicPositionBounds(
+  line: number,
+  character: number,
+  source: string,
+): { kind: "validation-error"; message: string } | null {
+  const lines = splitSourceLines(source);
+  if (line > lines.length) {
+    return { kind: "validation-error", message: "line is beyond end of file" };
+  }
+
+  const lineText = lines[line - 1] ?? "";
+  if (character > lineText.length + 1) {
+    return { kind: "validation-error", message: "character is beyond end of line" };
+  }
+
+  return null;
+}
+
 /** Split source into logical lines without CRLF line-ending bytes. */
 export function splitSourceLines(source: string): string[] {
   return source.replace(/\r\n?/g, "\n").split("\n");