Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
doc-links(php): a property's, constant's or case's doc block belongs to its type
Martin Vogel2fdcbfe28828
diff --git a/internal/cbm/doclink.c b/internal/cbm/doclink.cindex 18a65cef1..8c6612b0e 100644--- a/internal/cbm/doclink.c+++ b/internal/cbm/doclink.c@@ -251,7 +251,8 @@ static const doclink_lang_t DOCLINK_LANGS[] = {.parse_doc = cbm_doclink_php_parse_doc,.scan_scope = cbm_doclink_php_scan_scope,.scope_tag = CBM_DOCLINK_PHP_SCOPE_TAG,- .portable_scope = cbm_doclink_php_portable_scope},+ .portable_scope = cbm_doclink_php_portable_scope,+ .loose_docs = cbm_doclink_php_loose_docs},};static const doclink_lang_t *doclink_lang(CBMLanguage lang) {@@ -480,10 +481,11 @@ static bool doclink_taken(const CBMExtractCtx *ctx, uint32_t first, uint32_t lasreturn false;}-/* The file's own doc, then the language's loose docs: their references belong- * to the file. The parser gets a definition-shaped stand-in for the file; what- * it pushes is marked, and the resolving half takes the File node as the- * source. No qualified name for that node is computed on this side. */+/* The file's own doc, then the language's loose docs. The parser gets a+ * definition-shaped stand-in for the file; what it pushes with the stand-in+ * is marked, and the resolving half takes the File node as the source (a+ * loose-doc hook may push with a definition of the file instead). No qualified+ * name for that node is computed on this side. */static void doclink_file_pass(CBMExtractCtx *ctx, const doclink_lang_t *L) {const char *file_doc = ctx->result->module_doc;bool has_doc = file_doc && file_doc[0];@@ -513,7 +515,9 @@ static void doclink_file_pass(CBMExtractCtx *ctx, const doclink_lang_t *L) {L->loose_docs(ctx, &file_def, doclink_taken);}for (int i = first; i < arr->count; i++) {- arr->items[i].flags |= CBM_DOCLINK_FLAG_FILE;+ if (arr->items[i].source_qn == file_def.qualified_name) {+ arr->items[i].flags |= CBM_DOCLINK_FLAG_FILE; /* not a definition's */+ }}}diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.hindex cce493488..faccd4dcf 100644--- a/internal/cbm/doclink.h+++ b/internal/cbm/doclink.h@@ -23,9 +23,11 @@* scope_tag, the blob's tag line and its persisted form (line* portable_scope numbers dropped). Optional.* loose_docs after the definitions and the file's own doc: the- * file's other doc comments (C: a prototype's doc,- * which the graph keeps no node for); what it pushes- * belongs to the file. Optional.+ * file's other doc comments, which the graph keeps no+ * node for. What it pushes with the file stand-in+ * belongs to the file (C: a prototype's doc); it may push+ * with a definition of the file instead (PHP: a+ * property's doc belongs to its class). Optional.* scan_file instead of parse_doc, for a DOCUMENT language whose* text is the documentation (Markdown): one pass over* the file's bytes pushes every reference, with the@@ -564,12 +566,20 @@ char *cbm_doclink_ts_portable_scope(const char *scope);* this length and the resolver reports it as unparseable. */enum { CBM_DOCLINK_TS_REF_MAX = 512 };+/* Asked by a loose_docs hook for a doc comment on lines [first, last]: true+ * when a definition's doc or the file's own doc there was already taken. */+typedef bool (*cbm_doclink_taken_fn)(const CBMExtractCtx *ctx, uint32_t first, uint32_t last);+/* ── PHP (doclink_php.c) ───────────────────────────────────────────── */void cbm_doclink_php_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,uint32_t doc_line);const char *cbm_doclink_php_scan_scope(CBMExtractCtx *ctx);char *cbm_doclink_php_portable_scope(const char *scope);+/* Doc blocks on properties, class constants and enum cases (they have no+ * node): their references belong to the type around them. */+void cbm_doclink_php_loose_docs(CBMExtractCtx *ctx, const CBMDefinition *file_def,+ cbm_doclink_taken_fn taken);#define CBM_DOCLINK_PHP_SCOPE_TAG "php1"@@ -600,10 +610,6 @@ size_t cbm_doclink_php_qualify(char *out, size_t cap, const char *ns, size_t ns_/* ── C (doclink_c.c) ───────────────────────────────────────────────── */-/* Asked by a loose_docs hook for a doc comment on lines [first, last]: true- * when a definition's doc or the file's own doc there was already taken. */-typedef bool (*cbm_doclink_taken_fn)(const CBMExtractCtx *ctx, uint32_t first, uint32_t last);-void cbm_doclink_c_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,uint32_t doc_line);void cbm_doclink_c_loose_docs(CBMExtractCtx *ctx, const CBMDefinition *file_def,diff --git a/internal/cbm/doclink_php.c b/internal/cbm/doclink_php.cindex 8abb8a437..35f14788e 100644--- a/internal/cbm/doclink_php.c+++ b/internal/cbm/doclink_php.c@@ -37,6 +37,10 @@* flags as for T* "At the top level" includes the branches of a top-level conditional* (`if (!function_exists('f')) { function f() {} }`), never a function body.+ * Doc blocks on properties, class constants and enum cases, which have no+ * node, go through cbm_doclink_php_loose_docs: their references belong to+ * the type around them.+ ** The persisted blob (cbm_doclink_php_portable_scope) drops the lines of N* and T and the U records: other files read names only, and every name a* supertype record holds is already qualified.@@ -910,6 +914,111 @@ const char *cbm_doclink_php_scan_scope(CBMExtractCtx *ctx) {return sb.oom ? NULL : sb.buf;}+/* ── Loose docs ──────────────────────────────────────────────────── */++/* The definition of a type declaration: its name, at its line. */+static const CBMDefinition *php_type_def(const CBMExtractCtx *ctx, TSNode decl) {+ TSNode name = ts_node_child_by_field_name(decl, TS_FIELD("name"));+ if (ts_node_is_null(name)) {+ return NULL;+ }+ uint32_t b = ts_node_start_byte(name);+ size_t n = ts_node_end_byte(name) - b;+ uint32_t line = ts_node_start_point(decl).row + SKIP_ONE;+ const CBMDefArray *defs = &ctx->result->defs;+ for (int i = 0; i < defs->count; i++) {+ const CBMDefinition *d = &defs->items[i];+ if (d->name && d->qualified_name && d->start_line == line && strlen(d->name) == n &&+ memcmp(d->name, ctx->source + b, n) == 0) {+ return d;+ }+ }+ return NULL;+}++static bool php_member_decl(TSNode n) {+ return php_kind(n, "property_declaration") || php_kind(n, "const_declaration") ||+ php_kind(n, "enum_case");+}++static bool php_doc_comment(const CBMExtractCtx *ctx, TSNode n) {+ if (!php_kind(n, "comment")) {+ return false;+ }+ uint32_t b = ts_node_start_byte(n);+ size_t len = ts_node_end_byte(n) - b;+ return len > PHP_PREFIX_LEN + SKIP_ONE && memcmp(ctx->source + b, "/**", PHP_PREFIX_LEN) == 0 &&+ ctx->source[b + PHP_PREFIX_LEN] != '*';+}++/* The doc blocks right above a type's properties, constants and cases. */+static void php_loose_type(CBMExtractCtx *ctx, TSNode decl, cbm_doclink_taken_fn taken) {+ const CBMDefinition *def = php_type_def(ctx, decl);+ TSNode body = ts_node_child_by_field_name(decl, TS_FIELD("body"));+ if (!def || ts_node_is_null(body)) {+ return;+ }+ TSNode doc = {0};+ TSTreeCursor cur = ts_tree_cursor_new(body);+ for (bool more = ts_tree_cursor_goto_first_child(&cur); more;+ more = ts_tree_cursor_goto_next_sibling(&cur)) {+ TSNode c = ts_tree_cursor_current_node(&cur);+ if (!ts_node_is_named(c)) {+ continue;+ }+ if (php_doc_comment(ctx, c)) {+ doc = c;+ continue;+ }+ uint32_t first = ts_node_is_null(doc) ? 0 : ts_node_start_point(doc).row + SKIP_ONE;+ uint32_t last = ts_node_is_null(doc) ? 0 : ts_node_end_point(doc).row + SKIP_ONE;+ if (first && php_member_decl(c) &&+ ts_node_start_point(c).row + SKIP_ONE <= last + SKIP_ONE && !taken(ctx, first, last)) {+ CBMArena *a = ctx->scratch ? ctx->scratch : ctx->arena;+ uint32_t b = ts_node_start_byte(doc);+ char *text = cbm_arena_strndup(a, ctx->source + b, ts_node_end_byte(doc) - b);+ if (text) {+ cbm_doclink_php_parse_doc(ctx, def, text, first);+ }+ }+ doc = (TSNode){0};+ }+ ts_tree_cursor_delete(&cur);+}++/* The types of the file: top level, namespace bodies, top-level conditionals. */+static void php_loose_walk(CBMExtractCtx *ctx, TSNode parent, int depth,+ cbm_doclink_taken_fn taken) {+ if (depth > PHP_COND_DEPTH) {+ return;+ }+ TSTreeCursor cur = ts_tree_cursor_new(parent);+ for (bool more = ts_tree_cursor_goto_first_child(&cur); more;+ more = ts_tree_cursor_goto_next_sibling(&cur)) {+ TSNode c = ts_tree_cursor_current_node(&cur);+ if (php_is_type_decl(c)) {+ php_loose_type(ctx, c, taken);+ } else if (php_kind(c, "namespace_definition")) {+ TSNode body = ts_node_child_by_field_name(c, TS_FIELD("body"));+ if (!ts_node_is_null(body)) {+ php_loose_walk(ctx, body, depth + SKIP_ONE, taken);+ }+ } else if (php_is_branch(c)) {+ php_loose_walk(ctx, c, depth + SKIP_ONE, taken);+ }+ }+ ts_tree_cursor_delete(&cur);+}++void cbm_doclink_php_loose_docs(CBMExtractCtx *ctx, const CBMDefinition *file_def,+ cbm_doclink_taken_fn taken) {+ (void)file_def; /* a member's doc belongs to its type, never to the file */+ if (!ctx || !ctx->result || !taken || ts_node_is_null(ctx->root)) {+ return;+ }+ php_loose_walk(ctx, ctx->root, 0, taken);+}+/* The blob without lines and imports: "N blk name first last" -> "N blk* name", "T kind fqn flags first last" -> "T kind fqn flags", U dropped. */char *cbm_doclink_php_portable_scope(const char *scope) {diff --git a/tests/test_doc_mentions_php.c b/tests/test_doc_mentions_php.cindex c4342d90d..c1352b0e5 100644--- a/tests/test_doc_mentions_php.c+++ b/tests/test_doc_mentions_php.c@@ -193,13 +193,16 @@ static void php_write_repo(const char *repo) {"class Numbers { const MAX = 9; }\n""trait Loud { public function shout() {} }\n""function clamp($v) { return $v; }\n");- th_write_file(TH_PATH(repo, "src/Model/Base.php"), "<?php\n"- "namespace App\\Model;\n"- "\n"- "abstract class Base {\n"- " public function boot() {}\n"- " public function mixedCase() {}\n"- "}\n");+ th_write_file(TH_PATH(repo, "src/Model/Base.php"),+ "<?php\n"+ "namespace App\\Model;\n"+ "\n"+ "abstract class Base {\n"+ " /** The hook, {@see \\App\\Util\\Strings}. */\n"+ " protected $hook;\n"+ " public function boot() {}\n"+ " public function mixedCase() {}\n"+ "}\n");th_write_file(TH_PATH(repo, "src/Dup.php"), "<?php\n""namespace App\\One;\n""class Same {}\n"@@ -323,6 +326,8 @@ TEST(doc_mentions_php_resolution) {ASSERT_TRUE(php_row(db, "\\App\\Twin\\Twin", "ambiguous"));ASSERT_TRUE(php_row(db, "\\App\\One\\Same", "graph_gap"));ASSERT_TRUE(php_row(db, "\\App\\One\\same()", "graph_gap"));+ /* a property's doc block belongs to its class */+ ASSERT_TRUE(php_edge(db, "src.Model.Base.Base", "src.Util.Helper.Strings"));/* aliases and method names compare without case */ASSERT_TRUE(php_edge(db, "src.Model.User.User.other", "src.Util.Helper.Helper.format"));PASS();