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_ts.c — resolving TypeScript and JavaScript doc references
* (doclink_ts.c), one index over TS, TSX and JS files, which import each other.
*
* A reference is a path: segments joined by `.`, `#` (an instance member) or
* `~` (a module's member), with an optional `()` or meaning suffix
* (`:class`, `:0`) that is dropped (one node holds every overload). Its first
* segment is looked up as the TypeScript checker would see it from the
* documented declaration, and the field test's prototype does:
* 1. the declaration's own parameters (dropped at extraction);
* 2. the namespaces around the reference's line, innermost first;
* 3. the file's own top-level declarations;
* 4. the file's imports: named, default and namespace imports, followed
* through `export { a as b }`, `export ... from` and `export *` barrels
* (a cycle guard and a depth bound; two barrels that answer differently
* are ambiguous); a relative specifier resolves with the usual extension
* and index rules; a bare one through the nearest tsconfig/jsconfig
* `paths` (the first target, as TypeScript tries it first) or
* `baseUrl`, else, when it is the `name` of a workspace package (the
* pipeline's package map), to that package's entry module (`exports`,
* `main`, `module`) when the repository indexes it; every other bare
* specifier, a package's subpath included, is external;
* 5. the standard library's global names: external;
* 6. the top-level declarations of the repository's script files (files
* without an import or an export are global): one binds, several are
* ambiguous;
* 7. the members of the documented declaration's class or interface (of the
* declaration itself for a class or interface doc), `this.` included.
* Nothing found is missing. The other segments walk members (a node's
* qualified name + `.` + segment) or a module's exports. A member a class,
* interface or enum declares without a node of its own is a graph gap. Test
* code binds only from test code. Edges are exact for a name the file
* declares or imports, unique otherwise.
*/
#include "pipeline/doc_links.h"
#include "pipeline/path_alias.h"
#include "pipeline/pipeline_internal.h" /* cbm_pipeline_file_node, cbm_pipeline_get_pkgmap */
#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 {
TR_MAX_DEPTH = 16,
TR_MAX_SEGS = 16,
TR_QN_MAX = 2048,
TR_PATH_MAX = 1024,
TR_FIELDS = 5,
TR_HTML_MIN = 11, /* HTML + Element */
TR_SVG_MIN = 10, /* SVG + Element */
};
/* ── The index ───────────────────────────────────────────────────── */
typedef struct {
const char *a; /* local name / exported name */
const char *spec;
const char *b; /* orig / local */
char kind; /* imports: d n s */
} tr_rec_t;
typedef struct {
const char *path;
uint32_t first;
uint32_t last;
} tr_ns_t;
typedef struct {
const char *name;
uint32_t line; /* the declaration's */
uint32_t first; /* the function body it is visible in */
uint32_t last;
} tr_nest_t;
typedef struct {
const char *path;
const char *module_qn;
const char *sym_qn; /* what its declarations' QNs start with: an index file's
* module QN without `.index` (fqn.c, strip_init_or_index) */
bool test;
bool module_syntax;
tr_rec_t *imps; /* I */
int nimps;
tr_rec_t *stars; /* A: spec */
int nstars;
tr_rec_t *star_as; /* S: a = name, spec */
int nstar_as;
tr_rec_t *froms; /* F: a = name, spec, b = orig */
int nfroms;
tr_rec_t *locals; /* L: a = name, b = local */
int nlocals;
tr_rec_t *decls; /* D: a = name, kind e/d flags: 'e', 'd', 'b' (both), '-' */
int ndecls;
tr_ns_t *nss;
int nnss;
tr_nest_t *nested; /* V: only in a fresh blob, the run's own files */
int nnested;
} tr_file_t;
typedef struct {
CBMArena arena;
const char *project;
tr_file_t *files;
int nfiles;
int *run_to_file;
int run_count;
CBMHashTable *by_path; /* rel_path -> (file index + 1) as a pointer */
CBMHashTable *globals; /* name -> tr_global_t */
CBMHashTable *by_module; /* module QN -> (first file index + 1) */
const cbm_path_alias_collection_t *aliases; /* the pipeline's, borrowed */
CBMHashTable *pkgmap; /* the pipeline's, borrowed */
bool oom;
} tr_index_t;
typedef struct {
int file;
int count; /* script files declaring the name */
} tr_global_t;
static const char *tr_copy(tr_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 bool tr_dash(const char *s, size_t n) {
return n == SKIP_ONE && s[0] == '-';
}
/* Append one record to a growing arena array. */
static tr_rec_t *tr_push(tr_index_t *ix, tr_rec_t **items, int *count) {
if (*count == 0 || (*count >= CBM_SZ_4 && (*count & (*count - SKIP_ONE)) == 0)) {
int ncap = *count ? *count * PAIR_LEN : CBM_SZ_4; /* 4, 8, 16, ... */
tr_rec_t *g = (tr_rec_t *)cbm_arena_alloc(&ix->arena, (size_t)ncap * sizeof(tr_rec_t));
if (!g) {
ix->oom = true;
return NULL;
}
if (*count) {
memcpy(g, *items, (size_t)*count * sizeof(tr_rec_t));
}
*items = g;
}
tr_rec_t *r = &(*items)[(*count)++];
memset(r, 0, sizeof(*r));
return r;
}
static void tr_push_ns(tr_index_t *ix, tr_file_t *f, const char *path, uint32_t first,
uint32_t last) {
if (f->nnss == 0 || (f->nnss >= CBM_SZ_4 && (f->nnss & (f->nnss - SKIP_ONE)) == 0)) {
int ncap = f->nnss ? f->nnss * PAIR_LEN : CBM_SZ_4;
tr_ns_t *g = (tr_ns_t *)cbm_arena_alloc(&ix->arena, (size_t)ncap * sizeof(tr_ns_t));
if (!g) {
ix->oom = true;
return;
}
if (f->nnss) {
memcpy(g, f->nss, (size_t)f->nnss * sizeof(tr_ns_t));
}
f->nss = g;
}
f->nss[f->nnss++] = (tr_ns_t){path, first, last};
}
static void tr_push_nested(tr_index_t *ix, tr_file_t *f, const char *name, uint32_t line,
uint32_t first, uint32_t last) {
if (f->nnested == 0 ||
(f->nnested >= CBM_SZ_4 && (f->nnested & (f->nnested - SKIP_ONE)) == 0)) {
int ncap = f->nnested ? f->nnested * PAIR_LEN : CBM_SZ_4;
tr_nest_t *g = (tr_nest_t *)cbm_arena_alloc(&ix->arena, (size_t)ncap * sizeof(tr_nest_t));
if (!g) {
ix->oom = true;
return;
}
if (f->nnested) {
memcpy(g, f->nested, (size_t)f->nnested * sizeof(tr_nest_t));
}
f->nested = g;
}
f->nested[f->nnested++] = (tr_nest_t){name, line, first, last};
}
static void tr_read_record(tr_index_t *ix, tr_file_t *f, const char **fl, const size_t *ln, int n) {
char tag = fl[0][0];
tr_rec_t *r = NULL;
if (tag == 'M') {
f->module_syntax = true;
} else if (tag == 'I' && n >= TR_FIELDS && (r = tr_push(ix, &f->imps, &f->nimps))) {
r->a = tr_copy(ix, fl[1], ln[1]);
r->kind = fl[PAIR_LEN][0];
r->spec = tr_copy(ix, fl[CBM_SZ_3], ln[CBM_SZ_3]);
r->b = tr_dash(fl[CBM_SZ_4], ln[CBM_SZ_4]) ? NULL : tr_copy(ix, fl[CBM_SZ_4], ln[CBM_SZ_4]);
} else if (tag == 'A' && n >= PAIR_LEN && (r = tr_push(ix, &f->stars, &f->nstars))) {
r->spec = tr_copy(ix, fl[1], ln[1]);
} else if (tag == 'S' && n >= CBM_SZ_3 && (r = tr_push(ix, &f->star_as, &f->nstar_as))) {
r->a = tr_copy(ix, fl[1], ln[1]);
r->spec = tr_copy(ix, fl[PAIR_LEN], ln[PAIR_LEN]);
} else if (tag == 'F' && n >= CBM_SZ_4 && (r = tr_push(ix, &f->froms, &f->nfroms))) {
r->a = tr_copy(ix, fl[1], ln[1]);
r->spec = tr_copy(ix, fl[PAIR_LEN], ln[PAIR_LEN]);
r->b = tr_copy(ix, fl[CBM_SZ_3], ln[CBM_SZ_3]);
} else if (tag == 'L' && n >= CBM_SZ_3 && (r = tr_push(ix, &f->locals, &f->nlocals))) {
r->a = tr_copy(ix, fl[1], ln[1]);
r->b = tr_copy(ix, fl[PAIR_LEN], ln[PAIR_LEN]);
} else if (tag == 'D' && n >= CBM_SZ_3 && (r = tr_push(ix, &f->decls, &f->ndecls))) {
r->a = tr_copy(ix, fl[1], ln[1]);
bool e = memchr(fl[PAIR_LEN], 'e', ln[PAIR_LEN]) != NULL;
bool d = memchr(fl[PAIR_LEN], 'd', ln[PAIR_LEN]) != NULL;
r->kind = (e && d) ? 'b' : e ? 'e' : d ? 'd' : '-';
} else if (tag == 'V' && n >= TR_FIELDS) {
tr_push_nested(ix, f, tr_copy(ix, fl[1], ln[1]),
(uint32_t)strtoul(fl[PAIR_LEN], NULL, CBM_DECIMAL_BASE),
(uint32_t)strtoul(fl[CBM_SZ_3], NULL, CBM_DECIMAL_BASE),
(uint32_t)strtoul(fl[CBM_SZ_4], NULL, CBM_DECIMAL_BASE));
} else if (tag == 'N' && n >= PAIR_LEN) {
uint32_t first =
n >= CBM_SZ_4 ? (uint32_t)strtoul(fl[PAIR_LEN], NULL, CBM_DECIMAL_BASE) : 0;
uint32_t last = n >= CBM_SZ_4 ? (uint32_t)strtoul(fl[CBM_SZ_3], NULL, CBM_DECIMAL_BASE) : 0;
tr_push_ns(ix, f, tr_copy(ix, fl[1], ln[1]), first, last);
}
}
static void tr_read_blob(tr_index_t *ix, tr_file_t *f, 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[TR_FIELDS];
size_t ln[TR_FIELDS];
int n = 0;
const char *s = b;
for (const char *p = b; p <= e && n < TR_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) {
tr_read_record(ix, f, fl, ln, n);
}
line = *e ? e : NULL;
}
}
static CBMLanguage tr_lang(const char *path) {
const char *dot = strrchr(path, '.');
if (dot && (strcmp(dot, ".ts") == 0 || strcmp(dot, ".mts") == 0 || strcmp(dot, ".cts") == 0)) {
return CBM_LANG_TYPESCRIPT;
}
return dot && strcmp(dot, ".tsx") == 0 ? CBM_LANG_TSX : CBM_LANG_JAVASCRIPT;
}
static void tr_destroy(void *index) {
tr_index_t *ix = (tr_index_t *)index;
if (!ix) {
return;
}
cbm_ht_free(ix->by_path);
cbm_ht_free(ix->globals);
cbm_ht_free(ix->by_module);
cbm_free(CBM_MEM_CLASS_OTHER, ix->run_to_file);
cbm_arena_destroy(&ix->arena);
cbm_free(CBM_MEM_CLASS_OTHER, ix);
}
static bool tr_add_globals(tr_index_t *ix) {
ix->globals = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, CBM_SZ_256);
if (!ix->globals) {
return false;
}
for (int i = 0; i < ix->nfiles; i++) {
const tr_file_t *f = &ix->files[i];
if (f->module_syntax) {
continue; /* a module's names are its own */
}
for (int k = 0; k < f->ndecls; k++) {
tr_global_t *g = (tr_global_t *)cbm_ht_get(ix->globals, f->decls[k].a);
if (g) {
g->count += g->file == i ? 0 : SKIP_ONE;
continue;
}
g = (tr_global_t *)cbm_arena_alloc(&ix->arena, sizeof(tr_global_t));
if (!g) {
return false;
}
*g = (tr_global_t){i, SKIP_ONE};
cbm_ht_set(ix->globals, f->decls[k].a, g);
}
}
return true;
}
/* The QN prefix of a file's declarations: an index module's QN loses its
* last segment, as a symbol QN does in fqn.c. */
static const char *tr_symbol_prefix(tr_index_t *ix, const char *module_qn) {
static const char suffix[] = ".index";
size_t sl = sizeof(suffix) - SKIP_ONE;
size_t n = module_qn ? strlen(module_qn) : 0;
if (n <= sl || strcmp(module_qn + n - sl, suffix) != 0) {
return module_qn;
}
return tr_copy(ix, module_qn, n - sl);
}
static void *tr_build(const cbm_doclink_build_in_t *in) {
tr_index_t *ix = (tr_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
? (tr_file_t *)cbm_arena_calloc(&ix->arena, (size_t)in->file_count * sizeof(tr_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];
tr_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_TYPESCRIPT);
f->test = cbm_is_test_file(src->rel_path, tr_lang(src->rel_path));
ix->oom = ix->oom || !f->module_qn;
f->sym_qn = tr_symbol_prefix(ix, 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) {
tr_read_blob(ix, f, src->scope);
}
}
ok = ok && !ix->oom && tr_add_globals(ix);
ix->aliases = in->ctx->path_aliases;
ix->pkgmap = cbm_pipeline_get_pkgmap();
ix->by_module =
ok ? cbm_ht_create_in(CBM_MEM_CLASS_OTHER, (uint32_t)(ix->nfiles + SKIP_ONE)) : NULL;
ok = ok && ix->by_module;
for (int i = ix->nfiles - SKIP_ONE; ok && i >= 0; i--) {
if (ix->files[i].module_qn) {
cbm_ht_set(ix->by_module, ix->files[i].module_qn, (void *)(uintptr_t)(i + SKIP_ONE));
}
}
if (!ok) {
cbm_log_error("doc_links.ts.error", "step", "index", "reason", "alloc");
tr_destroy(ix);
return NULL;
}
char b[PAIR_LEN][CBM_SZ_32];
snprintf(b[0], sizeof(b[0]), "%d", ix->nfiles);
snprintf(b[SKIP_ONE], sizeof(b[SKIP_ONE]), "%u", cbm_ht_count(ix->globals));
cbm_log_info("doc_links.ts.index", "files", b[0], "global_names", b[SKIP_ONE]);
return ix;
}
/* ── Resolution ──────────────────────────────────────────────────── */
typedef enum {
TR_NONE = 0, /* nothing found */
TR_NODE,
TR_MODULE, /* a file's exports (a namespace import) */
TR_EXTERNAL,
TR_AMBIGUOUS,
TR_GAP, /* declared, without a node */
TR_MISSING,
TR_NOT_INDEXED, /* a relative import of a file the index does not hold */
} tr_kind_t;
typedef struct {
tr_kind_t kind;
const cbm_gbuf_node_t *node;
int file;
bool exact;
} tr_res_t;
typedef struct {
const tr_index_t *ix;
const cbm_gbuf_t *g;
int src;
cbm_doclink_outcome_t *out;
int visited[TR_MAX_DEPTH * PAIR_LEN];
const char *visited_name[TR_MAX_DEPTH * PAIR_LEN];
int nvisited;
} tr_ctx_t;
static tr_res_t tr_mk(tr_kind_t k) {
return (tr_res_t){k, NULL, CBM_NOT_FOUND, false};
}
/* The node at `qn`, when it belongs to file f (any file when f is NULL). */
static const cbm_gbuf_node_t *tr_node(const tr_ctx_t *c, const char *qn, const tr_file_t *f) {
const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(c->g, qn);
if (!n || !n->label) {
return NULL;
}
if (f && (!n->file_path || strcmp(n->file_path, f->path) != 0)) {
return NULL;
}
return n;
}
static bool tr_join(char *out, size_t cap, const char *a, const char *b, const char *c) {
int n = c ? snprintf(out, cap, "%s.%s.%s", a, b, c) : snprintf(out, cap, "%s.%s", a, b);
return n > 0 && (size_t)n < cap;
}
static const tr_rec_t *tr_decl(const tr_file_t *f, const char *name) {
for (int i = 0; i < f->ndecls; i++) {
if (strcmp(f->decls[i].a, name) == 0) {
return &f->decls[i];
}
}
return NULL;
}
/* A top-level declaration of file f: its node, or a graph gap. */
static tr_res_t tr_decl_res(const tr_ctx_t *c, const tr_file_t *f, const char *name) {
char qn[TR_QN_MAX];
if (!tr_join(qn, sizeof(qn), f->sym_qn, name, NULL)) {
return tr_mk(TR_GAP);
}
const cbm_gbuf_node_t *n = tr_node(c, qn, f);
tr_res_t r = tr_mk(n ? TR_NODE : TR_GAP);
r.node = n;
return r;
}
static int tr_file_at(const tr_index_t *ix, const char *path) {
void *v = cbm_ht_get(ix->by_path, path);
return v ? (int)((uintptr_t)v - SKIP_ONE) : CBM_NOT_FOUND;
}
/* Normalize dir + "/" + rel into out ("." and ".." resolved); false when it
* leaves the repository. */
static bool tr_norm(const char *dir, size_t dl, const char *rel, char *out, size_t cap) {
char buf[TR_PATH_MAX];
int n = dl ? snprintf(buf, sizeof(buf), "%.*s/%s", (int)dl, dir, rel)
: snprintf(buf, sizeof(buf), "%s", rel);
if (n <= 0 || (size_t)n >= sizeof(buf)) {
return false;
}
size_t w = 0;
for (char *seg = buf; *seg;) {
char *slash = strchr(seg, '/');
size_t sl = slash ? (size_t)(slash - seg) : strlen(seg);
if (sl == PAIR_LEN && seg[0] == '.' && seg[SKIP_ONE] == '.') {
if (w == 0) {
return false;
}
while (w > 0 && out[w - SKIP_ONE] != '/') {
w--;
}
w = w > 0 ? w - SKIP_ONE : 0;
} else if (!(sl == SKIP_ONE && seg[0] == '.') && sl > 0) {
if (w > 0) {
out[w++] = '/';
}
if (w + sl + SKIP_ONE >= cap) {
return false;
}
memcpy(out + w, seg, sl);
w += sl;
}
seg = slash ? slash + SKIP_ONE : seg + sl;
}
out[w] = '\0';
return w > 0;
}
/* The file a repository-relative module path names: the path itself, the
* path with a module extension, or its index file. */
static int tr_path_file(const tr_index_t *ix, const char *base) {
static const char *const strip[] = {".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", NULL};
static const char *const exts[] = {".ts", ".tsx", ".d.ts", ".mts", ".cts",
".js", ".jsx", ".mjs", ".cjs", NULL};
static const char *const index[] = {"/index.ts", "/index.tsx", "/index.d.ts", "/index.js",
NULL};
int hit = tr_file_at(ix, base);
if (hit >= 0) {
return hit;
}
char stem[TR_PATH_MAX];
snprintf(stem, sizeof(stem), "%s", base);
size_t bl = strlen(stem);
for (int i = 0; strip[i]; i++) {
size_t el = strlen(strip[i]);
if (bl > el && strcmp(stem + bl - el, strip[i]) == 0) {
stem[bl - el] = '\0';
break;
}
}
char cand[TR_PATH_MAX + CBM_SZ_16];
for (int i = 0; exts[i] && hit < 0; i++) {
snprintf(cand, sizeof(cand), "%s%s", stem, exts[i]);
hit = tr_file_at(ix, cand);
}
for (int i = 0; index[i] && hit < 0; i++) {
snprintf(cand, sizeof(cand), "%s%s", base, index[i]);
hit = tr_file_at(ix, cand);
}
return hit;
}
/* The workspace package a bare specifier names (`name` or `@scope/name`, no
* subpath): the file of its entry module, as the pipeline's package map
* holds it. */
static int tr_package_file(const tr_index_t *ix, const char *spec) {
const char *slash = strchr(spec, '/');
if (spec[0] == '@' && slash) {
slash = strchr(slash + SKIP_ONE, '/');
}
if (slash || !ix->pkgmap || !ix->by_module) {
return CBM_NOT_FOUND;
}
const char *qn = (const char *)cbm_ht_get(ix->pkgmap, spec);
void *v = qn ? cbm_ht_get(ix->by_module, qn) : NULL;
return v ? (int)((uintptr_t)v - SKIP_ONE) : CBM_NOT_FOUND;
}
/* A bare specifier the repository answers itself: the nearest
* tsconfig/jsconfig `paths` or `baseUrl`, else a workspace package. */
static int tr_bare_file(const tr_index_t *ix, int from, const char *spec) {
const cbm_path_alias_map_t *map =
ix->aliases ? cbm_path_alias_find_for_file(ix->aliases, ix->files[from].path) : NULL;
char aliased[TR_PATH_MAX];
if (map && cbm_path_alias_resolve_into(map, spec, aliased, sizeof(aliased))) {
int hit = tr_path_file(ix, aliased);
if (hit >= 0) {
return hit;
}
}
return tr_package_file(ix, spec);
}
/* The file a module specifier written in file `from` names: -1 with
* *external for a bare specifier the repository does not answer (a
* package). */
static int tr_spec_file(const tr_index_t *ix, int from, const char *spec, bool *external) {
*external = false;
if (!(spec[0] == '.' &&
(spec[SKIP_ONE] == '/' || spec[SKIP_ONE] == '\0' ||
(spec[SKIP_ONE] == '.' && (spec[PAIR_LEN] == '/' || spec[PAIR_LEN] == '\0'))))) {
int hit = tr_bare_file(ix, from, spec);
*external = hit < 0;
return hit;
}
const char *path = ix->files[from].path;
const char *slash = strrchr(path, '/');
char base[TR_PATH_MAX];
if (!tr_norm(path, slash ? (size_t)(slash - path) : 0, spec, base, sizeof(base))) {
return CBM_NOT_FOUND;
}
return tr_path_file(ix, base);
}
static tr_res_t tr_export_of(tr_ctx_t *c, int file, const char *name, int depth);
/* What a specifier's file exports as `name`. */
static tr_res_t tr_from(tr_ctx_t *c, int file, const char *spec, const char *name, int depth) {
bool external = false;
int f = tr_spec_file(c->ix, file, spec, &external);
if (f < 0) {
return tr_mk(external ? TR_EXTERNAL : TR_NOT_INDEXED);
}
if (!name) {
tr_res_t r = tr_mk(TR_MODULE);
r.file = f;
return r;
}
return tr_export_of(c, f, name, depth + SKIP_ONE);
}
/* A name bound at the top level of file `file`: its declaration or import. */
static tr_res_t tr_top_binding(tr_ctx_t *c, int file, const char *name, int depth) {
const tr_file_t *f = &c->ix->files[file];
if (tr_decl(f, name)) {
tr_res_t r = tr_decl_res(c, f, name);
r.exact = true;
return r;
}
for (int i = 0; i < f->nimps; i++) {
const tr_rec_t *im = &f->imps[i];
if (strcmp(im->a, name) != 0) {
continue;
}
tr_res_t r = im->kind == 's' ? tr_from(c, file, im->spec, NULL, depth)
: im->kind == 'd' ? tr_from(c, file, im->spec, "default", depth)
: tr_from(c, file, im->spec, im->b ? im->b : name, depth);
r.exact = r.kind == TR_NODE;
return r;
}
return tr_mk(TR_NONE);
}
static bool tr_seen(tr_ctx_t *c, int file, const char *name) {
for (int i = 0; i < c->nvisited; i++) {
if (c->visited[i] == file && strcmp(c->visited_name[i], name) == 0) {
return true;
}
}
if (c->nvisited < (int)(sizeof(c->visited) / sizeof(c->visited[0]))) {
c->visited[c->nvisited] = file;
c->visited_name[c->nvisited] = name;
c->nvisited++;
}
return false;
}
static bool tr_same(const tr_res_t *a, const tr_res_t *b) {
return a->kind == b->kind && a->node == b->node && a->file == b->file;
}
/* What file `file` exports as `name`; TR_NONE when it exports no such name. */
static tr_res_t tr_export_of(tr_ctx_t *c, int file, const char *name, int depth) {
if (depth > TR_MAX_DEPTH || tr_seen(c, file, name)) {
return tr_mk(TR_NONE);
}
const tr_file_t *f = &c->ix->files[file];
bool dflt = strcmp(name, "default") == 0;
for (int i = 0; i < f->ndecls; i++) {
const tr_rec_t *d = &f->decls[i];
bool hit = dflt ? (d->kind == 'd' || d->kind == 'b')
: (strcmp(d->a, name) == 0 &&
(d->kind == 'e' || d->kind == 'b' || !f->module_syntax));
if (hit) {
return tr_decl_res(c, f, d->a);
}
}
for (int i = 0; i < f->nlocals; i++) {
if (strcmp(f->locals[i].a, name) == 0) {
return tr_top_binding(c, file, f->locals[i].b, depth + SKIP_ONE);
}
}
for (int i = 0; i < f->nfroms; i++) {
if (strcmp(f->froms[i].a, name) == 0) {
return tr_from(c, file, f->froms[i].spec, f->froms[i].b, depth);
}
}
for (int i = 0; i < f->nstar_as; i++) {
if (strcmp(f->star_as[i].a, name) == 0) {
return tr_from(c, file, f->star_as[i].spec, NULL, depth);
}
}
tr_res_t found = tr_mk(TR_NONE);
for (int i = 0; i < f->nstars && !dflt; i++) {
tr_res_t r = tr_from(c, file, f->stars[i].spec, name, depth);
if (r.kind == TR_NONE || r.kind == TR_NOT_INDEXED) {
continue;
}
if (found.kind == TR_NONE) {
found = r;
} else if (!tr_same(&found, &r)) {
return tr_mk(TR_AMBIGUOUS);
}
}
return found;
}
/* ECMAScript, DOM and Node.js globals: external. Sorted. */
static const char *const TR_LIB[] = {"AbortController",
"AbortSignal",
"AggregateError",
"Array",
"ArrayBuffer",
"ArrayLike",
"AsyncGenerator",
"AsyncIterable",
"AsyncIterableIterator",
"AsyncIterator",
"Atomics",
"Awaited",
"BigInt",
"BigInt64Array",
"BigUint64Array",
"Blob",
"Boolean",
"Buffer",
"CSSStyleDeclaration",
"Capitalize",
"ConstructorParameters",
"CustomEvent",
"DOMException",
"DataView",
"Date",
"Document",
"DocumentFragment",
"Element",
"Error",
"ErrorEvent",
"Event",
"EventListener",
"EventTarget",
"Exclude",
"Extract",
"File",
"FileList",
"Float32Array",
"Float64Array",
"FormData",
"Function",
"Generator",
"HTMLElement",
"Headers",
"Infinity",
"InstanceType",
"Int16Array",
"Int32Array",
"Int8Array",
"Intl",
"Iterable",
"IterableIterator",
"Iterator",
"JSON",
"KeyboardEvent",
"Location",
"Lowercase",
"Map",
"Math",
"MessageEvent",
"MouseEvent",
"MutationObserver",
"NaN",
"Navigator",
"Node",
"NodeJS",
"NodeList",
"NonNullable",
"Number",
"Object",
"Omit",
"OmitThisParameter",
"Parameters",
"Partial",
"Pick",
"Promise",
"PromiseLike",
"PropertyKey",
"Proxy",
"RangeError",
"Readonly",
"ReadonlyArray",
"ReadonlyMap",
"ReadonlySet",
"Record",
"ReferenceError",
"Reflect",
"RegExp",
"Request",
"Required",
"Response",
"ReturnType",
"Set",
"SharedArrayBuffer",
"String",
"Symbol",
"SyntaxError",
"TemplateStringsArray",
"TextDecoder",
"TextEncoder",
"ThisParameterType",
"ThisType",
"TypeError",
"URIError",
"URL",
"URLSearchParams",
"Uint16Array",
"Uint32Array",
"Uint8Array",
"Uint8ClampedArray",
"Uncapitalize",
"Uppercase",
"WeakMap",
"WeakRef",
"WeakSet",
"WebSocket",
"Window",
"Worker",
"XMLHttpRequest",
"__dirname",
"__filename",
"clearInterval",
"clearTimeout",
"console",
"decodeURIComponent",
"document",
"encodeURIComponent",
"exports",
"fetch",
"globalThis",
"isFinite",
"isNaN",
"module",
"parseFloat",
"parseInt",
"process",
"queueMicrotask",
"require",
"setImmediate",
"setInterval",
"setTimeout",
"structuredClone",
"undefined",
"window"};
static int tr_lib_cmp(const void *k, const void *e) {
return strcmp((const char *)k, *(const char *const *)e);
}
static bool tr_lib(const char *name) {
size_t n = strlen(name);
if ((n > TR_HTML_MIN && strncmp(name, "HTML", CBM_SZ_4) == 0 &&
strcmp(name + n - CBM_SZ_7, "Element") == 0) ||
(n > TR_SVG_MIN && strncmp(name, "SVG", CBM_SZ_3) == 0 &&
strcmp(name + n - CBM_SZ_7, "Element") == 0)) {
return true;
}
return bsearch(name, TR_LIB, sizeof(TR_LIB) / sizeof(TR_LIB[0]), sizeof(TR_LIB[0]),
tr_lib_cmp) != NULL;
}
static bool tr_label_container(const char *l) {
return l && (strcmp(l, "Class") == 0 || strcmp(l, "Interface") == 0 || strcmp(l, "Enum") == 0);
}
/* The class, interface or enum whose members a bare name may be: the
* documented declaration itself when it is one, else the one it is a member
* of. NULL: none. */
static const cbm_gbuf_node_t *tr_container(const tr_ctx_t *c, const char *source_qn) {
const cbm_gbuf_node_t *s = cbm_gbuf_find_by_qn(c->g, source_qn);
if (s && tr_label_container(s->label)) {
return s;
}
const char *dot = strrchr(source_qn, '.');
if (!dot || (size_t)(dot - source_qn) >= TR_QN_MAX) {
return NULL;
}
char parent[TR_QN_MAX];
memcpy(parent, source_qn, (size_t)(dot - source_qn));
parent[dot - source_qn] = '\0';
const cbm_gbuf_node_t *p = cbm_gbuf_find_by_qn(c->g, parent);
return p && tr_label_container(p->label) ? p : NULL;
}
static tr_res_t tr_member(const tr_ctx_t *c, const cbm_gbuf_node_t *of, const char *name) {
char qn[TR_QN_MAX];
if (!tr_join(qn, sizeof(qn), of->qualified_name, name, NULL)) {
return tr_mk(TR_MISSING);
}
const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(c->g, qn);
if (n) {
tr_res_t r = tr_mk(TR_NODE);
r.node = n;
r.exact = true;
return r;
}
/* a class, interface or enum member often has no node of its own */
return tr_mk(tr_label_container(of->label) ? TR_GAP : TR_MISSING);
}
/* The first segment, seen from the documented declaration. */
static tr_res_t tr_head(tr_ctx_t *c, const CBMDocLink *link, const char *name) {
const tr_file_t *src = &c->ix->files[c->src];
if (strcmp(name, "this") == 0) {
const cbm_gbuf_node_t *k = tr_container(c, link->source_qn);
tr_res_t r = tr_mk(k ? TR_NODE : TR_MISSING);
r.node = k;
r.exact = true;
return r;
}
/* the namespaces around the reference, innermost first */
const tr_ns_t *best[TR_MAX_SEGS];
int nb = 0;
for (int i = 0; i < src->nnss && nb < TR_MAX_SEGS; i++) {
const tr_ns_t *ns = &src->nss[i];
if (ns->first <= link->line && link->line <= ns->last) {
best[nb++] = ns;
}
}
for (int k = nb - SKIP_ONE; k >= 0; k--) { /* nested ones come later in the blob */
char qn[TR_QN_MAX];
const cbm_gbuf_node_t *n =
tr_join(qn, sizeof(qn), src->sym_qn, best[k]->path, name) ? tr_node(c, qn, src) : NULL;
if (n) {
tr_res_t r = tr_mk(TR_NODE);
r.node = n;
r.exact = true;
return r;
}
}
/* a function or class declared in a function body around the reference,
* innermost first; the graph keeps it under a file-level name, which is
* its own only when the node starts on its line */
const tr_nest_t *vis = NULL;
for (int i = 0; i < src->nnested; i++) {
const tr_nest_t *v = &src->nested[i];
if (strcmp(v->name, name) == 0 && v->first <= link->line && link->line <= v->last &&
(!vis || v->last - v->first < vis->last - vis->first)) {
vis = v;
}
}
if (vis) {
tr_res_t r = tr_decl_res(c, src, name);
if (r.kind == TR_NODE && r.node->start_line != (int)vis->line) {
r = tr_mk(TR_GAP); /* the node is another declaration's of that name */
}
r.exact = true;
return r;
}
tr_res_t r = tr_top_binding(c, c->src, name, 0);
if (r.kind != TR_NONE) {
return r;
}
if (tr_lib(name)) {
return tr_mk(TR_EXTERNAL);
}
const tr_global_t *g = (const tr_global_t *)cbm_ht_get(c->ix->globals, name);
if (g) {
if (g->count > SKIP_ONE) {
return tr_mk(TR_AMBIGUOUS);
}
r = tr_decl_res(c, &c->ix->files[g->file], name);
return r;
}
const cbm_gbuf_node_t *k = tr_container(c, link->source_qn);
if (k) {
r = tr_member(c, k, name);
if (r.kind == TR_NODE) {
return r;
}
}
return tr_mk(TR_MISSING);
}
static bool tr_ident(const char *s, size_t n) {
if (n == 0 || isdigit((unsigned char)s[0])) {
return false;
}
for (size_t i = 0; i < n; i++) {
unsigned char ch = (unsigned char)s[i];
if (!(isalnum(ch) || ch == '_' || ch == '$' || ch >= 0x80)) {
return false;
}
}
return true;
}
/* Split a reference into its segments; false when it is no name path. */
static int tr_segments(char *buf, char **segs) {
size_t n = strlen(buf);
char *paren = strchr(buf, '(');
if (paren) {
if (buf[n - SKIP_ONE] != ')') {
return 0;
}
*paren = '\0'; /* (), (args): one node holds every overload */
}
char *colon = strchr(buf, ':');
if (colon) {
*colon = '\0'; /* a meaning: :class, :0 */
}
int ns = 0;
for (char *p = buf; ns < TR_MAX_SEGS;) {
size_t k = strcspn(p, ".#~");
if (!tr_ident(p, k)) {
return 0;
}
segs[ns++] = p;
if (p[k] == '\0') {
break;
}
p[k] = '\0';
p += k + SKIP_ONE;
}
return ns;
}
static void tr_out(tr_ctx_t *c, tr_res_t r) {
switch (r.kind) {
case TR_NODE: {
const tr_file_t *src = &c->ix->files[c->src];
const char *tp = r.node->file_path;
int tf = tp ? tr_file_at(c->ix, tp) : CBM_NOT_FOUND;
if (tf >= 0 && c->ix->files[tf].test && !src->test) {
c->out->kind = CBM_DOCLINK_UNRESOLVED;
c->out->reason = CBM_DOCLINK_REASON_TEST_ONLY;
return;
}
c->out->kind = CBM_DOCLINK_EDGE;
c->out->target = r.node;
c->out->exact = r.exact;
return;
}
case TR_EXTERNAL:
c->out->reason = CBM_DOCLINK_REASON_EXTERNAL;
break;
case TR_AMBIGUOUS:
c->out->reason = CBM_DOCLINK_REASON_AMBIGUOUS;
break;
case TR_GAP:
c->out->reason = CBM_DOCLINK_REASON_GRAPH_GAP;
break;
case TR_NOT_INDEXED:
c->out->reason = CBM_DOCLINK_REASON_NOT_INDEXED;
break;
default:
c->out->reason = CBM_DOCLINK_REASON_MISSING;
break;
}
c->out->kind = CBM_DOCLINK_UNRESOLVED;
}
static void tr_resolve(const void *index, void *state, int run_file, const CBMDocLink *link,
const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {
(void)state; /* TS/JS keeps no per-file working state */
const tr_index_t *ix = (const tr_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;
}
tr_ctx_t c = {.ix = ix, .g = graph, .src = ix->run_to_file[run_file], .out = out};
char buf[CBM_DOCLINK_TS_REF_MAX + PAIR_LEN];
size_t rl = strlen(link->raw);
char *segs[TR_MAX_SEGS];
int ns = 0;
if (rl <= CBM_DOCLINK_TS_REF_MAX && strncmp(link->raw, "module:", CBM_SZ_7) != 0) {
memcpy(buf, link->raw, rl + SKIP_ONE);
ns = tr_segments(buf, segs);
}
if (ns == 0) {
out->reason = CBM_DOCLINK_REASON_UNPARSEABLE;
return;
}
tr_res_t r = tr_head(&c, link, segs[0]);
for (int i = SKIP_ONE; i < ns && (r.kind == TR_NODE || r.kind == TR_MODULE); i++) {
if (r.kind == TR_MODULE) {
c.nvisited = 0;
r = tr_export_of(&c, r.file, segs[i], 0);
r.kind = r.kind == TR_NONE ? TR_MISSING : r.kind;
} else {
r = tr_member(&c, r.node, segs[i]);
}
}
if (r.kind == TR_MODULE) {
/* a module named by itself: its file */
const cbm_gbuf_node_t *fn =
cbm_pipeline_file_node(graph, ix->project, ix->files[r.file].path);
r = tr_mk(fn ? TR_NODE : TR_GAP);
r.node = fn;
r.exact = true;
}
tr_out(&c, r);
}
/* A top-level declaration (D name flags) declares one name: other files reach
* it through an import of it, so a reference that did either bound it (an
* edge into this file) or names it in its unresolved row. Imports, exports
* and namespaces change how others resolve: GLOBAL. */
static bool tr_removable(const char *line, size_t len, const char **name, size_t *nlen) {
return len > PAIR_LEN && line[0] == 'D' && line[1] == '\t' &&
cbm_doclinks_scope_field(line, len, 1, name, nlen);
}
static int tr_scope_delta(const char *stored, const char *fresh, cbm_doclink_name_fn removed,
void *ud) {
return cbm_doclinks_scope_delta_lines(stored, fresh, tr_removable, removed, ud);
}
const cbm_doclink_resolver_t cbm_doclink_ts_resolver = {
.langs = {CBM_LANG_TYPESCRIPT, CBM_LANG_TSX, CBM_LANG_JAVASCRIPT},
.lang_count = CBM_SZ_3,
.scope_tag = CBM_DOCLINK_TS_SCOPE_TAG,
.build = tr_build,
.destroy = tr_destroy,
.resolve = tr_resolve,
.scope_delta = tr_scope_delta,
};