php_lsp/analysis/

code_lens.rs

/// `textDocument/codeLens` — inline actionable annotations above declarations.
///
/// Four lens types are emitted:
///   1. **Reference count** — above every function, class, and method declaration.
///   2. **Run test** — above PHPUnit test methods (methods whose name starts with
///      `test` or that carry a `/** @test */` docblock).
///   3. **N implementations** — above abstract classes, interfaces, and traits,
///      counting classes that extend/implement/use them.
///   4. **overrides ClassName::method** — above methods that override a parent
///      class method of the same name.
///
/// Counts and locations come from mir's inverted indexes (reference posting
/// lists and subtype edges) plus the salsa workspace index — never from a
/// per-request AST walk over the workspace.
use std::collections::HashMap;

use php_ast::{ClassMemberKind, EnumMemberKind, NamespaceBody, Stmt, StmtKind};
use serde_json::json;
use tower_lsp::lsp_types::{CodeLens, Command, Location, Url};

use crate::document::ast::{ParsedDoc, SourceView};
use crate::document::document_store::DocumentStore;
use crate::navigation::moniker::resolve_fqn;
use crate::navigation::references::{dedup_ref_locations, session_tuple_to_location};
use crate::text::fqn_short_name;

/// Build all code lenses for `uri`/`doc`, answering counts from the store's
/// mir-backed indexes.
///
/// `cancel_rev` is threaded into mir's index queries so a concurrent edit
/// aborts them at phase boundaries. `should_cancel` is polled between
/// top-level declarations; when it returns `true` the function returns an
/// empty `Vec` immediately. Pass `|| false` for requests that do not need
/// cooperative cancellation.
pub fn code_lenses(
    uri: &Url,
    doc: &ParsedDoc,
    store: &DocumentStore,
    imports: &HashMap<String, String>,
    cancel_rev: Option<u64>,
    should_cancel: impl Fn() -> bool,
) -> Vec<CodeLens> {
    let env = LensEnv {
        uri,
        doc,
        store,
        imports,
        cancel_rev,
    };
    let sv = doc.view();
    let mut lenses = Vec::new();
    collect_lenses(
        &doc.program().stmts,
        sv,
        "",
        &env,
        &mut lenses,
        &should_cancel,
    );
    lenses
}

/// Shared lookup context for one code-lens request.
struct LensEnv<'a> {
    uri: &'a Url,
    doc: &'a ParsedDoc,
    store: &'a DocumentStore,
    imports: &'a HashMap<String, String>,
    cancel_rev: Option<u64>,
}

impl LensEnv<'_> {
    fn reference_locations(&self, symbol: &mir_analyzer::Name) -> Vec<Location> {
        let files = self.store.reference_candidate_files(symbol);
        let mut locations: Vec<Location> = self
            .store
            .indexed_references(symbol, &files, false, self.cancel_rev)
            .into_iter()
            .filter_map(session_tuple_to_location)
            .collect();
        dedup_ref_locations(&mut locations);
        locations
    }

    fn ref_count_lens(
        &self,
        range: tower_lsp::lsp_types::Range,
        symbol: mir_analyzer::Name,
    ) -> CodeLens {
        let locations = self.reference_locations(&symbol);
        let label = match locations.len() {
            0 => "0 references".to_string(),
            1 => "1 reference".to_string(),
            n => format!("{n} references"),
        };
        lens(range, self.uri, label, locations)
    }

    fn impl_count_lens(
        &self,
        range: tower_lsp::lsp_types::Range,
        fqn: &str,
        include_trait_users: bool,
    ) -> CodeLens {
        let locations: Vec<Location> = self
            .store
            .indexed_subtype_classes(fqn, include_trait_users)
            .into_iter()
            .filter_map(|site| subtype_site_to_location(&site.file, &site.range))
            .collect();
        let label = match locations.len() {
            0 => "0 implementations".to_string(),
            1 => "1 implementation".to_string(),
            n => format!("{n} implementations"),
        };
        lens(range, self.uri, label, locations)
    }

    /// Declaration location of `method` on the class/trait `parent_fqn`,
    /// from the salsa workspace index. Prefers the exact-FQN class entry;
    /// falls back to any same-short-name class declaring the method.
    fn parent_method_location(&self, parent_fqn: &str, method: &str) -> Option<Location> {
        let ws = self.store.get_workspace_index_salsa();
        let parent_fqn = parent_fqn.trim_start_matches('\\');
        let candidates = ws.classes_by_name.get(fqn_short_name(parent_fqn))?;
        let method_loc = |r: &crate::db::workspace_index::ClassRef| {
            let (uri, cls) = ws.at(*r)?;
            let m = cls.methods.iter().find(|m| m.name.as_ref() == method)?;
            let start = tower_lsp::lsp_types::Position {
                line: m.start_line,
                character: m.name_char,
            };
            let end = tower_lsp::lsp_types::Position {
                line: m.start_line,
                character: m.name_char + m.name.encode_utf16().count() as u32,
            };
            Some((
                cls.fqn.trim_start_matches('\\').to_string(),
                Location {
                    uri: uri.clone(),
                    range: tower_lsp::lsp_types::Range { start, end },
                },
            ))
        };
        let mut fallback = None;
        for r in candidates {
            if let Some((fqn, loc)) = method_loc(r) {
                if fqn == parent_fqn {
                    return Some(loc);
                }
                fallback.get_or_insert(loc);
            }
        }
        fallback
    }
}

