Skip to content

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.

doc-links(ts): bare specifiers through tsconfig paths and workspace packages

Martin Vogel06e69d0c562c
diff --git a/scripts/memory-core-baseline.txt b/scripts/memory-core-baseline.txt
index 251920e2f..7095384a0 100644
--- a/scripts/memory-core-baseline.txt
+++ b/scripts/memory-core-baseline.txt
@@ -75,7 +75,7 @@ src/pipeline/pass_pkgmap.c 82
src/pipeline/pass_semantic.c 3
src/pipeline/pass_tests.c 3
src/pipeline/pass_usages.c 4
-src/pipeline/path_alias.c 42
+src/pipeline/path_alias.c 40
src/pipeline/pipeline.c 134
src/pipeline/pipeline_delta.c 19
src/pipeline/pipeline_incremental.c 143
diff --git a/src/pipeline/doc_links_ts.c b/src/pipeline/doc_links_ts.c
index db007f37e..c52d2e6da 100644
--- a/src/pipeline/doc_links_ts.c
+++ b/src/pipeline/doc_links_ts.c
@@ -14,8 +14,12 @@
* 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, every bare one is external (package.json and
- * tsconfig.json are not indexed);
+ * 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
@@ -29,7 +33,8 @@
* declares or imports, unique otherwise.
*/
#include "pipeline/doc_links.h"
-#include "pipeline/pipeline_internal.h" /* cbm_pipeline_file_node */
+#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 */
@@ -83,6 +88,8 @@ typedef struct {
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 */
@@ -110,8 +117,11 @@ typedef struct {
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_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;
@@ -266,6 +276,7 @@ static void tr_destroy(void *index) {
}
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);
@@ -298,6 +309,18 @@ static bool tr_add_globals(tr_index_t *ix) {
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) {
@@ -326,6 +349,7 @@ static void *tr_build(const cbm_doclink_build_in_t *in) {
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;
@@ -335,6 +359,16 @@ static void *tr_build(const cbm_doclink_build_in_t *in) {
}
}
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);
@@ -410,7 +444,7 @@ static const tr_rec_t *tr_decl(const tr_file_t *f, const char *name) {
/* 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->module_qn, name, NULL)) {
+ 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);
@@ -461,22 +495,9 @@ static bool tr_norm(const char *dir, size_t dl, const char *rel, char *out, size
return w > 0;
}
-/* The file a module specifier written in file `from` names: -1 with
- * *external for a bare specifier (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'))))) {
- *external = true;
- return CBM_NOT_FOUND;
- }
- 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;
- }
+/* 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};
@@ -508,6 +529,58 @@ static int tr_spec_file(const tr_index_t *ix, int from, const char *spec, bool *
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`. */
@@ -833,9 +906,8 @@ static tr_res_t tr_head(tr_ctx_t *c, const CBMDocLink *link, const char *name) {
}
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->module_qn, best[k]->path, name)
- ? tr_node(c, qn, src)
- : NULL;
+ 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;
diff --git a/src/pipeline/path_alias.c b/src/pipeline/path_alias.c
index ef999e14d..7ef54c369 100644
--- a/src/pipeline/path_alias.c
+++ b/src/pipeline/path_alias.c
@@ -317,11 +317,13 @@ void cbm_path_alias_collection_free(cbm_path_alias_collection_t *coll) {
free(coll);
}
-char *cbm_path_alias_resolve(const cbm_path_alias_map_t *map, const char *module_path) {
- if (!map || !module_path) {
- return NULL;
+bool cbm_path_alias_resolve_into(const cbm_path_alias_map_t *map, const char *module_path,
+ char *out, size_t cap) {
+ if (!map || !module_path || !out || cap == 0) {
+ return false;
}
size_t mod_len = strlen(module_path);
+ int n = CBM_NOT_FOUND;
for (int i = 0; i < map->count; i++) {
const cbm_path_alias_t *e = &map->entries[i];
@@ -339,41 +341,35 @@ char *cbm_path_alias_resolve(const cbm_path_alias_map_t *map, const char *module
strcmp(module_path + mod_len - suffix_len, e->alias_suffix) != 0) {
continue;
}
- size_t wild_len = mod_len - prefix_len - suffix_len;
- const char *wild_start = module_path + prefix_len;
- size_t tp_len = strlen(e->target_prefix);
- size_t ts_len = strlen(e->target_suffix);
- char *result = malloc(tp_len + wild_len + ts_len + 1);
- if (!result) {
- return NULL;
- }
- memcpy(result, e->target_prefix, tp_len);
- memcpy(result + tp_len, wild_start, wild_len);
- memcpy(result + tp_len + wild_len, e->target_suffix, ts_len);
- result[tp_len + wild_len + ts_len] = '\0';
- return strip_resolved_ext(result);
+ int wild_len = (int)(mod_len - prefix_len - suffix_len);
+ n = snprintf(out, cap, "%s%.*s%s", e->target_prefix, wild_len, module_path + prefix_len,
+ e->target_suffix);
+ break;
}
if (strcmp(module_path, e->alias_prefix) == 0) {
- return strip_resolved_ext(strdup(e->target_prefix));
+ n = snprintf(out, cap, "%s", e->target_prefix);
+ break;
}
}
/* baseUrl fallback. Apply only to non-relative imports that look
* sub-path-ish (contain '/' but don't start with '.' or '@'); skips
* obvious package names like "react" or "lodash". */
- if (map->base_url && module_path[0] != '.' && module_path[0] != '@' &&
+ if (n < 0 && map->base_url && module_path[0] != '.' && module_path[0] != '@' &&
strchr(module_path, '/') != NULL) {
- size_t bu_len = strlen(map->base_url);
- size_t need = bu_len + 1 + mod_len + 1;
- char *result = malloc(need);
- if (!result) {
- return NULL;
- }
- snprintf(result, need, "%s/%s", map->base_url, module_path);
- return strip_resolved_ext(result);
+ n = snprintf(out, cap, "%s/%s", map->base_url, module_path);
}
- return NULL;
+ if (n < 0 || (size_t)n >= cap) {
+ return false;
+ }
+ strip_resolved_ext(out);
+ return true;
+}
+
+char *cbm_path_alias_resolve(const cbm_path_alias_map_t *map, const char *module_path) {
+ char buf[CBM_PATH_ALIAS_RESULT_MAX];
+ return cbm_path_alias_resolve_into(map, module_path, buf, sizeof(buf)) ? strdup(buf) : NULL;
}
/* ── Repo walk ─────────────────────────────────────────────────── */
diff --git a/src/pipeline/path_alias.h b/src/pipeline/path_alias.h
index bc462e524..1f981c79e 100644
--- a/src/pipeline/path_alias.h
+++ b/src/pipeline/path_alias.h
@@ -93,4 +93,10 @@ const cbm_path_alias_map_t *cbm_path_alias_find_for_file(const cbm_path_alias_co
* pipeline can consume it. */
char *cbm_path_alias_resolve(const cbm_path_alias_map_t *map, const char *module_path);
+/* The same, written into out (cap bytes, NUL-terminated) instead of a heap
+ * string; false when no alias applies or the path does not fit. */
+enum { CBM_PATH_ALIAS_RESULT_MAX = 4096 };
+bool cbm_path_alias_resolve_into(const cbm_path_alias_map_t *map, const char *module_path,
+ char *out, size_t cap);
+
#endif /* CBM_PATH_ALIAS_H */
diff --git a/tests/test_doc_mentions_ts.c b/tests/test_doc_mentions_ts.c
index 32581e10d..c48c6bf7f 100644
--- a/tests/test_doc_mentions_ts.c
+++ b/tests/test_doc_mentions_ts.c
@@ -144,7 +144,8 @@ static void ts_write_repo(const char *repo) {
"function internal() {}\n");
th_write_file(TH_PATH(repo, "src/def.ts"), "export default class Def {}\n");
th_write_file(TH_PATH(repo, "src/barrel/index.ts"),
- "export * from \"../helper\";\nexport * from \"./more\";\n");
+ "export * from \"../helper\";\nexport * from \"./more\";\n"
+ "export function inBarrel() {}\n");
th_write_file(TH_PATH(repo, "src/barrel/more.ts"), "export function extra() {}\n");
th_write_file(TH_PATH(repo, "src/dup1.ts"), "export function twin() {}\n");
th_write_file(TH_PATH(repo, "src/dup2.ts"), "export function twin() {}\n");
@@ -164,7 +165,17 @@ static void ts_write_repo(const char *repo) {
"}\n");
/* a script: no import, no export, so its names are global */
th_write_file(TH_PATH(repo, "src/global.js"), "function legacyGlobal() {}\n");
+ /* a tsconfig path alias and a workspace package */
+ th_write_file(TH_PATH(repo, "tsconfig.json"),
+ "{ \"compilerOptions\": { \"paths\": { \"@lib/*\": [\"src/lib/*\"] } } }\n");
+ th_write_file(TH_PATH(repo, "src/lib/aliased.ts"), "export function aliased() {}\n");
+ th_write_file(TH_PATH(repo, "packages/util/package.json"),
+ "{ \"name\": \"@acme/util\", \"main\": \"src/index.ts\" }\n");
+ th_write_file(TH_PATH(repo, "packages/util/src/index.ts"), "export function utilFn() {}\n");
th_write_file(TH_PATH(repo, "src/widget.ts"),
+ "import { aliased } from \"@lib/aliased\";\n"
+ "import { utilFn } from \"@acme/util\";\n"
+ "import { inBarrel } from \"./barrel\";\n"
"import { Helper, gadget as g } from \"./helper\";\n"
"import * as ns from \"./helper\";\n"
"import Def from \"./def\";\n"
@@ -177,7 +188,8 @@ static void ts_write_repo(const char *repo) {
" * Links: {@link Helper}, {@link Helper.run}, {@link g}, {@link ns.gadget},\n"
" * {@link Def}, {@link extra}, {@link twin}, {@link Thing}, {@link Gone},\n"
" * {@link Promise}, {@link legacyGlobal}, {@link Nope}, {@link spin},\n"
- " * {@link Space.Inner.deep}, {@link Helper#missingMember}.\n"
+ " * {@link Space.Inner.deep}, {@link Helper#missingMember}, {@link aliased},\n"
+ " * {@link utilFn}, {@link inBarrel}.\n"
" */\n"
"export class Widget {\n"
" spin(): void {}\n"
@@ -247,6 +259,11 @@ TEST(doc_mentions_ts_resolution) {
ASSERT_TRUE(ts_edge(db, w, "src.widget.Space.Inner.deep"));
/* a class member without a node of its own */
ASSERT_TRUE(ts_row(db, "Helper#missingMember", "graph_gap"));
+ /* a tsconfig path alias; a workspace package's entry module */
+ ASSERT_TRUE(ts_edge(db, w, "src.lib.aliased.aliased"));
+ ASSERT_TRUE(ts_edge(db, w, "packages.util.src.utilFn"));
+ /* a declaration of an index file (its QN has no `index`) */
+ ASSERT_TRUE(ts_edge(db, w, "src.barrel.inBarrel"));
/* this. is the container's; a namespace's own names first */
ASSERT_TRUE(ts_edge(db, "src.widget.Widget.turn", "src.widget.Widget.spin"));
ASSERT_TRUE(ts_edge(db, "src.widget.Space.Inner.deep", "src.widget.Space.Inner.deep2"));