ast-mcp-server 0.4.0 → 0.5.0

package/dist/services/scaffold.js

@@ -0,0 +1,241 @@
+import { LanguageVariant, Node, Scope, ScriptTarget, SyntaxKind, ts, } from "ts-morph";
+import { buildFileOutline } from "./outline.js";
+function assertIdentifier(value, label) {
+    const scanner = ts.createScanner(ScriptTarget.Latest, false, LanguageVariant.Standard, value);
+    const valid = scanner.scan() === SyntaxKind.Identifier && scanner.scan() === SyntaxKind.EndOfFileToken;
+    if (!valid)
+        throw new Error(`${label} must be a valid TypeScript identifier.`);
+}
+function assertBoundedText(value, label, maximum = 10_000) {
+    if (value.trim().length === 0)
+        throw new Error(`${label} must not be empty.`);
+    if (value.length > maximum)
+        throw new Error(`${label} exceeds ${maximum} characters.`);
+}
+function parseFragment(sourceText, label) {
+    const sourceFile = ts.createSourceFile("__ast_scaffold_fragment.ts", sourceText, ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const diagnostics = sourceFile.parseDiagnostics;
+    if (diagnostics.length > 0) {
+        throw new Error(`${label} is not valid TypeScript in its declaration position.`);
+    }
+    return sourceFile;
+}
+function assertTypeFragment(value, label) {
+    assertBoundedText(value, label);
+    const sourceFile = parseFragment(`type __ScaffoldType = ${value};`, label);
+    const declaration = sourceFile.statements[0];
+    if (sourceFile.statements.length !== 1 ||
+        !declaration ||
+        !ts.isTypeAliasDeclaration(declaration) ||
+        declaration.type.getText(sourceFile) !== value.trim()) {
+        throw new Error(`${label} must contain exactly one TypeScript type.`);
+    }
+}
+function assertHeritageFragment(value, label, token) {
+    assertBoundedText(value, label);
+    const keyword = token === SyntaxKind.ExtendsKeyword ? "extends" : "implements";
+    const sourceFile = parseFragment(`class __Scaffold ${keyword} ${value} {}`, label);
+    const declaration = sourceFile.statements[0];
+    const clause = declaration && ts.isClassDeclaration(declaration)
+        ? declaration.heritageClauses?.find((item) => item.token === token)
+        : undefined;
+    if (sourceFile.statements.length !== 1 ||
+        !clause ||
+        clause.types.length !== 1 ||
+        clause.types[0]?.getText(sourceFile) !== value.trim()) {
+        throw new Error(`${label} must contain exactly one TypeScript heritage expression.`);
+    }
+}
+function assertInitializerFragment(value, label) {
+    assertBoundedText(value, label);
+    const sourceFile = parseFragment(`class __Scaffold { value = ${value}; }`, label);
+    const declaration = sourceFile.statements[0];
+    const members = declaration && ts.isClassDeclaration(declaration) ? declaration.members : [];
+    const property = members[0];
+    if (sourceFile.statements.length !== 1 ||
+        members.length !== 1 ||
+        !property ||
+        !ts.isPropertyDeclaration(property) ||
+        property.initializer?.getText(sourceFile) !== value.trim()) {
+        throw new Error(`${label} must contain exactly one TypeScript expression.`);
+    }
+}
+function scopeStructure(modifier) {
+    switch (modifier) {
+        case "public":
+            return { scope: Scope.Public };
+        case "public readonly":
+            return { scope: Scope.Public, isReadonly: true };
+        case "protected":
+            return { scope: Scope.Protected };
+        case "protected readonly":
+            return { scope: Scope.Protected, isReadonly: true };
+        case "private":
+            return { scope: Scope.Private };
+        case "private readonly":
+            return { scope: Scope.Private, isReadonly: true };
+        default:
+            return {};
+    }
+}
+function decoratorStructure(value, label) {
+    assertBoundedText(value, label);
+    const sourceFile = parseFragment(`${value.trim()}\nclass __Scaffold {}`, label);
+    const declaration = sourceFile.statements[0];
+    const decorators = declaration && ts.isClassDeclaration(declaration) && ts.canHaveDecorators(declaration)
+        ? ts.getDecorators(declaration)
+        : undefined;
+    if (sourceFile.statements.length !== 1 ||
+        decorators?.length !== 1 ||
+        decorators[0]?.getText(sourceFile) !== value.trim()) {
+        throw new Error(`${label} must contain exactly one TypeScript decorator.`);
+    }
+    const match = /^@([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)(?:\(([\s\S]*)\))?$/.exec(value.trim());
+    if (!match) {
+        throw new Error(`${label} must use @Name or @Name(arguments) syntax.`);
+    }
+    const argumentText = match[2]?.trim();
+    return {
+        name: match[1],
+        arguments: argumentText ? [argumentText] : [],
+    };
+}
+function validateSpec(spec) {
+    assertIdentifier(spec.className, "class_name");
+    if (spec.methods.length === 0)
+        throw new Error("methods must contain at least one method.");
+    const methodNames = new Set();
+    for (const [index, method] of spec.methods.entries()) {
+        assertIdentifier(method.name, `methods[${index}].name`);
+        if (method.name === "constructor") {
+            throw new Error('Method name "constructor" is reserved for the generated constructor.');
+        }
+        if (methodNames.has(method.name)) {
+            throw new Error("Method names must be unique so pending method selectors are unambiguous.");
+        }
+        methodNames.add(method.name);
+        assertTypeFragment(method.returnType, `methods[${index}].return_type`);
+        const parameterNames = new Set();
+        for (const [paramIndex, parameter] of method.params.entries()) {
+            assertIdentifier(parameter.name, `methods[${index}].params[${paramIndex}].name`);
+            if (parameterNames.has(parameter.name)) {
+                throw new Error(`methods[${index}] parameter names must be unique.`);
+            }
+            parameterNames.add(parameter.name);
+            assertTypeFragment(parameter.type, `methods[${index}].params[${paramIndex}].type`);
+        }
+        for (const [docsIndex, docs] of (method.docs ?? []).entries()) {
+            assertBoundedText(docs, `methods[${index}].docs[${docsIndex}]`);
+            if (docs.includes("*/")) {
+                throw new Error(`methods[${index}].docs[${docsIndex}] must not close its doc comment.`);
+            }
+        }
+    }
+    const constructorParameterNames = new Set();
+    for (const [index, parameter] of spec.constructorParams.entries()) {
+        assertIdentifier(parameter.name, `constructor_params[${index}].name`);
+        if (constructorParameterNames.has(parameter.name)) {
+            throw new Error("Constructor parameter names must be unique.");
+        }
+        constructorParameterNames.add(parameter.name);
+        assertTypeFragment(parameter.type, `constructor_params[${index}].type`);
+    }
+    const propertyNames = new Set();
+    for (const [index, property] of spec.properties.entries()) {
+        assertIdentifier(property.name, `properties[${index}].name`);
+        if (propertyNames.has(property.name))
+            throw new Error("Property names must be unique.");
+        if (methodNames.has(property.name)) {
+            throw new Error("Property names must not collide with generated method names.");
+        }
+        propertyNames.add(property.name);
+        assertTypeFragment(property.type, `properties[${index}].type`);
+        if (property.initializer === undefined) {
+            throw new Error(`properties[${index}] requires an initializer.`);
+        }
+        assertInitializerFragment(property.initializer, `properties[${index}].initializer`);
+    }
+    for (const [index, declaration] of spec.imports.entries()) {
+        assertBoundedText(declaration.from, `imports[${index}].from`, 500);
+        if ([...declaration.from].some((character) => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint <= 31 || codePoint === 127;
+        })) {
+            throw new Error(`imports[${index}].from must not contain control characters.`);
+        }
+        if (declaration.default !== undefined) {
+            assertIdentifier(declaration.default, `imports[${index}].default`);
+        }
+        for (const [nameIndex, name] of (declaration.named ?? []).entries()) {
+            assertIdentifier(name, `imports[${index}].named[${nameIndex}]`);
+        }
+    }
+    spec.decorators.forEach((decorator, index) => decoratorStructure(decorator, `decorators[${index}]`));
+    spec.methods.forEach((method, methodIndex) => (method.decorators ?? []).forEach((decorator, decoratorIndex) => decoratorStructure(decorator, `methods[${methodIndex}].decorators[${decoratorIndex}]`)));
+    if (spec.extends !== undefined) {
+        assertHeritageFragment(spec.extends, "extends", SyntaxKind.ExtendsKeyword);
+    }
+    spec.implements.forEach((value, index) => assertHeritageFragment(value, `implements[${index}]`, SyntaxKind.ImplementsKeyword));
+}
+export function buildClassScaffold(project, filePath, spec) {
+    validateSpec(spec);
+    const sourceFile = project.createSourceFile(filePath, "", { overwrite: false });
+    sourceFile.addImportDeclarations(spec.imports.map((declaration) => ({
+        moduleSpecifier: declaration.from,
+        ...(declaration.default ? { defaultImport: declaration.default } : {}),
+        ...(declaration.named?.length ? { namedImports: declaration.named } : {}),
+    })));
+    sourceFile.addClass({
+        name: spec.className,
+        isExported: true,
+        ...(spec.extends ? { extends: spec.extends } : {}),
+        ...(spec.implements.length > 0 ? { implements: spec.implements } : {}),
+        decorators: spec.decorators.map((decorator, index) => decoratorStructure(decorator, `decorators[${index}]`)),
+        ctors: spec.constructorParams.length > 0
+            ? [
+                {
+                    parameters: spec.constructorParams.map((parameter) => ({
+                        name: parameter.name,
+                        type: parameter.type,
+                        ...scopeStructure(parameter.accessModifier),
+                    })),
+                    statements: [],
+                },
+            ]
+            : [],
+        properties: spec.properties.map((property) => ({
+            name: property.name,
+            type: property.type,
+            ...scopeStructure(property.accessModifier),
+            ...(property.initializer !== undefined ? { initializer: property.initializer } : {}),
+        })),
+        methods: spec.methods.map((method, methodIndex) => ({
+            name: method.name,
+            isAsync: method.isAsync,
+            returnType: method.returnType,
+            ...scopeStructure(method.accessModifier),
+            parameters: method.params.map((parameter) => ({
+                name: parameter.name,
+                type: parameter.type,
+            })),
+            decorators: (method.decorators ?? []).map((decorator, decoratorIndex) => decoratorStructure(decorator, `methods[${methodIndex}].decorators[${decoratorIndex}]`)),
+            docs: method.docs ?? [],
+            statements: [`throw new Error("Not implemented: ${spec.className}.${method.name}");`],
+        })),
+    });
+    const classes = sourceFile.getClasses();
+    const allowedStatements = sourceFile
+        .getStatements()
+        .every((statement) => Node.isImportDeclaration(statement) || Node.isClassDeclaration(statement));
+    if (!allowedStatements ||
+        classes.length !== 1 ||
+        classes[0]?.getName() !== spec.className ||
+        classes[0].getMethods().length !== spec.methods.length) {
+        throw new Error("Generated scaffold failed structural postcondition validation.");
+    }
+    return {
+        sourceFile,
+        pendingMethods: spec.methods.map((method) => `${spec.className}.${method.name}`),
+        outline: buildFileOutline(sourceFile).text,
+    };
+}

package/dist/services/symbols.js

@@ -1,4 +1,20 @@
 import { Node, } from "ts-morph";
+export function symbolMatchRank(query, symbol) {
+    const normalizedQuery = query.toLowerCase();
+    const normalizedPath = symbol.symbolPath.toLowerCase();
+    const normalizedName = symbol.name.toLowerCase();
+    const normalizedSelector = `${normalizedPath}@${symbol.line}`;
+    if (normalizedSelector === normalizedQuery)
+        return 0;
+    if (normalizedPath === normalizedQuery)
+        return 1;
+    if (normalizedName === normalizedQuery)
+        return 2;
+    if (normalizedPath.startsWith(normalizedQuery) || normalizedName.startsWith(normalizedQuery)) {
+        return 3;
+    }
+    return 4;
+}
 function namedNode(node) {
     if (Node.isConstructorDeclaration(node))
         return "constructor";

package/dist/tools/apply_operation.js

@@ -7,7 +7,7 @@ const AstApplyOperationInputSchema = z.object({
 });
 const AstApplyOperationOutputSchema = z.object({
     operation_id: z.string().uuid(),
-    kind: z.enum(["rename_symbol", "replace_symbol_body"]),
+    kind: z.enum(["rename_symbol", "replace_symbol_body", "scaffold_class"]),
     status: z.literal("applied"),
     applied_at: z.string(),
     affected_files: z.array(z.string()),

package/dist/tools/find_references.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
 import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
 import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
+const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const AstFindReferencesInputSchema = z.object({
     project_root: z
         .string()
@@ -11,10 +12,11 @@ const AstFindReferencesInputSchema = z.object({
     file_path: z.string().describe("File containing the declaration."),
     symbol_path: z.string().describe("Exact symbol path returned by an outline or symbol search."),
     include_declaration: z.boolean().default(true),
+    detail: ReferenceDetailSchema.describe("Result detail: locations omits source lines; context adds bounded source-line text."),
     ...ToolOutputFormatInputSchema,
     ...PaginationInputSchema,
 });
-const ReferenceSchema = z.object({
+const ContextReferenceSchema = z.object({
     file: z.string(),
     line: z.number().int().positive(),
     column: z.number().int().positive(),
@@ -22,14 +24,25 @@ const ReferenceSchema = z.object({
     is_declaration: z.boolean(),
     context: z.string(),
 });
-const AstFindReferencesOutputSchema = z.object({
+const LocationReferenceSchema = ContextReferenceSchema.omit({ context: true });
+const ReferenceOutputBase = {
     symbol: z.string(),
+    include_declaration: z.boolean(),
     declaration_count: z.number().int().min(0),
     reference_count: z.number().int().min(0),
     affected_files: z.array(z.string()),
-    references: z.array(ReferenceSchema),
     ...PaginationOutputSchema,
-});
+};
+const ReferenceOutputSchemas = {
+    locations: z.object({
+        ...ReferenceOutputBase,
+        references: z.array(LocationReferenceSchema),
+    }),
+    context: z.object({
+        ...ReferenceOutputBase,
+        references: z.array(ContextReferenceSchema),
+    }),
+};
 export function registerFindReferences(server) {
     server.registerTool("ast_find_references", {
         title: "Find semantic symbol references",
@@ -41,7 +54,7 @@ export function registerFindReferences(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path, include_declaration, output_format, offset, limit, }) => {
+    }, async ({ project_root, file_path, symbol_path, include_declaration, detail, output_format, offset, limit, }) => {
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
@@ -81,14 +94,24 @@ export function registerFindReferences(server) {
                 const { items, ...metadata } = page;
                 return {
                     symbol: symbol_path,
+                    include_declaration,
                     declaration_count: 1,
                     reference_count: references.length,
                     affected_files: affectedFiles,
-                    references: items,
+                    references: detail === "context"
+                        ? items
+                        : items.map(({ file, line, column, kind, is_declaration }) => ({
+                            file,
+                            line,
+                            column,
+                            kind,
+                            is_declaration,
+                        })),
                     ...metadata,
                 };
             });
-            return formattedResult(AstFindReferencesOutputSchema, structuredContent, output_format);
+            const outputSchema = ReferenceOutputSchemas[detail];
+            return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
             return errorResult(error);

package/dist/tools/operation-schema.js

@@ -10,7 +10,7 @@ export const NormalizedDiagnosticSchema = z.object({
 export const PreparedOperationOutputSchema = z.object({
     operation_id: z.string().uuid(),
     plan_hash: z.string().length(64),
-    kind: z.enum(["rename_symbol", "replace_symbol_body"]),
+    kind: z.enum(["rename_symbol", "replace_symbol_body", "scaffold_class"]),
     status: z.literal("prepared"),
     project_root: z.string(),
     created_at: z.string(),

package/dist/tools/scaffold_class.js

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { prepareScaffoldClass } from "../services/operations.js";
+import { errorResult, structuredResult } from "./result.js";
+import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
+const IdentifierSchema = z.string().min(1).max(200);
+const TypeTextSchema = z.string().min(1).max(10_000);
+const AccessSchema = z.enum(["public", "protected", "private"]);
+const ConstructorAccessSchema = z.enum([
+    "public",
+    "protected",
+    "private",
+    "public readonly",
+    "protected readonly",
+    "private readonly",
+]);
+const ImportSchema = z
+    .object({
+    from: z.string().min(1).max(500),
+    named: z.array(IdentifierSchema).max(100).default([]),
+    default: IdentifierSchema.optional(),
+})
+    .strict();
+const ParameterSchema = z
+    .object({
+    name: IdentifierSchema,
+    type: TypeTextSchema,
+})
+    .strict();
+const ConstructorParameterSchema = ParameterSchema.extend({
+    access_modifier: ConstructorAccessSchema,
+}).strict();
+const PropertySchema = z
+    .object({
+    name: IdentifierSchema,
+    type: TypeTextSchema,
+    access: AccessSchema.default("private"),
+    initializer: z.string().max(10_000).optional(),
+})
+    .strict();
+const MethodSchema = z
+    .object({
+    name: IdentifierSchema,
+    is_async: z.boolean().default(false),
+    return_type: TypeTextSchema,
+    access: AccessSchema.default("public"),
+    parameters: z.array(ParameterSchema).max(100).default([]),
+    decorators: z.array(z.string().min(1).max(10_000)).max(50).default([]),
+    docs: z.array(z.string().min(1).max(10_000)).max(50).default([]),
+})
+    .strict();
+export const ScaffoldClassInputSchema = z
+    .object({
+    project_root: z.string().min(1),
+    file_path: z.string().min(1).max(1_000),
+    class_name: IdentifierSchema,
+    extends: TypeTextSchema.optional(),
+    implements: z.array(TypeTextSchema).max(50).default([]),
+    decorators: z.array(z.string().min(1).max(10_000)).max(50).default([]),
+    imports: z.array(ImportSchema).max(100).default([]),
+    constructor_params: z.array(ConstructorParameterSchema).max(100).default([]),
+    properties: z.array(PropertySchema).max(200).default([]),
+    methods: z.array(MethodSchema).min(1).max(200),
+    dry_run: z.literal(true).default(true),
+    allow_new_errors: z.boolean().default(false),
+})
+    .strict();
+const ScaffoldClassOutputSchema = PreparedOperationOutputSchema.extend({
+    file: z.string(),
+    class_name: z.string(),
+    outline: z.string(),
+    pending_methods: z.array(z.string()),
+});
+function toSpec(args) {
+    return {
+        className: args.class_name,
+        ...(args.extends ? { extends: args.extends } : {}),
+        implements: args.implements,
+        decorators: args.decorators,
+        imports: args.imports.map((item) => ({
+            from: item.from,
+            named: item.named,
+            ...(item.default ? { default: item.default } : {}),
+        })),
+        constructorParams: args.constructor_params.map((parameter) => ({
+            name: parameter.name,
+            type: parameter.type,
+            accessModifier: parameter.access_modifier,
+        })),
+        properties: args.properties.map((property) => ({
+            name: property.name,
+            type: property.type,
+            accessModifier: property.access,
+            ...(property.initializer !== undefined ? { initializer: property.initializer } : {}),
+        })),
+        methods: args.methods.map((method) => ({
+            name: method.name,
+            isAsync: method.is_async,
+            returnType: method.return_type,
+            accessModifier: method.access,
+            params: method.parameters.map((parameter) => ({
+                name: parameter.name,
+                type: parameter.type,
+            })),
+            decorators: method.decorators,
+            docs: method.docs,
+        })),
+    };
+}
+export function registerScaffoldClass(server) {
+    // The SDK compatibility overload exceeds TypeScript's instantiation depth for this schema.
+    // Keep the complete runtime schema and isolate only the registrar type.
+    const registerTool = server.registerTool.bind(server);
+    registerTool("ast_scaffold_class", {
+        title: "Prepare Class Scaffold",
+        description: "Prepares a hash-bound new TypeScript class file without writing it. Each method body throws an explicit not-implemented error. Review the diff, then apply the returned operation_id and plan_hash with ast_apply_operation.",
+        inputSchema: ScaffoldClassInputSchema,
+        outputSchema: ScaffoldClassOutputSchema.shape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        try {
+            const prepared = await prepareScaffoldClass({
+                projectRoot: args.project_root,
+                filePath: args.file_path,
+                spec: toSpec(args),
+                allowNewErrors: args.allow_new_errors,
+            });
+            const structuredContent = {
+                ...serializePreparedOperation(prepared.operation),
+                file: prepared.file,
+                class_name: prepared.className,
+                outline: prepared.outline,
+                pending_methods: prepared.pendingMethods,
+            };
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/search_symbols.js

@@ -1,10 +1,12 @@
 import path from "node:path";
 import { z } from "zod";
 import { buildFileOutline } from "../services/outline.js";
-import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
+import { createPaginationInputSchema, PaginationOutputSchema, paginate, } from "../services/pagination.js";
 import { withProject } from "../services/project.js";
-import { collectSymbols } from "../services/symbols.js";
+import { collectSymbols, symbolMatchRank } from "../services/symbols.js";
 import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
+const SEARCH_DEFAULT_LIMIT = 20;
+const SearchDetailSchema = z.enum(["selectors", "summary", "full"]).default("summary");
 const AstSearchSymbolsInputSchema = z.object({
     project_root: z
         .string()
@@ -21,10 +23,11 @@ const AstSearchSymbolsInputSchema = z.object({
         .string()
         .optional()
         .describe("Optional case-insensitive substring matched against project-relative file paths."),
+    detail: SearchDetailSchema.describe("Result detail: selectors for routing, summary adds signatures, full adds redundant declaration fields."),
     ...ToolOutputFormatInputSchema,
-    ...PaginationInputSchema,
+    ...createPaginationInputSchema(SEARCH_DEFAULT_LIMIT),
 });
-const SearchSymbolSchema = z.object({
+const FullSearchSymbolSchema = z.object({
     file: z.string(),
     symbol_path: z.string(),
     selector: z.string(),
@@ -33,15 +36,51 @@ const SearchSymbolSchema = z.object({
     line: z.number().int().positive(),
     signature: z.string(),
 });
-const AstSearchSymbolsOutputSchema = z.object({
-    symbols: z.array(SearchSymbolSchema),
-    duration_ms: z.number().min(0),
-    ...PaginationOutputSchema,
+const SelectorSearchSymbolSchema = FullSearchSymbolSchema.pick({
+    file: true,
+    selector: true,
+    kind: true,
 });
+const SummarySearchSymbolSchema = FullSearchSymbolSchema.pick({
+    file: true,
+    selector: true,
+    kind: true,
+    signature: true,
+});
+const SearchOutputSchemas = {
+    selectors: z.object({
+        symbols: z.array(SelectorSearchSymbolSchema),
+        duration_ms: z.number().min(0),
+        ...PaginationOutputSchema,
+    }),
+    summary: z.object({
+        symbols: z.array(SummarySearchSymbolSchema),
+        duration_ms: z.number().min(0),
+        ...PaginationOutputSchema,
+    }),
+    full: z.object({
+        symbols: z.array(FullSearchSymbolSchema),
+        duration_ms: z.number().min(0),
+        ...PaginationOutputSchema,
+    }),
+};
+function projectSymbols(detail, symbols) {
+    if (detail === "full")
+        return symbols;
+    if (detail === "summary") {
+        return symbols.map(({ file, selector, kind, signature }) => ({
+            file,
+            selector,
+            kind,
+            signature,
+        }));
+    }
+    return symbols.map(({ file, selector, kind }) => ({ file, selector, kind }));
+}
 export function registerSearchSymbols(server) {
     server.registerTool("ast_search_symbols", {
         title: "Search project symbols",
-        description: "Searches declarations structurally and returns exact file/symbol selectors that can be passed to the other AST tools.",
+        description: "Ranks structural declarations and returns exact file/symbol selectors for downstream AST tools.",
         inputSchema: AstSearchSymbolsInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -49,7 +88,7 @@ export function registerSearchSymbols(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, query, kinds, file_filter, output_format, offset, limit }) => {
+    }, async ({ project_root, query, kinds, file_filter, detail, output_format, offset, limit }) => {
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const startedAt = performance.now();
@@ -62,9 +101,13 @@ export function registerSearchSymbols(server) {
                     if (normalizedFileFilter && !file.toLowerCase().includes(normalizedFileFilter)) {
                         continue;
                     }
-                    const matchingSymbols = collectSymbols(sourceFile).filter((symbol) => (!kindSet || kindSet.has(symbol.kind)) &&
-                        (symbol.name.toLowerCase().includes(normalizedQuery) ||
-                            symbol.symbolPath.toLowerCase().includes(normalizedQuery)));
+                    const matchingSymbols = collectSymbols(sourceFile).filter((symbol) => {
+                        const selector = `${symbol.symbolPath}@${symbol.line}`.toLowerCase();
+                        return ((!kindSet || kindSet.has(symbol.kind)) &&
+                            (symbol.name.toLowerCase().includes(normalizedQuery) ||
+                                symbol.symbolPath.toLowerCase().includes(normalizedQuery) ||
+                                selector.includes(normalizedQuery)));
+                    });
                     if (matchingSymbols.length === 0)
                         continue;
                     const signatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
@@ -83,16 +126,34 @@ export function registerSearchSymbols(server) {
                         });
                     }
                 }
-                matches.sort((left, right) => `${left.file}:${left.line}:${left.symbol_path}`.localeCompare(`${right.file}:${right.line}:${right.symbol_path}`));
+                matches.sort((left, right) => {
+                    const rank = symbolMatchRank(query, {
+                        symbolPath: left.symbol_path,
+                        name: left.name,
+                        line: left.line,
+                    }) -
+                        symbolMatchRank(query, {
+                            symbolPath: right.symbol_path,
+                            name: right.name,
+                            line: right.line,
+                        });
+                    if (rank !== 0)
+                        return rank;
+                    return (left.file.localeCompare(right.file) ||
+                        left.line - right.line ||
+                        left.symbol_path.localeCompare(right.symbol_path) ||
+                        left.kind.localeCompare(right.kind));
+                });
                 const page = paginate(matches, offset, limit);
                 const { items, ...metadata } = page;
                 return {
-                    symbols: items,
+                    symbols: projectSymbols(detail, items),
                     duration_ms: performance.now() - startedAt,
                     ...metadata,
                 };
             });
-            return formattedResult(AstSearchSymbolsOutputSchema, structuredContent, output_format);
+            const outputSchema = SearchOutputSchemas[detail];
+            return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
             return errorResult(error);