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.c — resolving PHP doc references (doclink_php.c). A reference
* is a FQSEN as phpDocumentor reads it, resolved with PHP's own name rules.
*
* Forms: `\Ns\Type`, `Type`, `Type::method()`, `Type::$property`,
* `Type::CONSTANT` (an enum case too), `function()` and `\Ns\function()`;
* `self::`, `static::` and `parent::` with a member. A member written without
* `()` and without `$` is a constant or enum case, else a method.
*
* Names. A leading backslash is taken as written. Otherwise the first segment
* of a type name is replaced when it is the alias of a class `use` of the
* namespace block the reference is written in (aliases compare without case),
* else the block's namespace is put in front: phpDocumentor's rule. Two rules
* go beyond that tool, as PHP itself has them: an unqualified function name
* is taken from a `use function` import, else from the current namespace,
* else from the global namespace; and `self` and `static` name the type the
* doc sits in, `parent` that type's superclass. Beyond both, as authors
* write it: a bare `name()` in the doc of a type (or of its members) that
* declares or inherits a method of that name is that method; a `use
* function` import of the name still wins. Type, function
* and method names compare without case, properties and constants with it.
* The global fallback cannot see a function a dependency declares in the
* current namespace: a reference to one binds the global function of that
* name (a residual).
*
* Members are looked up on the type, then on the traits it uses, its
* superclass and its interfaces, each of them the same way (depth first; the
* first declaration found wins). Nothing found where a supertype is outside
* the repository is external; nothing found with every supertype in the
* repository is missing.
*
* Outcomes. A type, function or method binds to its graph node. A property,
* constant or enum case has none (a graph gap), nor has a type or function
* the graph folds into another one of the same name in its file (the scope
* flags those). A type or qualified function the repository does not declare
* is external when the first segment of its name is no namespace the
* repository declares (PHP's built-ins, Composer dependencies), else missing;
* an unqualified function nobody declares is external (PHP's built-in
* functions). Two declarations of one name are ambiguous unless one is in the
* reference's own file. Test code binds only from test code. Edges are exact
* for a name written fully qualified or bound by a use import, unique
* otherwise.
*/
#include "pipeline/doc_links.h"
#include "cbm.h"
#include "doclink.h"
#include "helpers.h" /* cbm_fqn_module_source_lang, cbm_is_test_file */
#include "foundation/arena.h"
#include "foundation/constants.h"
#include "foundation/hash_table.h"
#include "foundation/log.h"
#include "foundation/mem_core.h"
#include "graph_buffer/graph_buffer.h"
#include <ctype.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
enum {
PR_QN_MAX = 2048,
PR_NAME_MAX = 1024,
PR_FIELDS = 6,
PR_MAX_DEPTH = 16,
PR_VISIT_MAX = 64,
PR_USE_FIELDS = 5, /* U blk kind alias name */
PR_LINE_FIELDS = 4, /* N blk name first last / T kind fqn flags first last: lines from here */
};
/* ── The index ───────────────────────────────────────────────────── */
typedef struct {
char kind; /* m p c e */
const char *name;
} pr_member_t;
typedef struct {
char rel; /* e i t */
const char *fqn;
} pr_base_t;
typedef struct {
int file;
char kind; /* c i t e */
bool dup; /* folded into another declaration of its file */
const char *fqn;
const char *name; /* the tail of fqn */
uint32_t first; /* lines: only in a fresh blob */
uint32_t last;
pr_base_t *bases;
int nbases;
int cap_bases;
pr_member_t *members;
int nmembers;
int cap_members;
int next; /* the next type of the same name (without case), or -1 */
} pr_type_t;
typedef struct {
int file;
bool dup;
const char *fqn;
const char *name;
int next;
} pr_func_t;
typedef struct {
int blk;
const char *name;
uint32_t first;
uint32_t last;
} pr_ns_t;
typedef struct {
const char *path;
const char *module_qn;
bool test;
pr_ns_t *nss;
int nnss;
int cap_nss;
cbm_doclink_php_use_t *uses; /* only in a fresh blob; a block's are adjacent */
int *use_blk;
int nuses;
int cap_uses;
int cap_use_blk;
int type_first; /* its types: types[type_first, type_first + type_count) */
int type_count;
} pr_file_t;
typedef struct {
CBMArena arena;
const char *project;
pr_file_t *files;
int nfiles;
int *run_to_file;
int run_count;
pr_type_t *types;
int ntypes;
int cap_types;
pr_func_t *funcs;
int nfuncs;
int cap_funcs;
CBMHashTable *type_at; /* lowercase fqn -> the first type's index + 1 */
CBMHashTable *func_at; /* lowercase fqn -> the first function's index + 1 */
CBMHashTable *roots; /* lowercase first segment of a declared namespace */
CBMHashTable *by_path; /* rel_path -> file index + 1 */
bool oom;
} pr_index_t;
static const char *pr_copy(pr_index_t *ix, const char *s, size_t n) {
char *c = cbm_arena_strndup(&ix->arena, s, n);
ix->oom = ix->oom || !c;
return c;
}
static const char *pr_lower(pr_index_t *ix, const char *s, size_t n) {
char *c = cbm_arena_strndup(&ix->arena, s, n);
if (!c) {
ix->oom = true;
return NULL;
}
for (size_t i = 0; i < n; i++) {
c[i] = (char)tolower((unsigned char)c[i]);
}
return c;
}
/* Room for one more item in a growing arena array. */
static bool pr_grow(pr_index_t *ix, void **items, int count, int *cap, size_t size) {
if (count < *cap) {
return true;
}
int ncap = *cap ? *cap * PAIR_LEN : CBM_SZ_8;
void *g = cbm_arena_alloc(&ix->arena, (size_t)ncap * size);
if (!g) {
ix->oom = true;
return false;
}
if (count) {
memcpy(g, *items, (size_t)count * size);
}
*items = g;
*cap = ncap;
return true;
}
static bool pr_dash(const char *s, size_t n) {
return n == SKIP_ONE && s[0] == '-';
}
static uint32_t pr_num(const char *s) {
return (uint32_t)strtoul(s, NULL, CBM_DECIMAL_BASE);
}
static pr_type_t *pr_last_type(pr_index_t *ix, const pr_file_t *f) {
return f->type_count ? &ix->types[f->type_first + f->type_count - SKIP_ONE] : NULL;
}
static void pr_read_type(pr_index_t *ix, pr_file_t *f, int fi, const char **fl, const size_t *ln,
int n) {
if (!pr_grow(ix, (void **)&ix->types, ix->ntypes, &ix->cap_types, sizeof(pr_type_t))) {
return;
}
if (!f->type_count) {
f->type_first = ix->ntypes;
}
pr_type_t *t = &ix->types[ix->ntypes++];
f->type_count++;
memset(t, 0, sizeof(*t));
t->file = fi;
t->kind = fl[1][0];
t->fqn = pr_copy(ix, fl[PAIR_LEN], ln[PAIR_LEN]);
t->dup = fl[CBM_SZ_3][0] == 'd';
t->next = CBM_NOT_FOUND;
if (n > PR_LINE_FIELDS) {
t->first = pr_num(fl[PR_LINE_FIELDS]);
t->last = n > PR_LINE_FIELDS + SKIP_ONE ? pr_num(fl[PR_LINE_FIELDS + SKIP_ONE]) : 0;
}
if (t->fqn) {
const char *bs = strrchr(t->fqn, '\\');
t->name = bs ? bs + SKIP_ONE : t->fqn;
}
}
static void pr_read_record(pr_index_t *ix, pr_file_t *f, int fi, const char **fl, const size_t *ln,
int n) {
char tag = fl[0][0];
pr_type_t *t = NULL;
if (tag == 'N' && n >= CBM_SZ_3 &&
pr_grow(ix, (void **)&f->nss, f->nnss, &f->cap_nss, sizeof(pr_ns_t))) {
pr_ns_t *s = &f->nss[f->nnss++];
s->blk = (int)pr_num(fl[1]);
s->name =
pr_dash(fl[PAIR_LEN], ln[PAIR_LEN]) ? "" : pr_copy(ix, fl[PAIR_LEN], ln[PAIR_LEN]);
s->first = n > CBM_SZ_3 ? pr_num(fl[CBM_SZ_3]) : 0;
s->last = n > CBM_SZ_4 ? pr_num(fl[CBM_SZ_4]) : 0;
} else if (tag == 'U' && n >= PR_USE_FIELDS &&
pr_grow(ix, (void **)&f->uses, f->nuses, &f->cap_uses,
sizeof(cbm_doclink_php_use_t)) &&
pr_grow(ix, (void **)&f->use_blk, f->nuses, &f->cap_use_blk, sizeof(int))) {
cbm_doclink_php_use_t *u = &f->uses[f->nuses];
f->use_blk[f->nuses++] = (int)pr_num(fl[1]);
u->kind = fl[PAIR_LEN][0];
u->alias = pr_copy(ix, fl[CBM_SZ_3], ln[CBM_SZ_3]);
u->alias_len = ln[CBM_SZ_3];
u->name = pr_copy(ix, fl[CBM_SZ_4], ln[CBM_SZ_4]);
u->name_len = ln[CBM_SZ_4];
} else if (tag == 'T' && n >= CBM_SZ_4) {
pr_read_type(ix, f, fi, fl, ln, n);
} else if (tag == 'B' && n >= CBM_SZ_3 && (t = pr_last_type(ix, f)) &&
pr_grow(ix, (void **)&t->bases, t->nbases, &t->cap_bases, sizeof(pr_base_t))) {
t->bases[t->nbases++] = (pr_base_t){fl[1][0], pr_copy(ix, fl[PAIR_LEN], ln[PAIR_LEN])};
} else if (tag == 'K' && n >= CBM_SZ_3 && (t = pr_last_type(ix, f)) &&
pr_grow(ix, (void **)&t->members, t->nmembers, &t->cap_members,
sizeof(pr_member_t))) {
t->members[t->nmembers++] =
(pr_member_t){fl[1][0], pr_copy(ix, fl[PAIR_LEN], ln[PAIR_LEN])};
} else if (tag == 'F' && n >= CBM_SZ_3 &&
pr_grow(ix, (void **)&ix->funcs, ix->nfuncs, &ix->cap_funcs, sizeof(pr_func_t))) {
pr_func_t *fn = &ix->funcs[ix->nfuncs++];
fn->file = fi;
fn->fqn = pr_copy(ix, fl[1], ln[1]);
fn->dup = fl[PAIR_LEN][0] == 'd';
fn->next = CBM_NOT_FOUND;
const char *bs = fn->fqn ? strrchr(fn->fqn, '\\') : NULL;
fn->name = bs ? bs + SKIP_ONE : fn->fqn;
}
}
static void pr_read_blob(pr_index_t *ix, pr_file_t *f, int fi, const char *blob) {
const char *line = strchr(blob, '\n'); /* the tag line */
while (line && !ix->oom) {
const char *b = line + SKIP_ONE;
const char *e = strchr(b, '\n');
if (!e) {
e = b + strlen(b);
}
const char *fl[PR_FIELDS];
size_t ln[PR_FIELDS];
int n = 0;
const char *s = b;
for (const char *p = b; p <= e && n < PR_FIELDS; p++) {
if (p == e || *p == '\t') {
fl[n] = s;
ln[n] = (size_t)(p - s);
n++;
s = p + SKIP_ONE;
}
}
if (n > 0 && ln[0] == SKIP_ONE) {
pr_read_record(ix, f, fi, fl, ln, n);
}
line = *e ? e : NULL;
}
}
static void pr_destroy(void *index) {
pr_index_t *ix = (pr_index_t *)index;
if (!ix) {
return;
}
cbm_ht_free(ix->type_at);
cbm_ht_free(ix->func_at);
cbm_ht_free(ix->roots);
cbm_ht_free(ix->by_path);
cbm_free(CBM_MEM_CLASS_OTHER, ix->run_to_file);
cbm_arena_destroy(&ix->arena);
cbm_free(CBM_MEM_CLASS_OTHER, ix);
}
/* The namespace root of a qualified name ("" for a global one). */
static void pr_add_root(pr_index_t *ix, const char *name) {
const char *bs = name ? strchr(name, '\\') : NULL;
size_t n = bs ? (size_t)(bs - name) : (name ? strlen(name) : 0);
if (!n) {
return;
}
const char *key = pr_lower(ix, name, n);
if (key && !cbm_ht_get(ix->roots, key)) {
cbm_ht_set(ix->roots, key, (void *)(uintptr_t)SKIP_ONE);
}
}
/* Chain every type and function into its name's list, and collect the
* namespace roots. */
static bool pr_link(pr_index_t *ix) {
ix->type_at = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, (uint32_t)(ix->ntypes + SKIP_ONE));
ix->func_at = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, (uint32_t)(ix->nfuncs + SKIP_ONE));
ix->roots = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, CBM_SZ_64);
if (!ix->type_at || !ix->func_at || !ix->roots) {
return false;
}
for (int i = 0; i < ix->ntypes && !ix->oom; i++) {
pr_type_t *t = &ix->types[i];
const char *key = t->fqn ? pr_lower(ix, t->fqn, strlen(t->fqn)) : NULL;
if (!key) {
continue;
}
void *prev = cbm_ht_get(ix->type_at, key);
t->next = prev ? (int)((uintptr_t)prev - SKIP_ONE) : CBM_NOT_FOUND;
cbm_ht_set(ix->type_at, key, (void *)(uintptr_t)(i + SKIP_ONE));
if (strchr(t->fqn, '\\')) {
pr_add_root(ix, t->fqn);
}
}
for (int i = 0; i < ix->nfuncs && !ix->oom; i++) {
pr_func_t *fn = &ix->funcs[i];
const char *key = fn->fqn ? pr_lower(ix, fn->fqn, strlen(fn->fqn)) : NULL;
if (!key) {
continue;
}
void *prev = cbm_ht_get(ix->func_at, key);
fn->next = prev ? (int)((uintptr_t)prev - SKIP_ONE) : CBM_NOT_FOUND;
cbm_ht_set(ix->func_at, key, (void *)(uintptr_t)(i + SKIP_ONE));
if (strchr(fn->fqn, '\\')) {
pr_add_root(ix, fn->fqn);
}
}
for (int i = 0; i < ix->nfiles && !ix->oom; i++) {
for (int k = 0; k < ix->files[i].nnss; k++) {
pr_add_root(ix, ix->files[i].nss[k].name);
}
}
return !ix->oom;
}
static void *pr_build(const cbm_doclink_build_in_t *in) {
pr_index_t *ix = (pr_index_t *)cbm_calloc(CBM_MEM_CLASS_OTHER, sizeof(*ix));
if (!ix) {
return NULL;
}
cbm_arena_init(&ix->arena);
ix->project = in->ctx->project_name;
ix->nfiles = in->file_count;
ix->run_count = in->run_file_count;
ix->files =
in->file_count
? (pr_file_t *)cbm_arena_calloc(&ix->arena, (size_t)in->file_count * sizeof(pr_file_t))
: NULL;
ix->run_to_file = (int *)cbm_calloc(CBM_MEM_CLASS_OTHER,
(size_t)(in->run_file_count + SKIP_ONE) * sizeof(int));
ix->by_path = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, (uint32_t)(in->file_count + SKIP_ONE));
bool ok = (!in->file_count || ix->files) && ix->run_to_file && ix->by_path;
for (int r = 0; ok && r < in->run_file_count; r++) {
ix->run_to_file[r] = CBM_NOT_FOUND;
}
for (int i = 0; ok && i < in->file_count && !ix->oom; i++) {
const cbm_doclink_file_t *src = &in->files[i];
pr_file_t *f = &ix->files[i];
f->path = src->rel_path;
f->module_qn =
cbm_fqn_module_source_lang(&ix->arena, ix->project, src->rel_path, CBM_LANG_PHP);
f->test = cbm_is_test_file(src->rel_path, CBM_LANG_PHP);
ix->oom = ix->oom || !f->module_qn;
cbm_ht_set(ix->by_path, src->rel_path, (void *)(uintptr_t)(i + SKIP_ONE));
if (src->run_file >= 0 && src->run_file < in->run_file_count) {
ix->run_to_file[src->run_file] = i;
}
if (src->scope) {
pr_read_blob(ix, f, i, src->scope);
}
}
ok = ok && !ix->oom && pr_link(ix);
if (!ok) {
cbm_log_error("doc_links.php.error", "step", "index", "reason", "alloc");
pr_destroy(ix);
return NULL;
}
char b[CBM_SZ_3][CBM_SZ_32];
snprintf(b[0], sizeof(b[0]), "%d", ix->nfiles);
snprintf(b[SKIP_ONE], sizeof(b[SKIP_ONE]), "%d", ix->ntypes);
snprintf(b[PAIR_LEN], sizeof(b[PAIR_LEN]), "%d", ix->nfuncs);
cbm_log_info("doc_links.php.index", "files", b[0], "types", b[SKIP_ONE], "functions",
b[PAIR_LEN]);
return ix;
}
/* ── References ──────────────────────────────────────────────────── */
typedef struct {
const char *cls; /* a type or function name, NULL for none */
size_t cls_len;
const char *mem; /* a member name (no `$`), NULL for none */
size_t mem_len;
bool prop; /* `::$name` */
bool call; /* `()` at the end */
} pr_ref_t;
static bool pr_ident_start(char c) {
return isalpha((unsigned char)c) || c == '_' || (unsigned char)c >= 0x80;
}
static bool pr_ident_char(char c) {
return isalnum((unsigned char)c) || c == '_' || (unsigned char)c >= 0x80;
}
/* The end of an identifier at s[i] (i when there is none). */
static size_t pr_ident_end(const char *s, size_t i, size_t n) {
if (i >= n || !pr_ident_start(s[i])) {
return i;
}
while (i < n && pr_ident_char(s[i])) {
i++;
}
return i;
}
/* The end of a name (`\`-joined identifiers, a leading `\` allowed) at s[0]. */
static size_t pr_name_end(const char *s, size_t n) {
size_t i = (n > 0 && s[0] == '\\') ? SKIP_ONE : 0;
size_t e = pr_ident_end(s, i, n);
if (e == i) {
return 0;
}
while (e + SKIP_ONE < n && s[e] == '\\' && pr_ident_start(s[e + SKIP_ONE])) {
e = pr_ident_end(s, e + SKIP_ONE, n);
}
return e;
}
static bool pr_parse(const char *s, size_t n, pr_ref_t *r) {
memset(r, 0, sizeof(*r));
size_t i = pr_name_end(s, n);
if (i == 0) {
return false; /* a member needs its type: `::name` is no FQSEN */
}
r->cls = s;
r->cls_len = i;
if (i + PAIR_LEN <= n && s[i] == ':' && s[i + SKIP_ONE] == ':') {
i += PAIR_LEN;
if (i < n && s[i] == '$') {
r->prop = true;
i++;
}
size_t e = pr_ident_end(s, i, n);
if (e == i) {
return false;
}
r->mem = s + i;
r->mem_len = e - i;
i = e;
}
if (!r->prop && i + PAIR_LEN == n && s[i] == '(' && s[i + SKIP_ONE] == ')') {
r->call = true;
i = n;
}
return i == n;
}
/* ── Resolution ──────────────────────────────────────────────────── */
typedef enum {
PR_NONE = 0, /* nothing found */
PR_TYPE, /* a type of the index (`type`) */
PR_NODE,
PR_GAP,
PR_EXTERNAL,
PR_MISSING,
PR_AMBIGUOUS,
} pr_kind_t;
typedef struct {
pr_kind_t kind;
int type;
const cbm_gbuf_node_t *node;
bool exact;
} pr_res_t;
typedef struct {
const pr_index_t *ix;
const cbm_gbuf_t *g;
int src;
const char *ns; /* the reference's namespace block */
size_t ns_len;
const cbm_doclink_php_use_t *uses; /* that block's imports */
int nuses;
int cur; /* the type the doc sits in, or -1 */
} pr_ctx_t;
static pr_res_t pr_mk(pr_kind_t k) {
return (pr_res_t){k, CBM_NOT_FOUND, NULL, false};
}
static bool pr_eq_nocase(const char *a, size_t an, const char *b, size_t bn) {
if (an != bn) {
return false;
}
for (size_t i = 0; i < an; i++) {
if (tolower((unsigned char)a[i]) != tolower((unsigned char)b[i])) {
return false;
}
}
return true;
}
static void pr_lower_into(char *out, const char *s, size_t n) {
for (size_t i = 0; i < n; i++) {
out[i] = (char)tolower((unsigned char)s[i]);
}
out[n] = '\0';
}
/* The namespace block of `line` in file f and its imports. */
static void pr_block_at(pr_ctx_t *c, const pr_file_t *f, uint32_t line) {
int blk = f->nnss ? CBM_NOT_FOUND : 0;
c->ns = "";
c->ns_len = 0;
for (int i = 0; i < f->nnss; i++) {
if (line >= f->nss[i].first && line <= f->nss[i].last) {
blk = f->nss[i].blk;
c->ns = f->nss[i].name;
c->ns_len = strlen(c->ns);
break;
}
}
c->uses = NULL;
c->nuses = 0;
for (int i = 0; i < f->nuses; i++) {
if (f->use_blk[i] != blk) {
continue;
}
if (!c->uses) {
c->uses = &f->uses[i];
}
c->nuses++;
}
}
/* The type of file f whose lines hold `line`, or -1. */
static int pr_type_at(const pr_index_t *ix, const pr_file_t *f, uint32_t line) {
for (int i = 0; i < f->type_count; i++) {
const pr_type_t *t = &ix->types[f->type_first + i];
if (line >= t->first && line <= t->last) {
return f->type_first + i;
}
}
return CBM_NOT_FOUND;
}
/* The node at `qn` in file `path`, or NULL. */
static const cbm_gbuf_node_t *pr_node(const pr_ctx_t *c, const char *qn, const char *path) {
const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(c->g, qn);
if (!n || !n->label || !n->file_path || strcmp(n->file_path, path) != 0) {
return NULL;
}
return n;
}
/* A declared type's own node: a gap when the graph folded it or has none. */
static pr_res_t pr_type_node(const pr_ctx_t *c, int ti) {
const pr_type_t *t = &c->ix->types[ti];
const pr_file_t *f = &c->ix->files[t->file];
char qn[PR_QN_MAX];
int n = snprintf(qn, sizeof(qn), "%s.%s", f->module_qn, t->name);
const cbm_gbuf_node_t *node =
(!t->dup && n > 0 && (size_t)n < sizeof(qn)) ? pr_node(c, qn, f->path) : NULL;
pr_res_t r = pr_mk(node ? PR_NODE : PR_GAP);
r.node = node;
return r;
}
/* The repository's type named `fqn`: one, several (ambiguous, unless one is
* in the reference's file) or none. */
static pr_res_t pr_find_type(const pr_ctx_t *c, const char *fqn, size_t len) {
char key[PR_NAME_MAX];
if (len >= sizeof(key)) {
return pr_mk(PR_NONE);
}
pr_lower_into(key, fqn, len);
void *v = cbm_ht_get(c->ix->type_at, key);
int first = v ? (int)((uintptr_t)v - SKIP_ONE) : CBM_NOT_FOUND;
int count = 0;
int own = CBM_NOT_FOUND;
for (int i = first; i >= 0; i = c->ix->types[i].next) {
count++;
own = c->ix->types[i].file == c->src ? i : own;
}
if (count == 0) {
return pr_mk(PR_NONE);
}
pr_res_t r = pr_mk(count == SKIP_ONE || own >= 0 ? PR_TYPE : PR_AMBIGUOUS);
r.type = count == SKIP_ONE ? first : own;
return r;
}
/* A name the repository does not declare: missing inside one of its
* namespaces, else external. */
static pr_res_t pr_absent(const pr_ctx_t *c, const char *fqn, size_t len) {
const char *bs = memchr(fqn, '\\', len);
char key[PR_NAME_MAX];
size_t rl = bs ? (size_t)(bs - fqn) : 0;
if (!rl || rl >= sizeof(key)) {
return pr_mk(PR_EXTERNAL);
}
pr_lower_into(key, fqn, rl);
return pr_mk(cbm_ht_get(c->ix->roots, key) ? PR_MISSING : PR_EXTERNAL);
}
/* True when the first segment of `name` is a class-use alias. */
static bool pr_aliased(const pr_ctx_t *c, const char *name, size_t len) {
const char *bs = memchr(name, '\\', len);
size_t first = bs ? (size_t)(bs - name) : len;
for (int i = 0; i < c->nuses; i++) {
if (c->uses[i].kind == 'c' &&
pr_eq_nocase(c->uses[i].alias, c->uses[i].alias_len, name, first)) {
return true;
}
}
return false;
}
static bool pr_is(const char *s, size_t n, const char *word) {
return pr_eq_nocase(s, n, word, strlen(word));
}
/* The superclass of type ti, as a type of the index. */
static pr_res_t pr_parent(const pr_ctx_t *c, int ti) {
const pr_type_t *t = &c->ix->types[ti];
for (int i = 0; i < t->nbases; i++) {
if (t->bases[i].rel == 'e' && t->bases[i].fqn) {
pr_res_t r = pr_find_type(c, t->bases[i].fqn, strlen(t->bases[i].fqn));
return r.kind == PR_NONE ? pr_mk(PR_EXTERNAL) : r;
}
}
return pr_mk(PR_MISSING);
}
/* The type a reference's type part names. */
static pr_res_t pr_type_of(const pr_ctx_t *c, const pr_ref_t *r) {
if (pr_is(r->cls, r->cls_len, "self") || pr_is(r->cls, r->cls_len, "static")) {
pr_res_t res = pr_mk(c->cur >= 0 ? PR_TYPE : PR_MISSING);
res.type = c->cur;
return res;
}
if (pr_is(r->cls, r->cls_len, "parent")) {
return c->cur >= 0 ? pr_parent(c, c->cur) : pr_mk(PR_MISSING);
}
char fqn[PR_NAME_MAX];
size_t fl = cbm_doclink_php_qualify(fqn, sizeof(fqn), c->ns, c->ns_len, c->uses, c->nuses,
r->cls, r->cls_len);
if (!fl) {
return pr_mk(PR_MISSING);
}
pr_res_t res = pr_find_type(c, fqn, fl);
if (res.kind == PR_NONE) {
res = pr_absent(c, fqn, fl);
}
res.exact = r->cls[0] == '\\' || pr_aliased(c, r->cls, r->cls_len);
return res;
}
/* ── Members across supertypes ───────────────────────────────────── */
typedef struct {
const pr_ctx_t *c;
char want; /* 'm' a method, 'p' a property, 'c' a constant or enum case */
const char *name;
size_t len;
int visited[PR_VISIT_MAX];
int nvisited;
bool open; /* a supertype outside the repository */
bool amb; /* a supertype with several declarations */
int owner; /* found: the declaring type and member */
const pr_member_t *found;
} pr_search_t;
static bool pr_member_is(const pr_search_t *s, const pr_member_t *m) {
size_t ml = strlen(m->name);
if (s->want == 'm') {
return m->kind == 'm' && pr_eq_nocase(m->name, ml, s->name, s->len);
}
bool kind = s->want == 'p' ? m->kind == 'p' : (m->kind == 'c' || m->kind == 'e');
return kind && ml == s->len && memcmp(m->name, s->name, ml) == 0;
}
static bool pr_seen(pr_search_t *s, int ti) {
for (int i = 0; i < s->nvisited; i++) {
if (s->visited[i] == ti) {
return true;
}
}
if (s->nvisited == PR_VISIT_MAX) {
s->open = true; /* too wide to follow: not every supertype was read */
return true;
}
s->visited[s->nvisited++] = ti;
return false;
}
static bool pr_search(pr_search_t *s, int ti, int depth) {
if (depth > PR_MAX_DEPTH) {
s->open = true;
return false;
}
if (pr_seen(s, ti)) {
return false;
}
const pr_type_t *t = &s->c->ix->types[ti];
for (int i = 0; i < t->nmembers; i++) {
if (pr_member_is(s, &t->members[i])) {
s->owner = ti;
s->found = &t->members[i];
return true;
}
}
static const char order[] = {'t', 'e', 'i'}; /* traits, superclass, interfaces */
for (size_t o = 0; o < sizeof(order); o++) {
for (int i = 0; i < t->nbases; i++) {
if (t->bases[i].rel != order[o] || !t->bases[i].fqn) {
continue;
}
pr_res_t r = pr_find_type(s->c, t->bases[i].fqn, strlen(t->bases[i].fqn));
if (r.kind == PR_TYPE && pr_search(s, r.type, depth + SKIP_ONE)) {
return true;
}
s->amb = s->amb || r.kind == PR_AMBIGUOUS;
s->open = s->open || r.kind == PR_NONE;
}
}
return false;
}
/* The member's outcome: a method's node, else a graph gap. */
static pr_res_t pr_member_node(const pr_ctx_t *c, const pr_search_t *s) {
const pr_type_t *t = &c->ix->types[s->owner];
if (s->found->kind != 'm' || t->dup) {
return pr_mk(PR_GAP);
}
const pr_file_t *f = &c->ix->files[t->file];
char qn[PR_QN_MAX];
int n = snprintf(qn, sizeof(qn), "%s.%s.%s", f->module_qn, t->name, s->found->name);
const cbm_gbuf_node_t *node =
(n > 0 && (size_t)n < sizeof(qn)) ? pr_node(c, qn, f->path) : NULL;
pr_res_t r = pr_mk(node ? PR_NODE : PR_GAP);
r.node = node;
return r;
}
static pr_res_t pr_member(const pr_ctx_t *c, int ti, const pr_ref_t *r) {
pr_search_t s = {.c = c, .name = r->mem, .len = r->mem_len, .owner = CBM_NOT_FOUND};
s.want = r->prop ? 'p' : r->call ? 'm' : 'c';
bool hit = pr_search(&s, ti, 0);
if (!hit && s.want == 'c') {
/* `Type::name` without parentheses names a method as often as a
* constant: no constant or case of that name, then a method */
bool open = s.open;
bool amb = s.amb;
s.want = 'm';
s.nvisited = 0;
hit = pr_search(&s, ti, 0);
s.open = s.open || open;
s.amb = s.amb || amb;
}
if (hit) {
return pr_member_node(c, &s);
}
return pr_mk(s.amb ? PR_AMBIGUOUS : s.open ? PR_EXTERNAL : PR_MISSING);
}
/* ── Functions ───────────────────────────────────────────────────── */
static pr_res_t pr_find_func(const pr_ctx_t *c, const char *fqn, size_t len) {
char key[PR_NAME_MAX];
if (len >= sizeof(key)) {
return pr_mk(PR_NONE);
}
pr_lower_into(key, fqn, len);
void *v = cbm_ht_get(c->ix->func_at, key);
int first = v ? (int)((uintptr_t)v - SKIP_ONE) : CBM_NOT_FOUND;
int count = 0;
int own = CBM_NOT_FOUND;
for (int i = first; i >= 0; i = c->ix->funcs[i].next) {
count++;
own = c->ix->funcs[i].file == c->src ? i : own;
}
if (count == 0) {
return pr_mk(PR_NONE);
}
if (count > SKIP_ONE && own < 0) {
return pr_mk(PR_AMBIGUOUS);
}
const pr_func_t *fn = &c->ix->funcs[count == SKIP_ONE ? first : own];
const pr_file_t *f = &c->ix->files[fn->file];
char qn[PR_QN_MAX];
int n = snprintf(qn, sizeof(qn), "%s.%s", f->module_qn, fn->name);
const cbm_gbuf_node_t *node =
(!fn->dup && n > 0 && (size_t)n < sizeof(qn)) ? pr_node(c, qn, f->path) : NULL;
pr_res_t r = pr_mk(node ? PR_NODE : PR_GAP);
r.node = node;
return r;
}
static pr_res_t pr_function(const pr_ctx_t *c, const pr_ref_t *r) {
char fqn[PR_NAME_MAX];
if (r->cls[0] == '\\' || memchr(r->cls, '\\', r->cls_len)) {
/* qualified: the type rules (a namespace alias may start it) */
size_t fl = cbm_doclink_php_qualify(fqn, sizeof(fqn), c->ns, c->ns_len, c->uses, c->nuses,
r->cls, r->cls_len);
pr_res_t res = fl ? pr_find_func(c, fqn, fl) : pr_mk(PR_MISSING);
if (res.kind == PR_NONE) {
res = pr_absent(c, fqn, fl);
}
res.exact = r->cls[0] == '\\' || pr_aliased(c, r->cls, r->cls_len);
return res;
}
for (int i = 0; i < c->nuses; i++) {
const cbm_doclink_php_use_t *u = &c->uses[i];
if (u->kind == 'f' && pr_eq_nocase(u->alias, u->alias_len, r->cls, r->cls_len)) {
pr_res_t res = pr_find_func(c, u->name, u->name_len);
if (res.kind == PR_NONE) {
res = pr_absent(c, u->name, u->name_len);
}
res.exact = true;
return res;
}
}
if (c->cur >= 0) {
/* a method the documented type declares or inherits */
pr_search_t s = {
.c = c, .want = 'm', .name = r->cls, .len = r->cls_len, .owner = CBM_NOT_FOUND};
if (pr_search(&s, c->cur, 0)) {
return pr_member_node(c, &s);
}
}
pr_res_t res = pr_mk(PR_NONE);
if (c->ns_len) {
int n = snprintf(fqn, sizeof(fqn), "%.*s\\%.*s", (int)c->ns_len, c->ns, (int)r->cls_len,
r->cls);
res = (n > 0 && (size_t)n < sizeof(fqn)) ? pr_find_func(c, fqn, (size_t)n) : res;
}
if (res.kind == PR_NONE) {
res = pr_find_func(c, r->cls, r->cls_len); /* PHP's global fallback */
}
return res.kind == PR_NONE ? pr_mk(PR_EXTERNAL) : res; /* none: a built-in */
}
/* ── Outcomes ────────────────────────────────────────────────────── */
static void pr_out(const pr_ctx_t *c, pr_res_t r, cbm_doclink_outcome_t *out) {
switch (r.kind) {
case PR_NODE: {
const pr_file_t *src = &c->ix->files[c->src];
void *v = r.node->file_path ? cbm_ht_get(c->ix->by_path, r.node->file_path) : NULL;
int tf = v ? (int)((uintptr_t)v - SKIP_ONE) : CBM_NOT_FOUND;
if (tf >= 0 && c->ix->files[tf].test && !src->test) {
out->kind = CBM_DOCLINK_UNRESOLVED;
out->reason = CBM_DOCLINK_REASON_TEST_ONLY;
return;
}
out->kind = CBM_DOCLINK_EDGE;
out->target = r.node;
out->exact = r.exact;
return;
}
case PR_EXTERNAL:
out->reason = CBM_DOCLINK_REASON_EXTERNAL;
break;
case PR_AMBIGUOUS:
out->reason = CBM_DOCLINK_REASON_AMBIGUOUS;
break;
case PR_GAP:
out->reason = CBM_DOCLINK_REASON_GRAPH_GAP;
break;
default:
out->reason = CBM_DOCLINK_REASON_MISSING;
break;
}
out->kind = CBM_DOCLINK_UNRESOLVED;
}
static void pr_resolve(const void *index, void *state, int run_file, const CBMDocLink *link,
const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {
(void)state; /* PHP keeps no per-file working state */
const pr_index_t *ix = (const pr_index_t *)index;
out->kind = CBM_DOCLINK_UNRESOLVED;
out->reason = CBM_DOCLINK_REASON_MISSING;
out->target = NULL;
out->exact = false;
if (!ix || !link->raw || run_file < 0 || run_file >= ix->run_count ||
ix->run_to_file[run_file] < 0) {
return;
}
pr_ctx_t c = {.ix = ix, .g = graph, .src = ix->run_to_file[run_file]};
const pr_file_t *f = &ix->files[c.src];
size_t rl = strlen(link->raw);
pr_ref_t r;
if (rl > CBM_DOCLINK_PHP_REF_MAX || !pr_parse(link->raw, rl, &r)) {
out->reason = CBM_DOCLINK_REASON_UNPARSEABLE;
return;
}
pr_block_at(&c, f, link->line);
c.cur = pr_type_at(ix, f, link->def_line);
pr_res_t res;
if (!r.mem && r.call) {
res = pr_function(&c, &r);
} else if (!r.mem) {
res = pr_type_of(&c, &r);
if (res.kind == PR_TYPE) {
bool exact = res.exact;
res = pr_type_node(&c, res.type);
res.exact = exact;
}
} else {
res = pr_type_of(&c, &r);
if (res.kind == PR_TYPE) {
bool exact = res.exact;
res = pr_member(&c, res.type, &r);
res.exact = exact;
}
}
pr_out(&c, res, out);
}
/* A top-level function (F fqn flags) or a member of the type above it (K kind
* name) declares one name; reported as a reference spells it, the last
* segment of a qualified name. A type, a supertype, a namespace block or a
* use import changes how others resolve: GLOBAL. */
static bool pr_removable(const char *line, size_t len, const char **name, size_t *nlen) {
if (len <= PAIR_LEN || line[1] != '\t') {
return false;
}
if (line[0] == 'K') {
return cbm_doclinks_scope_field(line, len, PAIR_LEN, name, nlen);
}
if (line[0] != 'F' || !cbm_doclinks_scope_field(line, len, 1, name, nlen)) {
return false;
}
for (size_t i = *nlen; i > 0; i--) {
if ((*name)[i - SKIP_ONE] == '\\') {
*nlen -= i;
*name += i;
break;
}
}
return true;
}
static int pr_scope_delta(const char *stored, const char *fresh, cbm_doclink_name_fn removed,
void *ud) {
return cbm_doclinks_scope_delta_lines(stored, fresh, pr_removable, removed, ud);
}
const cbm_doclink_resolver_t cbm_doclink_php_resolver = {
.langs = {CBM_LANG_PHP},
.lang_count = SKIP_ONE,
.scope_tag = CBM_DOCLINK_PHP_SCOPE_TAG,
.build = pr_build,
.destroy = pr_destroy,
.resolve = pr_resolve,
.scope_delta = pr_scope_delta,
};