fn collect_lenses(
    stmts: &[Stmt<'_, '_>],
    sv: SourceView<'_>,
    enclosing_ns: &str,
    env: &LensEnv<'_>,
    out: &mut Vec<CodeLens>,
    should_cancel: &impl Fn() -> bool,
) {
    // `namespace App;` (unbraced) applies to every following statement.
    let mut ns: String = enclosing_ns.to_string();
    for stmt in stmts {
        if should_cancel() {
            out.clear();
            return;
        }
        match &stmt.kind {
            StmtKind::Function(f) => {
                let name = f.name.as_str().unwrap_or_default();
                let range = sv.name_range(name);
                out.push(
                    env.ref_count_lens(range, mir_analyzer::Name::function(fqn_in(&ns, name))),
                );
            }
            StmtKind::Class(c) => {
                if let Some(class_name) = c.name {
                    let class_name_str = class_name.as_str().unwrap_or_default();
                    let class_fqn = fqn_in(&ns, class_name_str);
                    let class_range = sv.name_range(class_name_str);
                    out.push(
                        env.ref_count_lens(
                            class_range,
                            mir_analyzer::Name::class(class_fqn.clone()),
                        ),
                    );

                    // Implementations count for abstract classes (classes extending this).
                    if c.modifiers.is_abstract {
                        out.push(env.impl_count_lens(class_range, &class_fqn, false));
                    }

                    // Direct supertypes — extends parent + used traits — checked once
                    // per class for overrides lookups on each method.
                    let parents = collect_direct_supertypes(c, env.doc, env.imports);

                    for member in c.body.members.iter() {
                        match &member.kind {
                            ClassMemberKind::Method(m) => {
                                let method_name = m.name.as_str().unwrap_or_default();
                                let method_range = sv.name_range(method_name);
                                out.push(env.ref_count_lens(
                                    method_range,
                                    mir_analyzer::Name::method(class_fqn.as_str(), method_name),
                                ));

                                if is_test_method(sv.source(), m) {
                                    out.push(run_test_lens(
                                        method_range,
                                        env.uri,
                                        class_name_str,
                                        method_name,
                                    ));
                                }

                                // Overrides lens: emit for each direct supertype (parent class
                                // or used trait) that declares a method with the same name.
                                for parent_fqn in &parents {
                                    if let Some(parent_loc) =
                                        env.parent_method_location(parent_fqn, method_name)
                                    {
                                        out.push(overrides_lens(
                                            method_range,
                                            env.uri,
                                            fqn_short_name(parent_fqn),
                                            method_name,
                                            parent_loc,
                                        ));
                                    }
                                }

                                // Constructor-promoted params: `public function __construct(public string $name)`.
                                if m.name == "__construct" {
                                    for p in m.params.iter() {
                                        if p.visibility.is_some() {
                                            let param_name = p.name.as_str().unwrap_or_default();
                                            let prop_range = sv.name_range(param_name);
                                            out.push(env.ref_count_lens(
                                                prop_range,
                                                property_name(&class_fqn, param_name),
                                            ));
                                        }
                                    }
                                }
                            }
                            ClassMemberKind::Property(p) => {
                                let prop_name = p.name.as_str().unwrap_or_default();
                                let prop_range = sv.name_range(prop_name);
                                out.push(env.ref_count_lens(
                                    prop_range,
                                    property_name(&class_fqn, prop_name),
                                ));
                            }
                            _ => {}
                        }
                    }
                }
            }
            StmtKind::Interface(i) => {
                let name = i.name.as_str().unwrap_or_default();
                let fqn = fqn_in(&ns, name);
                let range = sv.name_range(name);
                out.push(env.ref_count_lens(range, mir_analyzer::Name::class(fqn.clone())));
                // Implementations count lens.
                out.push(env.impl_count_lens(range, &fqn, false));
            }
            StmtKind::Trait(t) => {
                let trait_name = t.name.as_str().unwrap_or_default();
                let trait_fqn = fqn_in(&ns, trait_name);
                let range = sv.name_range(trait_name);
                out.push(env.ref_count_lens(range, mir_analyzer::Name::class(trait_fqn.clone())));
                // Usages: classes that `use` this trait (trait edges included).
                out.push(env.impl_count_lens(range, &trait_fqn, true));
                for member in t.body.members.iter() {
                    match &member.kind {
                        ClassMemberKind::Method(m) => {
                            let method_name = m.name.as_str().unwrap_or_default();
                            let method_range = sv.name_range(method_name);
                            out.push(env.ref_count_lens(
                                method_range,
                                mir_analyzer::Name::method(trait_fqn.as_str(), method_name),
                            ));
                        }
                        ClassMemberKind::Property(p) => {
                            let prop_name = p.name.as_str().unwrap_or_default();
                            let prop_range = sv.name_range(prop_name);
                            out.push(
                                env.ref_count_lens(
                                    prop_range,
                                    property_name(&trait_fqn, prop_name),
                                ),
                            );
                        }
                        _ => {}
                    }
                }
            }
            StmtKind::Enum(e) => {
                let enum_name = e.name.as_str().unwrap_or_default();
                let enum_fqn = fqn_in(&ns, enum_name);
                let range = sv.name_range(enum_name);
                out.push(env.ref_count_lens(range, mir_analyzer::Name::class(enum_fqn.clone())));
                for member in e.body.members.iter() {
                    match &member.kind {
                        EnumMemberKind::Method(m) => {
                            let method_name = m.name.as_str().unwrap_or_default();
                            let method_range = sv.name_range(method_name);
                            out.push(env.ref_count_lens(
                                method_range,
                                mir_analyzer::Name::method(enum_fqn.as_str(), method_name),
                            ));
                        }
                        EnumMemberKind::Case(c) => {
                            let case_name = c.name.as_str().unwrap_or_default();
                            let case_range = sv.name_range(case_name);
                            out.push(env.ref_count_lens(
                                case_range,
                                mir_analyzer::Name::class_constant(enum_fqn.as_str(), case_name),
                            ));
                        }
                        _ => {}
                    }
                }
            }
            StmtKind::Namespace(nsd) => {
                let ns_name = nsd
                    .name
                    .as_ref()
                    .map(|n| n.to_string_repr().into_owned())
                    .unwrap_or_default();
                match &nsd.body {
                    NamespaceBody::Braced(inner) => {
                        collect_lenses(&inner.stmts, sv, &ns_name, env, out, should_cancel);
                    }
                    NamespaceBody::Simple => {
                        ns = ns_name;
                    }
                }
            }
            _ => {}
        }
    }
}

