ashlr-plugin 1.36.4

package/servers/_ast-refactor/extract-function.ts

@@ -0,0 +1,357 @@
+/**
+ * _ast-refactor/extract-function.ts — AST-aware extract-function operation.
+ *
+ * Exports:
+ *   planExtractFunction — plan a byte-range extract into a new function
+ *
+ * Three shapes of extract (v1.18.1):
+ *   1. Single expression → `function extracted() { return <expr>; }` +
+ *      call site replaces range with `extracted(args)`.
+ *   2. Statements whose internals are not read after the range → no return;
+ *      call site becomes `extracted(args);` (bare expression statement).
+ *   3. Statements where exactly one value declared-or-written-inside is read
+ *      later in the enclosing scope → `return x;` and call site
+ *      `const x = extracted(args);` (or `let` if the binding was reassigned).
+ *      Multiple outputs → `return { a, b };` + `const { a, b } = extracted(args);`.
+ *
+ * Constraints:
+ *   - Refuses ranges containing `return`, `throw`, `await`, or `yield`.
+ *   - Params are typed `unknown` (no type-checker).
+ *   - Inserts extracted function BEFORE the enclosing top-level scope.
+ */
+
+import { extractIdentifiers, walkNodes } from "../_ast-helpers";
+import type { ParseResult } from "../_ast-helpers";
+import type Parser from "web-tree-sitter";
+import {
+  validateIdentifier,
+  isDeclarationSite,
+  type RangeEdit,
+} from "./_shared";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ExtractFunctionOptions {
+  newFunctionName: string;
+  /** Byte range of the expression/statement block to extract. */
+  start: number;
+  end: number;
+}
+
+export interface ExtractFunctionResult {
+  ok: boolean;
+  edits?: RangeEdit[];
+  source?: string;
+  reason?: string;
+  /** Soft warnings the caller should surface to the user (only set on ok:true). */
+  warnings?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * File-local extract-function with return-value detection (v1.18.1).
+ *
+ * Outputs are always written as `const { a, b } = …` destructuring so the
+ * call-site stays readable. If the binding already existed and was only
+ * reassigned (not declared) inside the range, we emit `({ a, b } = …)` form
+ * instead to avoid redeclaration — flagged as a warning for now since we
+ * don't yet distinguish declaration vs. re-assignment rigorously.
+ */
+export function planExtractFunction(
+  parsed: ParseResult,
+  options: ExtractFunctionOptions,
+): ExtractFunctionResult {
+  const { tree, source } = parsed;
+  const { newFunctionName, start, end } = options;
+
+  // Validate new function name
+  const nameErr = validateIdentifier(newFunctionName);
+  if (nameErr) return { ok: false, reason: nameErr };
+
+  if (start >= end) {
+    return { ok: false, reason: "extract range is empty (start >= end)" };
+  }
+  if (start < 0 || end > source.length) {
+    return { ok: false, reason: `extract range [${start}, ${end}] is out of source bounds` };
+  }
+
+  const body = source.slice(start, end);
+
+  if (/\breturn\b/.test(body)) {
+    return { ok: false, reason: "extracted range contains 'return' — extract does not support early returns from the target block" };
+  }
+  if (/\bthrow\b/.test(body)) {
+    return { ok: false, reason: "extracted range contains 'throw' — extract does not support throw statements" };
+  }
+  if (/\bawait\b/.test(body)) {
+    return { ok: false, reason: "extracted range contains 'await' — extract does not support async/await (the enclosing fn would need to become async too)" };
+  }
+  if (/\byield\b/.test(body)) {
+    return { ok: false, reason: "extracted range contains 'yield' — extract does not support generator yields" };
+  }
+
+  // Find the smallest node that fully contains the range
+  let targetNode: Parser.SyntaxNode | null = null;
+  walkNodes(tree, (n) => {
+    if (n.startIndex <= start && n.endIndex >= end) {
+      if (targetNode === null || (n.endIndex - n.startIndex) < (targetNode.endIndex - targetNode.startIndex)) {
+        targetNode = n;
+      }
+    }
+  });
+
+  if (!targetNode) {
+    return { ok: false, reason: "could not find an enclosing node for the given range" };
+  }
+  const tn = targetNode as Parser.SyntaxNode;
+
+  const EXPRESSION_TYPES = new Set([
+    "binary_expression", "call_expression", "member_expression",
+    "ternary_expression", "unary_expression", "update_expression",
+    "parenthesized_expression", "identifier", "property_identifier",
+    "number", "string", "template_string", "true", "false", "null",
+    "object", "array", "arrow_function", "new_expression",
+    "subscript_expression", "type_assertion", "as_expression",
+    "non_null_expression", "regex",
+  ]);
+  const STATEMENT_TYPES = new Set([
+    "expression_statement", "lexical_declaration", "variable_declaration",
+    "if_statement", "for_statement", "for_in_statement", "while_statement",
+    "do_statement", "switch_statement", "try_statement", "block",
+    "statement_block", "assignment_expression",
+  ]);
+
+  const isExpression = EXPRESSION_TYPES.has(tn.type);
+  const isStatementish = STATEMENT_TYPES.has(tn.type);
+
+  if (!isExpression && !isStatementish) {
+    return {
+      ok: false,
+      reason: `range encloses node type '${tn.type}' which is neither an expression nor a statement — extract not supported for this shape`,
+    };
+  }
+
+  // --- Identifier analysis ------------------------------------------------
+  const allRefs = extractIdentifiers(tree, source);
+  const refsInRange = allRefs.filter(
+    (r) => r.kind === "value" && r.range[0] >= start && r.range[1] <= end,
+  );
+
+  // Names declared/written inside the range (via variable declarators, assignments,
+  // destructuring patterns, parameter defaults etc.).
+  const declaredInRange = new Set<string>();
+  walkNodes(tree, (n) => {
+    if (n.startIndex < start || n.endIndex > end) return;
+    if (n.type === "identifier" && isDeclarationSite(n, "value")) {
+      declaredInRange.add(n.text);
+    }
+  });
+  // Names written (assigned / updated) inside the range — captures non-declaration
+  // reassignment cases like `x = 5;` / `x += 1;`. We track both the declarations
+  // and these writes to decide what could possibly be "output" of the extracted fn.
+  const writtenInRange = new Set<string>(declaredInRange);
+  walkNodes(tree, (n) => {
+    if (n.startIndex < start || n.endIndex > end) return;
+    if (n.type === "assignment_expression") {
+      const lhs = n.childForFieldName ? n.childForFieldName("left") : n.namedChild(0);
+      if (lhs && lhs.type === "identifier") writtenInRange.add(lhs.text);
+    }
+    if (n.type === "update_expression") {
+      const arg = n.namedChild(0);
+      if (arg && arg.type === "identifier") writtenInRange.add(arg.text);
+    }
+  });
+
+  // Parameters = identifiers referenced in range but not *declared* in range
+  // and not the new function name itself. (We use declaredInRange, not
+  // writtenInRange — a plain `x = 5` inside the range where `x` came from
+  // outside is an outer-scope reference; `x` must be a parameter AND an output.)
+  const paramNames = new Set<string>();
+  for (const ref of refsInRange) {
+    if (!declaredInRange.has(ref.name) && ref.name !== newFunctionName) {
+      paramNames.add(ref.name);
+    }
+  }
+  const params = [...paramNames].map((p) => `${p}: unknown`);
+  const paramCall = [...paramNames].join(", ");
+
+  // --- Return-value detection (statement form only) ----------------------
+  // Find the enclosing scope to check "used after range". Scope = nearest
+  // function/method body or root.
+  const enclosingScope = findEnclosingScope(tree, start, end);
+  const readsAfterRange = new Set<string>();
+  if (isStatementish && enclosingScope) {
+    const scopeStart = enclosingScope.startIndex;
+    const scopeEnd = enclosingScope.endIndex;
+    for (const ref of allRefs) {
+      if (ref.kind !== "value") continue;
+      if (ref.range[0] < end) continue; // must be AFTER the range
+      if (ref.range[0] >= scopeEnd) continue; // must be within enclosing scope
+      if (ref.range[0] < scopeStart) continue;
+      if (writtenInRange.has(ref.name)) {
+        // Skip if this "read" is itself a declaration site (e.g., re-declares
+        // the name in a later block) — that's not a real read.
+        readsAfterRange.add(ref.name);
+      }
+    }
+  }
+
+  // Outputs that need to be returned from the extracted fn.
+  const outputs = [...readsAfterRange].sort();
+  const declaredOutputs = outputs.filter((n) => declaredInRange.has(n));
+  const reassignedOutputs = outputs.filter((n) => !declaredInRange.has(n));
+
+  // --- Build extracted function body ---------------------------------------
+  let funcBody: string;
+  let callSiteExpr: string;
+  const warnings: string[] = [];
+
+  if (isExpression) {
+    // Single expression extract — wrap in return.
+    funcBody = `  return ${body.trim()};`;
+    callSiteExpr = `${newFunctionName}(${paramCall})`;
+  } else if (outputs.length === 0) {
+    // Statement(s) with no outputs.
+    funcBody = body.replace(/^\n|\n$/g, "").split("\n").map((l) => "  " + l).join("\n");
+    callSiteExpr = `${newFunctionName}(${paramCall})`;
+  } else if (outputs.length === 1) {
+    const name = outputs[0]!;
+    const indented = body.replace(/^\n|\n$/g, "").split("\n").map((l) => "  " + l).join("\n");
+    funcBody = `${indented}\n  return ${name};`;
+    if (declaredInRange.has(name)) {
+      callSiteExpr = `const ${name} = ${newFunctionName}(${paramCall})`;
+    } else {
+      // Variable is outer-scope — reassign via expression so no redeclare.
+      callSiteExpr = `${name} = ${newFunctionName}(${paramCall})`;
+    }
+  } else {
+    // Multiple outputs → object return.
+    const indented = body.replace(/^\n|\n$/g, "").split("\n").map((l) => "  " + l).join("\n");
+    funcBody = `${indented}\n  return { ${outputs.join(", ")} };`;
+    if (reassignedOutputs.length > 0 && declaredOutputs.length === 0) {
+      // All bindings pre-exist; destructure-assign.
+      callSiteExpr = `({ ${outputs.join(", ")} } = ${newFunctionName}(${paramCall}))`;
+    } else if (declaredOutputs.length === outputs.length) {
+      // All freshly declared inside range — safe to `const`-destructure.
+      callSiteExpr = `const { ${outputs.join(", ")} } = ${newFunctionName}(${paramCall})`;
+    } else {
+      // Mixed: some declared inside range, some outer-scope reassigned.
+      // A `const { a, b } = ...` destructure would shadow the outer-scope names
+      // of the reassigned bindings. Detect this and refuse rather than emit a
+      // silent advisory.
+      //
+      // Shadowing detector: for every name in reassignedOutputs, check whether
+      // it is already declared (or is a parameter) in the enclosing scope
+      // *outside* the extraction range. If so, `const { name } = ...` at the
+      // call site would introduce a new binding that shadows it.
+      const enclosingScopeBindings = new Set<string>();
+      if (enclosingScope) {
+        walkNodes(tree, (n) => {
+          // Only look at nodes inside the enclosing scope but outside the range
+          if (n.startIndex >= start && n.startIndex < end) return;
+          if (n.startIndex < enclosingScope.startIndex) return;
+          if (n.startIndex >= enclosingScope.endIndex) return;
+          if (n.type === "identifier" && isDeclarationSite(n, "value")) {
+            enclosingScopeBindings.add(n.text);
+          }
+          // Enclosing function parameters
+          if (
+            n.type === "identifier" &&
+            n.parent?.type === "formal_parameters"
+          ) {
+            enclosingScopeBindings.add(n.text);
+          }
+          // Destructuring params: { a, b } in parameter position
+          if (
+            n.type === "identifier" &&
+            n.parent?.type === "shorthand_property_identifier_pattern"
+          ) {
+            enclosingScopeBindings.add(n.text);
+          }
+        });
+      }
+      const shadowedNames = reassignedOutputs.filter((n) => enclosingScopeBindings.has(n));
+      if (shadowedNames.length > 0) {
+        return {
+          ok: false,
+          reason: `extract-function: would shadow outer-scope binding${shadowedNames.length > 1 ? "s" : ""} [${shadowedNames.join(", ")}] — use destructure-assign form manually or rename the extracted outputs.`,
+        };
+      }
+      // No detected shadowing — emit const destructure and note the mixed shape.
+      callSiteExpr = `const { ${outputs.join(", ")} } = ${newFunctionName}(${paramCall})`;
+    }
+  }
+
+  // Terminator: statement form needs a trailing `;`; expression-replacing
+  // form that's replacing an expression inside a larger expression shouldn't
+  // append one.
+  const replacement = isExpression ? callSiteExpr : `${callSiteExpr};`;
+
+  // --- Insert location ----------------------------------------------------
+  const root = tree.rootNode;
+  let insertBeforeNode: Parser.SyntaxNode | null = null;
+  for (let i = 0; i < root.childCount; i++) {
+    const child = root.child(i)!;
+    if (child.startIndex <= start && child.endIndex >= end) {
+      insertBeforeNode = child;
+      break;
+    }
+    if (child.startIndex > start) break;
+  }
+  const insertAt = insertBeforeNode ? insertBeforeNode.startIndex : 0;
+
+  const funcText = `function ${newFunctionName}(${params.join(", ")}) {\n${funcBody}\n}\n\n`;
+
+  const edits: RangeEdit[] = [
+    { start: insertAt, end: insertAt, replacement: funcText },
+    { start, end, replacement },
+  ];
+
+  if (insertAt > start && insertAt < end) {
+    return { ok: false, reason: "internal error: insert point overlaps with extracted range" };
+  }
+
+  return { ok: true, edits, source, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// findEnclosingScope
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the nearest enclosing function/method body or arrow function scope
+ * for a byte range. Used by extract-function to decide the "used after"
+ * analysis boundary. Falls back to the root.
+ */
+function findEnclosingScope(
+  tree: Parser.Tree,
+  start: number,
+  end: number,
+): Parser.SyntaxNode {
+  const SCOPE_TYPES = new Set([
+    "function_declaration",
+    "function_expression",
+    "arrow_function",
+    "method_definition",
+    "generator_function_declaration",
+    "generator_function",
+  ]);
+  let best: Parser.SyntaxNode = tree.rootNode;
+  let bestSize = Infinity;
+  walkNodes(tree, (n) => {
+    if (!SCOPE_TYPES.has(n.type)) return;
+    if (n.startIndex <= start && n.endIndex >= end) {
+      const size = n.endIndex - n.startIndex;
+      if (size < bestSize) {
+        best = n;
+        bestSize = size;
+      }
+    }
+  });
+  return best;
+}

package/servers/_ast-refactor/file-local-rename.ts

@@ -0,0 +1,172 @@
+/**
+ * _ast-refactor/file-local-rename.ts — File-local AST rename operations.
+ *
+ * Exports:
+ *   planRenameInFile     — load + parse + plan rename for a file path
+ *   planRenameFromParsed — pure variant operating on a pre-parsed tree (test-friendly)
+ *
+ * Invariants:
+ *   - Never writes the file. Returns byte-range edits; the caller applies them.
+ *   - Always refuses rather than producing a subtly-wrong rename.
+ *   - Pure AST logic — no file-system side-effects beyond reading the source.
+ */
+
+import { parseFile, extractIdentifiers } from "../_ast-helpers";
+import type { ParseResult } from "../_ast-helpers";
+import {
+  applyRangeEdits as _applyRangeEdits, // re-exported via facade
+  validateIdentifier,
+  isDeclarationSite,
+  rangesToNodes,
+  type RangeEdit,
+  type RefactorKind,
+} from "./_shared";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type { RangeEdit, RefactorKind };
+
+export interface RenameInFileOptions {
+  /**
+   * If set, only rename identifiers of this kind. Defaults to "value".
+   * Use `"type"` to rename a type-only symbol (interface, type alias, etc.).
+   */
+  kind?: RefactorKind;
+  /**
+   * If true, ignore the shadowing guard and rename anyway. Default false.
+   * Reserved for tests and advanced callers who've already verified safety.
+   */
+  force?: boolean;
+}
+
+export type RenameInFileResult =
+  | {
+      ok: true;
+      edits: RangeEdit[];
+      warnings: string[];
+      references: number;
+      /**
+       * The exact source string the tree was parsed from. Callers applying
+       * the edits MUST use this string (not a fresh re-read of the file) so
+       * byte offsets stay aligned — a concurrent write between the initial
+       * read and the rewrite would otherwise produce silently corrupt output.
+       */
+      source: string;
+    }
+  | {
+      ok: false;
+      reason: string;
+      warnings?: string[];
+    };
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Plan a file-local rename.
+ *
+ * Loads + parses the file, collects identifier references matching
+ * `{name, kind}`, checks the shadowing guard, and returns a list of byte
+ * ranges to replace with `newName`.
+ */
+export async function planRenameInFile(
+  filePath: string,
+  oldName: string,
+  newName: string,
+  options: RenameInFileOptions = {},
+): Promise<RenameInFileResult> {
+  const kind: RefactorKind = options.kind ?? "value";
+
+  const nameError = validateIdentifier(newName);
+  if (nameError) return { ok: false, reason: nameError };
+  if (oldName === newName) {
+    return { ok: false, reason: "old and new names are identical" };
+  }
+
+  const parsed = await parseFile(filePath);
+  if (!parsed) {
+    return {
+      ok: false,
+      reason: "unsupported language or grammar not wired (ashlr__edit_structural supports .ts/.tsx/.js/.jsx today)",
+    };
+  }
+
+  return planRenameFromParsed(parsed, oldName, newName, kind, options.force === true);
+}
+
+/**
+ * Pure variant of {@link planRenameInFile} that operates on a pre-parsed
+ * tree. Convenient for tests.
+ */
+export function planRenameFromParsed(
+  parsed: ParseResult,
+  oldName: string,
+  newName: string,
+  kind: RefactorKind,
+  force = false,
+): RenameInFileResult {
+  const { tree, source } = parsed;
+
+  const allRefs = extractIdentifiers(tree, source);
+  const matches = allRefs.filter((r) => r.name === oldName && r.kind === kind);
+
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      reason: `no ${kind}-position identifier named '${oldName}' found in file`,
+    };
+  }
+
+  // Shadowing guard: count unique declaration sites. >1 means the same name
+  // introduces multiple bindings (e.g., outer function + inner parameter).
+  // Until we have proper scope resolution, refuse rather than silently
+  // collide all of them.
+  const warnings: string[] = [];
+  const declarationMatches = rangesToNodes(tree, matches.map((m) => m.range)).filter(
+    (n) => isDeclarationSite(n, kind),
+  );
+  const declarationCount = declarationMatches.length;
+
+  if (declarationCount > 1 && !force) {
+    return {
+      ok: false,
+      reason: `'${oldName}' has ${declarationCount} declaration sites in this file — rename refused to avoid shadowing collisions. Rename each scope individually or pass force:true after verifying safety.`,
+    };
+  }
+  if (declarationCount === 0) {
+    warnings.push(
+      `no ${kind}-position declaration of '${oldName}' detected — identifier may be bound in an outer scope (imported / global). Rename applied only to the occurrences in this file.`,
+    );
+  }
+
+  // Check the new name doesn't already collide with a declaration of the
+  // same kind in the file.
+  if (!force) {
+    const collision = allRefs.some(
+      (r) => r.name === newName && r.kind === kind,
+    );
+    if (collision) {
+      return {
+        ok: false,
+        reason: `'${newName}' already exists as a ${kind}-position identifier in this file — would collide. Rename to a different name, or pass force:true.`,
+      };
+    }
+  }
+
+  const edits: RangeEdit[] = matches.map((m) => ({
+    start: m.range[0],
+    end: m.range[1],
+    replacement: newName,
+  }));
+
+  return {
+    ok: true,
+    edits,
+    warnings,
+    references: matches.length,
+    source,
+  };
+}

package/servers/_ast-refactor.ts

@@ -0,0 +1,41 @@
+/**
+ * _ast-refactor.ts — Facade re-exporting the public API of the AST-refactor
+ * module family (Track D, v1.24).
+ *
+ * The implementation has been decomposed into focused sub-modules:
+ *   _ast-refactor/_shared.ts           — common types, helpers, applyRangeEdits
+ *   _ast-refactor/file-local-rename.ts — planRenameInFile + planRenameFromParsed
+ *   _ast-refactor/cross-file-rename.ts — planCrossFileRename + applyCrossFileRenameEdits
+ *   _ast-refactor/extract-function.ts  — planExtractFunction
+ *
+ * All public signatures are identical to the monolithic v1.18.1 version.
+ * Callers (edit-structural-server-handlers.ts, tests) are unaffected.
+ */
+
+export type { RangeEdit, RefactorKind } from "./_ast-refactor/_shared";
+export { applyRangeEdits } from "./_ast-refactor/_shared";
+
+export type {
+  RenameInFileOptions,
+  RenameInFileResult,
+} from "./_ast-refactor/file-local-rename";
+export {
+  planRenameInFile,
+  planRenameFromParsed,
+} from "./_ast-refactor/file-local-rename";
+
+export type {
+  CrossFileRenameOptions,
+  CrossFileFileEdit,
+  CrossFileRenameResult,
+} from "./_ast-refactor/cross-file-rename";
+export {
+  planCrossFileRename,
+  applyCrossFileRenameEdits,
+} from "./_ast-refactor/cross-file-rename";
+
+export type {
+  ExtractFunctionOptions,
+  ExtractFunctionResult,
+} from "./_ast-refactor/extract-function";
+export { planExtractFunction } from "./_ast-refactor/extract-function";

package/servers/_ast-skeleton.ts

@@ -0,0 +1,107 @@
+/**
+ * _ast-skeleton.ts — AST-truncated skeleton renderer for ashlr__read.
+ *
+ * For large wired-language files (TS/TSX/JS), instead of snipCompact head+tail
+ * truncation we return a SKELETON: import/export-from lines verbatim at the top,
+ * followed by every top-level symbol's docstring + signature + a one-line body
+ * elision marker.  Typical savings: 60–80% vs full source.
+ *
+ * Contract:
+ *   - Returns null on ANY failure — callers MUST fall through to snipCompact.
+ *   - Never throws.
+ *   - Deterministic (no Date.now / Math.random).
+ */
+
+import { resolveLanguage } from "./_ast-languages";
+import { splitFileIntoChunks } from "./_ast-chunker";
+
+/** Languages fully wired for AST skeleton rendering. */
+const WIRED_SKELETON_LANGUAGES = new Set(["typescript", "tsx", "javascript"]);
+
+/** Regex that matches import / export-from / re-export lines. */
+const IMPORT_EXPORT_RE =
+  /^\s*(import\b|export\s+(?:\*|\{|type\b).*\bfrom\b|export\s+\{)/;
+
+/**
+ * Render an AST skeleton for `filePath`.
+ *
+ * Returns null when:
+ *   - Language is not in the wired JS/TS set.
+ *   - splitFileIntoChunks returns null or an empty array.
+ *   - Any unexpected error occurs.
+ */
+export async function renderAstSkeleton(
+  filePath: string,
+  content: string,
+): Promise<string | null> {
+  try {
+    // Guard: only wired languages get AST treatment.
+    const lang = resolveLanguage(filePath);
+    if (!lang || !WIRED_SKELETON_LANGUAGES.has(lang)) return null;
+
+    // Parse the file into top-level chunks.
+    const chunks = await splitFileIntoChunks(filePath);
+    if (!chunks || chunks.length === 0) return null;
+
+    // -----------------------------------------------------------------------
+    // Extract import / export-from lines via line scan (no AST needed — these
+    // are always verbatim and the regex is reliable for TS/JS).
+    // -----------------------------------------------------------------------
+    const importLines: string[] = [];
+    for (const line of content.split("\n")) {
+      if (IMPORT_EXPORT_RE.test(line)) {
+        importLines.push(line);
+      }
+    }
+
+    // -----------------------------------------------------------------------
+    // Build the skeleton body: one block per chunk in source order.
+    // -----------------------------------------------------------------------
+    const parts: string[] = [];
+
+    // Import block at the top (if any).
+    if (importLines.length > 0) {
+      parts.push(importLines.join("\n"));
+      parts.push(""); // blank separator
+    }
+
+    // One block per chunk, preserving source order (splitFileIntoChunks already
+    // returns chunks in tree-sitter traversal = source order).
+    for (const chunk of chunks) {
+      const block: string[] = [];
+      if (chunk.docstring) {
+        block.push(chunk.docstring);
+      }
+      // Enums are small and their MEMBERS are the signal (the whole point of an
+      // enum is its variants), so render them in full rather than eliding the
+      // body. Everything else gets signature + a body-elision marker.
+      if (chunk.kind === "enum") {
+        block.push(content.slice(chunk.startByte, chunk.endByte));
+      } else if (chunk.kind === "class" && chunk.members && chunk.members.length > 0) {
+        // Show the class shape: header + member signatures (method bodies elided).
+        block.push(`${chunk.signature} {`);
+        for (const m of chunk.members) block.push(`  ${m}`);
+        block.push("}");
+      } else {
+        block.push(chunk.signature);
+        block.push(
+          `  // … body elided (L${chunk.startLine}–L${chunk.endLine})`,
+        );
+      }
+      parts.push(block.join("\n"));
+    }
+
+    // -----------------------------------------------------------------------
+    // Footer note so agents know how to recover the full file.
+    // -----------------------------------------------------------------------
+    parts.push(
+      "\n// [ast-skeleton] Signatures only — bodies elided for token efficiency." +
+        "\n// To read the full file: pass bypassSummary:true to ashlr__read.",
+    );
+
+    return parts.join("\n\n");
+  } catch {
+    // Tree-sitter can timeout on macOS cold-start; any other error also falls back.
+    return null;
+  }
+}