@mrclrchtr/supi-code-runtime 3.2.0 → 4.1.0

package/README.md

@@ -8,6 +8,14 @@ This is a **library-only package** — it has no pi extension surface, no user-f
 
 - `@mrclrchtr/supi-code-runtime/api` — shared canonical types, capability interfaces, workspace runtime registry, and typed request context
 
+Read-only provider methods return `CodeQueryResult<T>`:
+
+- `completed` — collection completed; `data` may be empty or `null`
+- `partial` — usable data was collected, but one or more provider branches failed
+- `unavailable` — no result was established; includes a reason
+
+This keeps successful zero-result facts distinct from routing, transport, and provider failures.
+
 ## License
 
 MIT

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -50,7 +50,6 @@
   },
   "main": "src/api.ts",
   "exports": {
-    "./abort-utils": "./src/abort-utils.ts",
     "./api": "./src/api.ts",
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
@@ -71,7 +70,6 @@
     "./status-spinner": "./src/status-spinner.ts",
     "./terminal": "./src/terminal.ts",
     "./tool-framework": "./src/tool-framework.ts",
-    "./prompt-surface": "./src/prompt-surface.ts",
-    "./types": "./src/types.ts"
+    "./prompt-surface": "./src/prompt-surface.ts"
   }
 }

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -6,8 +6,6 @@
 // For lighter imports, use one of the domain subpaths directly
 // (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./abort-utils.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -42,5 +40,3 @@ export * from "./status-spinner.ts";
 export * from "./terminal.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./tool-framework.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./types.ts";

package/node_modules/@mrclrchtr/supi-core/src/evidence-badge.ts