fn fqn_in(ns: &str, name: &str) -> String {
    if ns.is_empty() {
        name.to_string()
    } else {
        format!("{ns}\\{name}")
    }
}

fn property_name(class_fqn: &str, prop: &str) -> mir_analyzer::Name {
    mir_analyzer::Name::property(class_fqn, prop)
}

fn subtype_site_to_location(file: &str, range: &mir_analyzer::Range) -> Option<Location> {
    let uri = Url::parse(file).ok()?;
    // mir uses 1-based lines; 0-based columns.
    let line = range.start.line.saturating_sub(1);
    Some(Location {
        uri,
        range: tower_lsp::lsp_types::Range {
            start: tower_lsp::lsp_types::Position {
                line,
                character: range.start.column,
            },
            end: tower_lsp::lsp_types::Position {
                line,
                character: range.end.column,
            },
        },
    })
}

fn lens(
    range: tower_lsp::lsp_types::Range,
    uri: &Url,
    title: String,
    locations: Vec<Location>,
) -> CodeLens {
    CodeLens {
        range,
        command: Some(Command {
            title,
            command: "editor.action.showReferences".to_string(),
            arguments: Some(vec![json!(uri), json!(range.start), json!(locations)]),
        }),
        data: None,
    }
}

fn overrides_lens(
    range: tower_lsp::lsp_types::Range,
    uri: &Url,
    parent_class: &str,
    method_name: &str,
    parent_location: Location,
) -> CodeLens {
    CodeLens {
        range,
        command: Some(Command {
            title: format!("overrides {}::{}", parent_class, method_name),
            command: "editor.action.showReferences".to_string(),
            arguments: Some(vec![
                json!(uri),
                json!(range.start),
                json!(vec![parent_location]),
            ]),
        }),
        data: None,
    }
}

