@mrclrchtr/supi-code-runtime 11.2.0 → 11.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "11.2.0",
+  "version": "11.4.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,

package/src/capability/types.ts

@@ -77,7 +77,9 @@ export interface SemanticProvider {
   ): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
   /**
    * Collect workspace symbols from routes that can contribute within the
-   * optional canonical path scopes.
+   * optional path scopes. Completeness is relative to those scopes, but data
+   * may include out-of-scope rows; consumers must filter rows themselves.
+   * Policy exclusions proven outside every scope do not make the query partial.
    */
   workspaceSymbols(
     query: string,

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/query-result.ts

@@ -3,8 +3,17 @@ export interface CodeQueryPartialMetadata {
   /** Automatic path-policy evidence removed from a collected result. */
   readonly automaticPathExclusion?: {
     readonly excludedCount: number;
+    /** Observed policy paths, not canonical navigation paths; retain aliases when presenting exclusions. */
     readonly examples: readonly string[];
   };
+  /**
+   * True when automatic path-policy exclusions are the only reason the result
+   * is partial: every contributing provider branch completed and no coverage
+   * gap was observed. Excluded rows matched paths the workspace policy treats
+   * as out of automatic scope, so the retained rows are the complete in-policy
+   * answer.
+   */
+  readonly exclusionOnly?: boolean;
 }
 
 /**

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 ───────────────────────────────────────────────────────