@@ -22,14 +22,15 @@ export interface EvidenceBadgeInput {
  * |------------------------------------------------------|---------------------------------------|
  * | shown=12, total=12, omitted=0, label="references"   | `12 references`                       |
  * | shown=8,  total=20, omitted=12, label="symbols"     | `8 of 20 symbols (12 omitted)`        |
- * | shown=5,  total=null, reason="timeout", label="matches" | `5 matches — timeout`              |
+ * | shown=5, total=null, omitted=2, reason="timeout" | `5 matches (2 collected omitted; more may exist — timeout)` |
  */
 export function formatEvidenceBadge(input: EvidenceBadgeInput): string {
   const { shownCount, totalCount, omittedCount, partialReason, label } = input;
 
   if (totalCount === null) {
     const reasonSuffix = partialReason ? ` — ${partialReason}` : "";
-    return `${shownCount} ${label}${reasonSuffix}`;
+    const omittedPrefix = (omittedCount ?? 0) > 0 ? `${omittedCount} collected omitted; ` : "";
+    return `${shownCount} ${label} (${omittedPrefix}more may exist${reasonSuffix})`;
   }
 
   if (omittedCount !== null && omittedCount > 0) {

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -6,8 +6,6 @@
 // For lighter imports, use one of the domain subpaths directly
 // (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./abort-utils.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -36,5 +34,3 @@ export * from "./status-spinner.ts";
 export * from "./terminal.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./tool-framework.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./types.ts";

package/node_modules/@mrclrchtr/supi-core/src/llm.ts

@@ -24,16 +24,6 @@ export interface WithRetryOptions {
   onRetry?: (attempt: number, delayMs: number) => void;
 }
 
-/**
- * Attempt an async operation with retries and exponential backoff.
- *
- * If the signal is already aborted on entry, the operation is skipped entirely.
- * If the signal aborts during a delay, the delay is cancelled immediately.
- *
- * @param fn - The async operation to retry.
- * @param options - Optional configuration for retries, backoff, signal, and callbacks.
- * @returns The result on success, or `null` if all attempts fail or the signal aborts.
- */
 /**
  * Create a promise that resolves after `ms` milliseconds, or rejects if
  * the signal fires before the timeout elapses.

package/node_modules/@mrclrchtr/supi-core/src/path-utils.ts

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 /** Strip pi's optional leading `@` file-path prefix from a tool input. */
 export function stripToolPathPrefix(target: string): string {
@@ -16,25 +17,28 @@ export function resolveToolPath(cwd: string, target: string): string {
   return path.resolve(cwd, stripToolPathPrefix(target));
 }
 
-/** Convert a file path to a file:// URI. */
+/**
+ * Convert a file path to a file:// URI.
+ *
+ * Uses Node's `pathToFileURL` to produce a standards-compliant URI with
+ * proper percent-encoding of spaces, hashes, and other special characters.
+ */
 export function fileToUri(filePath: string): string {
-  const resolved = path.resolve(filePath);
-  if (process.platform === "win32") {
-    return `file:///${resolved.replace(/\\/g, "/")}`;
-  }
-  return `file://${resolved}`;
+  return pathToFileURL(filePath).href;
 }
 
-/** Convert a file:// URI to a file path. */
+/**
+ * Convert a file:// URI to a file path.
+ *
+ * Uses Node's `fileURLToPath` for standards-compliant decoding. Non-file
+ * URIs are passed through unchanged so consumers (such as LSP diagnostic
+ * handling) remain compatible with non-file URI schemes.
+ */
 export function uriToFile(uri: string): string {
   if (!uri.startsWith("file://")) return uri;
-  let filePath = decodeURIComponent(uri.slice(7));
-  if (
-    process.platform === "win32" &&
-    filePath.startsWith("/") &&
-    /^[A-Za-z]:/.test(filePath.slice(1))
-  ) {
-    filePath = filePath.slice(1);
+  try {
+    return fileURLToPath(uri);
+  } catch {
+    return uri;
   }
-  return filePath;
 }

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-action-menu.ts

@@ -34,6 +34,7 @@ export function buildActionMenu(field: ScopedFieldValue, scope: SettingsScope):
     if (choices.length > 0) {
       for (const choice of choices) menu.push({ value: `set:${choice}`, label: choice });
     } else if (field.field.kind === "number") menu.push({ value: "edit", label: "Edit value…" });
+    else if (field.field.kind === "string") menu.push({ value: "edit", label: "Edit value…" });
     else if (field.field.kind === "stringList") menu.push({ value: "edit", label: "Edit values…" });
     else if (field.field.kind === "modelPicker")
       menu.push({ value: "edit", label: "Choose model…" });

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts

@@ -86,6 +86,11 @@ export interface NumberField extends BaseField {
   values?: string[];
 }
 
+/** One free-form string. */
+export interface StringField extends BaseField {
+  kind: "string";
+}
+
 /** Comma-separated string list. */
 export interface StringListField extends BaseField {
   kind: "stringList";
@@ -164,6 +169,7 @@ export type SettingsField =
   | BoolField
   | EnumField
   | NumberField
+  | StringField
   | StringListField
   | ModelPickerField
   | CustomField;
@@ -248,6 +254,8 @@ export function formatValue(value: unknown, field: SettingsField): string {
       return value ? "on" : "off";
     case "number":
       return String(value ?? "");
+    case "string":
+      return typeof value === "string" && value ? value : "none";
     case "stringList": {
       const arr = Array.isArray(value) ? value : [];
       return arr.length > 0 ? arr.map(String).join(", ") : "none";
@@ -271,6 +279,7 @@ export function sourceBadge(displayValue: string, source: ValueSource): string {
 
 /** Format the value used to prefill editors and compare concrete choices. */
 export function formatEditValue(value: unknown, field: SettingsField): string {
+  if (field.kind === "string") return typeof value === "string" ? value : "";
   if (field.kind === "stringList") {
     const arr = Array.isArray(value) ? value : [];
     return arr.map(String).join(", ");

package/node_modules/@mrclrchtr/supi-core/src/settings.ts

@@ -26,6 +26,7 @@ export type {
   SettingsField,
   SettingsFieldAction,
   SettingsPersistedChange,
+  StringField,
   StringListField,
   ValueSource,
 } from "./settings/settings-schema.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "description": "SuPi code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "3.2.0"
+    "@mrclrchtr/supi-core": "4.1.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/api.ts

@@ -15,6 +15,14 @@ export type {
   StructuralProvider,
   StructuralResult,
 } from "./capability/types.ts";
+export type { CodeQueryResult } from "./query-result.ts";
+// Shared query-result constructors and contract
+export {
+  completedCodeQuery,
+  mapCodeQueryResult,
+  partialCodeQuery,
+  unavailableCodeQuery,
+} from "./query-result.ts";
 // Shared canonical types
 export type {
   CalleeDepth,
@@ -25,7 +33,9 @@ export type {
   CodeResult,
   CodeSymbol,
   ConfidenceMode,
+  DeclarationNesting,
   DisambiguationCandidate,
+  DocumentCodeSymbol,
   ExportData,
   FileEdit,
   ImportData,
@@ -37,7 +47,6 @@ export type {
   SourceRange,
   WorkspaceEdit,
 } from "./types.ts";
-export { normalizeRefactorOperation } from "./types.ts";
 export type { WorkspaceContext } from "./workspace/context.ts";
 // Workspace context
 export { createWorkspaceContext } from "./workspace/context.ts";

package/src/capability/types.ts

@@ -4,6 +4,7 @@
  * tree-sitter) advertise what they can do.
  */
 
+import type { CodeQueryResult } from "../query-result.ts";
 import type {
   CalleeDepth,
   CalleesData,
@@ -12,6 +13,7 @@ import type {
   CodePosition,
   CodeResult,
   CodeSymbol,
+  DocumentCodeSymbol,
   ExportData,
   ImportData,
   NodeAtData,
@@ -44,32 +46,30 @@ export type CapabilityState =
 /**
  * Semantic analysis capability backed by a language server (LSP).
  *
- * Methods return `null` to signal absence (unavailable / inactive) and
- * an array to signal a successful query (possibly empty).
+ * Every read query preserves whether collection completed, completed only
+ * partially, or was unavailable. Successful empty arrays and protocol-level
+ * null values are completed observations rather than capability failures.
  */
 export interface SemanticProvider {
-  references(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
-  implementation(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
-  documentSymbols(filePath: string): Promise<CodeSymbol[] | null>;
-  workspaceSymbols(query: string): Promise<CodeSymbol[] | null>;
+  references(filePath: string, position: CodePosition): Promise<CodeQueryResult<CodeLocation[]>>;
+  implementation(
+    filePath: string,
+    position: CodePosition,
+  ): Promise<CodeQueryResult<CodeLocation[]>>;
+  documentSymbols(filePath: string): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
+  workspaceSymbols(query: string): Promise<CodeQueryResult<CodeSymbol[]>>;
 
-  /**
-   * Optional definition capability. Returns the definition location(s) for
-   * the symbol at the given position. When the provider cannot produce
-   * definition info, returns `null`.
-   */
-  definition?(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
+  /** Optional definition capability with explicit completed-empty semantics. */
+  definition?(filePath: string, position: CodePosition): Promise<CodeQueryResult<CodeLocation[]>>;
 
   /**
-   * Optional hover capability. Returns a simplified type/signature info
-   * shape that does not depend on vscode-languageserver-types. When the
-   * provider cannot produce hover info (unavailable, unsupported file,
-   * no result at the given position), returns `null`.
+   * Optional hover capability. A completed `null` data value means the
+   * provider successfully found no hover at the requested point.
    */
   hover?(
     filePath: string,
     position: CodePosition,
-  ): Promise<{ contents: string; range?: SourceRange } | null>;
+  ): Promise<CodeQueryResult<{ contents: string; range?: SourceRange } | null>>;
 
   /**
    * Optional operation-aware refactor capability.
@@ -85,8 +85,8 @@ export interface SemanticProvider {
    * Optional rename capability. When present, the provider supports
    * precise semantic symbol-rename operations.
    *
-   * Kept as a low-level substrate helper for compatibility while the public
-   * tool surface still exposes a legacy `rename` alias.
+   * This remains a lower-level substrate helper for providers that expose
+   * symbol rename independently of their general refactor planner.
    */
   rename?(file: string, position: CodePosition, newName: string): Promise<RefactorResult>;
 
@@ -97,16 +97,6 @@ export interface SemanticProvider {
    * Kept as a low-level substrate helper and for lightweight introspection.
    */
   codeActions?(file: string, position: CodePosition): Promise<RefactorResult[]>;
-
-  /**
-   * Optional lightweight code action titles for display purposes.
-   * Returns simplified title/kind pairs at the given position.
-   * When the provider cannot produce code actions, returns `null`.
-   */
-  codeActionTitles?(
-    file: string,
-    position: CodePosition,
-  ): Promise<Array<{ title: string; kind?: string }> | null>;
 }
 
 /**

package/src/index.ts

@@ -12,9 +12,12 @@ export type {
   CapabilityState,
   CodeLocation,
   CodePosition,
+  CodeQueryResult,
   CodeResult,
   CodeSymbol,
   ConfidenceMode,
+  DeclarationNesting,
+  DocumentCodeSymbol,
   ExportData,
   ImportData,
   NodeAtData,
@@ -29,8 +32,11 @@ export type {
   WorkspaceContext,
 } from "./api.ts";
 export {
+  completedCodeQuery,
   createWorkspaceContext,
   getDefaultWorkspaceRuntime,
-  normalizeRefactorOperation,
+  mapCodeQueryResult,
+  partialCodeQuery,
+  unavailableCodeQuery,
   WorkspaceRuntime,
 } from "./api.ts";

package/src/query-result.ts

@@ -0,0 +1,42 @@
+/**
+ * Result of a read-only code-provider query.
+ *
+ * `completed` includes successful empty observations, such as an empty
+ * reference list or a protocol-level null hover. `partial` preserves usable
+ * data when a multi-provider query could not complete every branch.
+ * `unavailable` means the query did not establish a result.
+ */
+export type CodeQueryResult<T> =
+  | { readonly kind: "completed"; readonly data: T }
+  | { readonly kind: "partial"; readonly data: T; readonly reason: string }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+/** Construct a successfully completed code-query result, including empty data. */
+export function completedCodeQuery<T>(data: T): CodeQueryResult<T> {
+  return { kind: "completed", data };
+}
+
+/** Construct a usable but incomplete code-query result. */
+export function partialCodeQuery<T>(data: T, reason: string): CodeQueryResult<T> {
+  return { kind: "partial", data, reason };
+}
+
+/** Construct a code-query result that could not be established. */
+export function unavailableCodeQuery<T = never>(reason: string): CodeQueryResult<T> {
+  return { kind: "unavailable", reason };
+}
+
+/** Map completed or partial query data while preserving its availability state. */
+export function mapCodeQueryResult<T, U>(
+  result: CodeQueryResult<T>,
+  map: (data: T) => U,
+): CodeQueryResult<U> {
+  switch (result.kind) {
+    case "completed":
+      return completedCodeQuery(map(result.data));
+    case "partial":
+      return partialCodeQuery(map(result.data), result.reason);
+    case "unavailable":
+      return unavailableCodeQuery(result.reason);
+  }
+}

package/src/types.ts

@@ -34,6 +34,9 @@ export interface SymbolAnchor {
   character: number;
 }
 
+/** Provider-backed nesting evidence for a declaration reported within one document. */
+export type DeclarationNesting = "top-level" | "nested" | "unknown";
+
 /**
  * A discovered symbol / declaration.
  *
@@ -51,9 +54,21 @@ export interface CodeSymbol {
   file: string;
   declarationAnchor: SymbolAnchor;
   nameAnchor?: SymbolAnchor;
+  /** Named symbolic container when reported; absence does not prove top-level nesting. */
   container?: string | null;
 }
 
+/**
+ * A document-scoped declaration with explicit hierarchy evidence.
+ *
+ * `unknown` means the provider returned a flat observation without an actual
+ * hierarchy. A reported container name remains metadata and does not promote
+ * a flat observation to known nesting.
+ */
+export interface DocumentCodeSymbol extends CodeSymbol {
+  nesting: DeclarationNesting;
+}
+
 // ── Result types ───────────────────────────────────────────────────────
 
 /**
@@ -143,11 +158,8 @@ export interface WorkspaceEdit {
 
 /**
  * Supported refactor operation names for the current semantic planning path.
- *
- * `rename` is kept as a legacy alias for the public rename-only surface.
  */
 export type RefactorOperation =
-  | "rename"
   | "rename_symbol"
   | "extract_function"
   | "extract_variable"
@@ -156,13 +168,6 @@ export type RefactorOperation =
   | "update_imports"
   | "delete_dead_code";
 
-/** Normalize legacy refactor aliases to their canonical operation names. */
-export function normalizeRefactorOperation(
-  operation: RefactorOperation,
-): Exclude<RefactorOperation, "rename"> {
-  return operation === "rename" ? "rename_symbol" : operation;
-}
-
 /**
  * Operation-aware refactor planning request.
  *

package/node_modules/@mrclrchtr/supi-core/src/abort-utils.ts

@@ -1,31 +0,0 @@
-/**
- * Abort controller/signal utility helpers.
- *
- * @module
- */
-
-/**
- * Combine a caller-provided abort controller with a generation timeout signal.
- *
- * Returns the combined signal and a cleanup function that removes both
- * event listeners. Callers must invoke cleanup in a `finally` block
- * to avoid listener leaks.
- */
-export function combineAbortSignals(
-  abort: AbortController,
-  timeoutMs: number,
-): { signal: AbortSignal; cleanup: () => void } {
-  const timeoutSignal = AbortSignal.timeout(timeoutMs);
-  const combinedController = new AbortController();
-  const onAbort = () => combinedController.abort();
-  abort.signal.addEventListener("abort", onAbort, { once: true });
-  timeoutSignal.addEventListener("abort", onAbort, { once: true });
-
-  return {
-    signal: combinedController.signal,
-    cleanup: () => {
-      abort.signal.removeEventListener("abort", onAbort);
-      timeoutSignal.removeEventListener("abort", onAbort);
-    },
-  };
-}

package/node_modules/@mrclrchtr/supi-core/src/substrate-types.ts

@@ -1,11 +0,0 @@
-/** 0-based position used by LSP and code-intelligence internally. */
-export interface CodePosition {
-  line: number;
-  character: number;
-}
-
-/** Normalized location — flat replacement for LSP's nested Location/range shape. */
-export interface CodeLocation {
-  uri: string;
-  range: { start: CodePosition; end: CodePosition };
-}

package/node_modules/@mrclrchtr/supi-core/src/types.ts

@@ -1,2 +0,0 @@
-// supi-core types domain — shared substrate types (zero dependencies, pure types).
-export type { CodeLocation, CodePosition } from "./substrate-types.ts";