fn run_test_lens(
    range: tower_lsp::lsp_types::Range,
    uri: &Url,
    class: &str,
    method: &str,
) -> CodeLens {
    CodeLens {
        range,
        command: Some(Command {
            title: "▶ Run test".to_string(),
            command: "php-lsp.runTest".to_string(),
            arguments: Some(vec![
                serde_json::json!(uri.to_string()),
                serde_json::json!(format!("{class}::{method}")),
            ]),
        }),
        data: None,
    }
}

/// Direct supertypes of `c` as FQNs — the extended parent class plus every
/// trait listed in `use` clauses, resolved through this file's imports and
/// namespace. Order is stable: extends first, then traits in source order.
/// Duplicates are removed.
fn collect_direct_supertypes(
    c: &php_ast::ClassDecl<'_, '_>,
    doc: &ParsedDoc,
    imports: &HashMap<String, String>,
) -> Vec<String> {
    let mut out: Vec<String> = Vec::new();
    let mut resolve = |name: std::borrow::Cow<'_, str>| {
        let fqn = resolve_fqn(doc, &name, imports)
            .trim_start_matches('\\')
            .to_string();
        if !out.contains(&fqn) {
            out.push(fqn);
        }
    };
    if let Some(extends) = &c.extends {
        resolve(extends.to_string_repr());
    }
    for member in c.body.members.iter() {
        if let ClassMemberKind::TraitUse(t) = &member.kind {
            for name in t.traits.iter() {
                resolve(name.to_string_repr());
            }
        }
    }
    out
}

/// A method is a test if its name starts with `test` (PHPUnit convention),
/// if its leading docblock contains `@test`, or if it carries a `#[Test]`
/// or `#[PHPUnit\Framework\Attributes\Test]` PHP attribute.
fn is_test_method(source: &str, m: &php_ast::MethodDecl<'_, '_>) -> bool {
    if m.name
        .as_str()
        .map(|s| s.starts_with("test"))
        .unwrap_or(false)
    {
        return true;
    }
    let has_test_attr = m.attributes.iter().any(|attr| {
        let span = attr.name.span();
        let attr_name = source
            .get(span.start as usize..span.end as usize)
            .unwrap_or("");
        attr_name == "Test" || attr_name.ends_with("\\Test")
    });
    if has_test_attr {
        return true;
    }
    m.doc_comment
        .as_ref()
        .is_some_and(|c| c.text.contains("@test"))
}

#[cfg(test)]
mod tests {
    use super::*;

    /// `should_cancel = || true` must return an empty Vec immediately without
    /// panicking, regardless of the document contents.
    #[test]
    fn code_lenses_cancelled_returns_empty() {
        use crate::document::ast::ParsedDoc;

        let source = "<?php\nclass Foo { public function bar(): void {} }\n";
        let doc = std::sync::Arc::new(ParsedDoc::parse(source));
        let uri = tower_lsp::lsp_types::Url::parse("file:///test.php").unwrap();
        let store = DocumentStore::new();

        let lenses = code_lenses(&uri, &doc, &store, &HashMap::new(), None, || true);
        assert!(lenses.is_empty(), "cancelled sweep must return empty");
    }
}