@mrclrchtr/supi-code-runtime 11.3.0 → 12.0.0

package/package.json

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

package/src/api.ts

@@ -14,6 +14,7 @@ export type {
   StructuralProvider,
   StructuralResult,
 } from "./capability/types.ts";
+export { childDeclarationLevel } from "./declaration-level.ts";
 export type {
   CFamilyExtension,
   CFamilyFileAssociationResolver,
@@ -50,7 +51,7 @@ export type {
   CodeResult,
   CodeSymbol,
   ConfidenceMode,
-  DeclarationNesting,
+  DeclarationLevel,
   DisambiguationCandidate,
   DocumentCodeSymbol,
   DocumentEditPrecondition,
@@ -59,6 +60,7 @@ export type {
   ImportData,
   NodeAtData,
   OutlineData,
+  RefactorActionIdentity,
   RefactorOperation,
   RefactorRequest,
   RefactorResult,

package/src/declaration-level.ts

@@ -0,0 +1,34 @@
+import type { DeclarationLevel } from "./types.ts";
+
+/** Declarations whose body holds statements, so nested declarations are local to it. */
+const FUNCTION_LIKE_KINDS = new Set(["function", "method", "constructor"]);
+/** Bindings whose value may be a function (locals) or an object literal (members). */
+const VALUE_BINDING_KINDS = new Set(["variable", "constant", "property", "field"]);
+/** Kinds that name an entry of an object, type, or enum rather than a statement-level binding. */
+const MEMBER_ENTRY_KINDS = new Set(["property", "field", "method", "enummember", "key", "event"]);
+
+/**
+ * Level of a declaration reported directly inside `parent`.
+ *
+ * Inside a local declaration everything stays local. A function, method, or
+ * constructor makes its nested declarations local. A variable, constant,
+ * property, or field holds either a function body (nested bindings are local)
+ * or an object literal (nested properties and methods are members). Every
+ * other container — class, interface, enum, struct, namespace, module, or a
+ * document section — makes its nested declarations members.
+ *
+ * Kinds compare case-insensitively, so LSP SymbolKind names and Tree-sitter
+ * outline kinds share one rule.
+ */
+export function childDeclarationLevel(
+  parent: { readonly kind: string | null; readonly level: DeclarationLevel },
+  childKind: string | null,
+): Exclude<DeclarationLevel, "top-level" | "unknown"> {
+  if (parent.level === "local") return "local";
+  const parentKind = parent.kind?.toLowerCase() ?? "";
+  if (FUNCTION_LIKE_KINDS.has(parentKind)) return "local";
+  if (VALUE_BINDING_KINDS.has(parentKind)) {
+    return MEMBER_ENTRY_KINDS.has(childKind?.toLowerCase() ?? "") ? "member" : "local";
+  }
+  return "member";
+}

package/src/types.ts

@@ -34,8 +34,16 @@ export interface SymbolAnchor {
   character: number;
 }
 
-/** Provider-backed nesting evidence for a declaration reported within one document. */
-export type DeclarationNesting = "top-level" | "nested" | "unknown";
+/**
+ * Where a declaration sits within its file, as reported by a provider.
+ *
+ * - `top-level`: directly in the file, not inside another declaration.
+ * - `member`: directly inside a class, interface, enum, struct, namespace,
+ *   module, or object literal (methods, fields, properties, enum members).
+ * - `local`: inside the body of a function, method, or constructor.
+ * - `unknown`: the provider reported a flat symbol list without hierarchy.
+ */
+export type DeclarationLevel = "top-level" | "member" | "local" | "unknown";
 
 /**
  * A discovered symbol / declaration.
@@ -54,7 +62,7 @@ export interface CodeSymbol {
   file: string;
   declarationAnchor: SymbolAnchor;
   nameAnchor?: SymbolAnchor;
-  /** Named symbolic container when reported; absence does not prove top-level nesting. */
+  /** Named enclosing declaration when reported; absence does not prove a top-level declaration. */
   container?: string | null;
 }
 
@@ -63,10 +71,10 @@ export interface CodeSymbol {
  *
  * `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.
+ * a flat observation to a known level.
  */
 export interface DocumentCodeSymbol extends CodeSymbol {
-  nesting: DeclarationNesting;
+  level: DeclarationLevel;
 }
 
 // ── Result types ───────────────────────────────────────────────────────
@@ -185,31 +193,53 @@ export interface WorkspaceEdit {
 }
 
 /**
- * Supported refactor operation names for the current semantic planning path.
- */
-export type RefactorOperation =
-  | "rename_symbol"
-  | "extract_function"
-  | "extract_variable"
-  | "rename_file"
-  | "move_file"
-  | "update_imports"
-  | "delete_dead_code";
-
-/**
- * Operation-aware refactor planning request.
+ * Operation-aware refactor planning request. Each operation carries only the
+ * scope it needs:
+ *
+ * - `rename_symbol`: one symbol position and the new name.
+ * - `code_action`: one file range and a CodeActionKind prefix under `refactor`.
+ * - `source_action`: one whole file and a CodeActionKind prefix under `source`.
  *
- * Consumers provide a target file/position plus operation-specific options.
- * File/resource operations remain requestable so providers can reject them
- * explicitly and honestly until shared workspace-edit resource ops exist.
+ * `kind` matches the requested kind and its dotted sub-kinds. `title`, when
+ * present, selects one action by its exact title.
  */
-export interface RefactorRequest {
-  operation: RefactorOperation;
-  file: string;
-  position: CodePosition;
-  range?: SourceRange;
-  newName?: string;
-  destination?: string;
+export type RefactorRequest =
+  | {
+      operation: "rename_symbol";
+      file: string;
+      position: CodePosition;
+      newName: string;
+    }
+  | {
+      operation: "code_action";
+      file: string;
+      range: SourceRange;
+      kind: string;
+      title?: string;
+    }
+  | {
+      operation: "source_action";
+      file: string;
+      kind: string;
+      title?: string;
+    };
+
+/** Supported refactor operation names. */
+export type RefactorOperation = RefactorRequest["operation"];
+
+/** The code action selected for a precise code- or source-action plan. */
+export interface RefactorActionIdentity {
+  /** Server-reported CodeActionKind. */
+  kind: string;
+  /** Server-reported action title. */
+  title: string;
+  /**
+   * How the edits were obtained: `edit` from the action itself (after
+   * `codeAction/resolve` when needed), or `captured-command` from the single
+   * `workspace/applyEdit` the server pushed while running the action's command.
+   * Captured edits were refused, never applied.
+   */
+  provenance?: "edit" | "captured-command";
 }
 
 /**
@@ -220,6 +250,10 @@ export interface DisambiguationCandidate {
   file?: string;
   line?: number;
   character?: number;
+  /** Server-reported CodeActionKind, for code-action candidates. */
+  kind?: string;
+  /** Exact action title to pass back as `title`, for code-action candidates. */
+  title?: string;
 }
 
 /**
@@ -233,6 +267,8 @@ export type RefactorResult =
   | {
       kind: "precise";
       edits: WorkspaceEdit;
+      /** The selected code action, for code- and source-action plans. */
+      action?: RefactorActionIdentity;
       /** Provider roots authorized by the semantic route. Consumers canonicalize before storage. */
       authorizedMutationRoots: string[];
     }