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(c): Doxygen @ref and @see names become MENTIONS edges, held until their audit
Martin Vogel80e000a92a2d
diff --git a/Makefile.cbm b/Makefile.cbmindex 4cfb47783..ffb0cb0e7 100644--- a/Makefile.cbm+++ b/Makefile.cbm@@ -392,6 +392,7 @@ EXTRACTION_SRCS = \$(CBM_DIR)/doclink_perl.c \$(CBM_DIR)/doclink_ts.c \$(CBM_DIR)/doclink_php.c \+ $(CBM_DIR)/doclink_c.c \$(CBM_DIR)/sql_values.c \$(CBM_DIR)/helpers.c \$(CBM_DIR)/cpp_branch_views.c \@@ -524,6 +525,7 @@ PIPELINE_SRCS = \src/pipeline/doc_links_perl.c \src/pipeline/doc_links_ts.c \src/pipeline/doc_links_php.c \+ src/pipeline/doc_links_c.c \src/pipeline/doc_links_msbuild.c \src/pipeline/pass_route_nodes.c \src/pipeline/pass_enrichment.c \@@ -786,7 +788,7 @@ TEST_DISCOVER_SRCS = \TEST_GRAPH_BUFFER_SRCS = tests/test_graph_buffer.c-TEST_PIPELINE_SRCS = tests/test_registry.c tests/test_pipeline.c tests/test_pipeline_conventions.c tests/test_pipeline_frozen.c tests/test_importance.c tests/test_cross_repo.c tests/test_fqn.c tests/test_route_canon.c tests/test_path_alias.c tests/test_configlink.c tests/test_doclinks.c tests/test_doc_mentions.c tests/test_doc_links_md.c tests/test_doc_links_pdf.c tests/test_doc_links_rst.c tests/test_doc_links_adoc.c tests/test_doc_mentions_go.c tests/test_doc_mentions_jvm.c tests/test_doc_mentions_rs.c tests/test_doc_mentions_perl.c tests/test_doc_mentions_ts.c tests/test_doc_mentions_php.c tests/test_infrascan.c tests/test_worker_pool.c tests/test_parallel.c tests/test_index_resilience.c tests/test_index_format.c tests/test_call_reference_contract.c tests/repro/repro_call_scope_usages.c tests/repro/repro_call_argument_usages.c tests/repro/repro_reference_precision.c tests/repro/repro_lexical_binding_precision.c tests/repro/repro_call_argument_matrix_a.c tests/repro/repro_call_argument_matrix_b.c tests/repro/repro_call_node_behaviors.c tests/repro/repro_language_registry.c tests/repro/repro_call_node_manifest.c tests/repro/repro_lsp_ordered_signatures.c tests/repro/repro_lsp_ordered_local.c tests/repro/repro_ts_overload_return_chains.c tests/repro/repro_harness_cleanup.c tests/repro/repro_runner_filter.c+TEST_PIPELINE_SRCS = tests/test_registry.c tests/test_pipeline.c tests/test_pipeline_conventions.c tests/test_pipeline_frozen.c tests/test_importance.c tests/test_cross_repo.c tests/test_fqn.c tests/test_route_canon.c tests/test_path_alias.c tests/test_configlink.c tests/test_doclinks.c tests/test_doc_mentions.c tests/test_doc_links_md.c tests/test_doc_links_pdf.c tests/test_doc_links_rst.c tests/test_doc_links_adoc.c tests/test_doc_mentions_go.c tests/test_doc_mentions_jvm.c tests/test_doc_mentions_rs.c tests/test_doc_mentions_perl.c tests/test_doc_mentions_ts.c tests/test_doc_mentions_php.c tests/test_doc_mentions_c.c tests/test_infrascan.c tests/test_worker_pool.c tests/test_parallel.c tests/test_index_resilience.c tests/test_index_format.c tests/test_call_reference_contract.c tests/repro/repro_call_scope_usages.c tests/repro/repro_call_argument_usages.c tests/repro/repro_reference_precision.c tests/repro/repro_lexical_binding_precision.c tests/repro/repro_call_argument_matrix_a.c tests/repro/repro_call_argument_matrix_b.c tests/repro/repro_call_node_behaviors.c tests/repro/repro_language_registry.c tests/repro/repro_call_node_manifest.c tests/repro/repro_lsp_ordered_signatures.c tests/repro/repro_lsp_ordered_local.c tests/repro/repro_ts_overload_return_chains.c tests/repro/repro_harness_cleanup.c tests/repro/repro_runner_filter.cTEST_WATCHER_SRCS = tests/test_watcher.cdiff --git a/internal/cbm/doclink.c b/internal/cbm/doclink.cindex cb65126b1..18a65cef1 100644--- a/internal/cbm/doclink.c+++ b/internal/cbm/doclink.c@@ -152,6 +152,8 @@ typedef struct {/* A document language: the whole file is the documentation, so one scan* of its bytes replaces parse_doc, the file-level doc and the scope. */void (*scan_file)(CBMExtractCtx *ctx);+ void (*loose_docs)(CBMExtractCtx *ctx, const CBMDefinition *file_def,+ cbm_doclink_taken_fn taken);} doclink_lang_t;static const doclink_lang_t DOCLINK_LANGS[] = {@@ -234,6 +236,17 @@ static const doclink_lang_t DOCLINK_LANGS[] = {.scan_scope = cbm_doclink_ts_scan_scope,.scope_tag = CBM_DOCLINK_TS_SCOPE_TAG,.portable_scope = cbm_doclink_ts_portable_scope},+ /* C, and the .h files C++ parses (the hooks skip every other file) */+ {.lang = CBM_LANG_C,+ .parse_doc = cbm_doclink_c_parse_doc,+ .scan_scope = cbm_doclink_c_scan_scope,+ .scope_tag = CBM_DOCLINK_C_SCOPE_TAG,+ .loose_docs = cbm_doclink_c_loose_docs},+ {.lang = CBM_LANG_CPP,+ .parse_doc = cbm_doclink_c_parse_doc,+ .scan_scope = cbm_doclink_c_scan_scope,+ .scope_tag = CBM_DOCLINK_C_SCOPE_TAG,+ .loose_docs = cbm_doclink_c_loose_docs},{.lang = CBM_LANG_PHP,.parse_doc = cbm_doclink_php_parse_doc,.scan_scope = cbm_doclink_php_scan_scope,@@ -359,12 +372,6 @@ static doc_line_ent_t *doc_info_of(CBMExtractCtx *ctx, const char *doc) {return NULL;}-/* A doc not built by doc_run_text keeps the definition's own line. */-static uint32_t doc_line_of(CBMExtractCtx *ctx, const char *doc) {- const doc_line_ent_t *info = doc_info_of(ctx, doc);- return info ? info->line : 0;-}-/* ── Persisted scope ─────────────────────────────────────────────── */char *cbm_doclink_portable_scope(const char *scope) {@@ -461,6 +468,55 @@ static doclink_twin_key_t *twin_keys(CBMExtractCtx *ctx, const char *label, intreturn keys;}+/* True when a doc taken from a definition, or the file's own doc, starts on+ * one of the lines [first, last]. */+static bool doclink_taken(const CBMExtractCtx *ctx, uint32_t first, uint32_t last) {+ const doc_line_map_t *m = (const doc_line_map_t *)ctx->doc_lines;+ for (int i = 0; m && i < m->count; i++) {+ if (m->items[i].parsed && m->items[i].line >= first && m->items[i].line <= last) {+ return true;+ }+ }+ return 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. */+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];+ if (!has_doc && !L->loose_docs) {+ return;+ }+ CBMDocLinkArray *arr = &ctx->result->doc_links;+ int first = arr->count;+ CBMDefinition file_def = {+ .name = ctx->rel_path,+ .qualified_name = ctx->module_qn ? ctx->module_qn : "",+ .label = "File",+ .file_path = ctx->rel_path,+ .start_line = SKIP_ONE,+ .end_line = SKIP_ONE,+ .docstring = file_doc,+ };+ if (has_doc) {+ doc_line_ent_t *info = doc_info_of(ctx, file_doc);+ uint32_t doc_line = info ? info->line : 0;+ L->parse_doc(ctx, &file_def, file_doc, doc_line ? doc_line : file_def.start_line);+ if (info) {+ info->parsed = true;+ }+ }+ if (L->loose_docs) {+ L->loose_docs(ctx, &file_def, doclink_taken);+ }+ for (int i = first; i < arr->count; i++) {+ arr->items[i].flags |= CBM_DOCLINK_FLAG_FILE;+ }+}+void cbm_doclinks_extract(CBMExtractCtx *ctx) {if (!ctx || !ctx->result) {return;@@ -520,29 +576,7 @@ void cbm_doclinks_extract(CBMExtractCtx *ctx) {info->parsed = true;}}- /* The file's own doc: its 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. */- const char *file_doc = ctx->result->module_doc;- if (file_doc && file_doc[0]) {- CBMDocLinkArray *arr = &ctx->result->doc_links;- int first = arr->count;- CBMDefinition file_def = {- .name = ctx->rel_path,- .qualified_name = ctx->module_qn ? ctx->module_qn : "",- .label = "File",- .file_path = ctx->rel_path,- .start_line = SKIP_ONE,- .end_line = SKIP_ONE,- .docstring = file_doc,- };- uint32_t doc_line = doc_line_of(ctx, file_doc);- L->parse_doc(ctx, &file_def, file_doc, doc_line ? doc_line : file_def.start_line);- for (int i = first; i < arr->count; i++) {- arr->items[i].flags |= CBM_DOCLINK_FLAG_FILE;- }- }+ doclink_file_pass(ctx, L);if (L->scan_scope) {ctx->result->doc_scope = L->scan_scope(ctx);}diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.hindex 8e3313009..cce493488 100644--- a/internal/cbm/doclink.h+++ b/internal/cbm/doclink.h@@ -22,6 +22,10 @@* identical on full and incremental runs. Optional.* 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.* 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@@ -106,6 +110,9 @@X(CBM_DOCLINK_TS_SEE, CBM_LANG_TYPESCRIPT, "see", false, false, "MENTIONS") \/* php (doclink_php.c): PHPDoc @see and {@see}; held until their audit passes */ \X(CBM_DOCLINK_PHP_SEE, CBM_LANG_PHP, "see", false, false, "MENTIONS") \+ /* c (doclink_c.c): Doxygen @ref and @see in .c and .h files; held until their audit */ \+ X(CBM_DOCLINK_C_REF, CBM_LANG_C, "doxygen_ref", false, false, "MENTIONS") \+ X(CBM_DOCLINK_C_SEE, CBM_LANG_C, "see", false, false, "MENTIONS") \/* markdown (doclink_md.c): what a document's text names explicitly */ \X(CBM_DOCLINK_MD_LINK, CBM_LANG_MARKDOWN, "link", false, true, "MENTIONS") \X(CBM_DOCLINK_MD_PATH, CBM_LANG_MARKDOWN, "path", false, true, "MENTIONS") \@@ -591,6 +598,26 @@ size_t cbm_doclink_php_qualify(char *out, size_t cap, const char *ns, size_t ns_const cbm_doclink_php_use_t *uses, int nuses, const char *ref,size_t n);+/* ── 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,+ cbm_doclink_taken_fn taken);+const char *cbm_doclink_c_scan_scope(CBMExtractCtx *ctx);++/* C files and the headers C++ parses share one scope tag: one resolver+ * indexes them. The blob holds no line: it is its own persisted form. */+#define CBM_DOCLINK_C_SCOPE_TAG "c1"++/* The longest reference a C token keeps; a longer one is cut just past this+ * length and the resolver reports it as unparseable. */+enum { CBM_DOCLINK_C_REF_MAX = 256 };+/* ── Perl POD (doclink_perl.c) ─────────────────────────────────────── */void cbm_doclink_perl_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,diff --git a/internal/cbm/doclink_c.c b/internal/cbm/doclink_c.cnew file mode 100644index 000000000..fa8ad5c22--- /dev/null+++ b/internal/cbm/doclink_c.c@@ -0,0 +1,760 @@+/*+ * doclink_c.c — C doc-comment references (Doxygen) and the C doc-link scope.+ *+ * Files. Only .c and .h files: a .h is parsed as C++, which does not change+ * that; other C++ and Objective-C sources are not part of this leg.+ *+ * Docs. The four Doxygen comment styles: blocks opening with slash-star-star+ * or slash-star-bang, and runs of lines opening with three slashes or with+ * slash-slash-bang (a `<` after the opener marks a member's trailing doc). A+ * definition's stored doc goes through cbm_doclink_c_parse_doc. Every other+ * Doxygen block of the file outside function bodies (a prototype's doc in a+ * header, which the graph keeps no node for; a group's text) goes through+ * cbm_doclink_c_loose_docs, and its references belong to the file.+ *+ * Tokens:+ * - `@ref name` or `\ref name`, an optional quoted label after it: family+ * doxygen_ref;+ * - the names listed after `@see`, `\see`, `@sa` or `\sa` (the paragraph up+ * to an empty line or the next command at the start of a line) that have+ * the shape of a symbol: `name`, `name()`, `::name`: family see. An+ * explicit @ref inside such a paragraph is a doxygen_ref token.+ * Text inside \code, \verbatim, \dot, \msc or \startuml blocks, a Markdown+ * fence or a code span holds none, nor does the word after \c, \p, \a, \b, \e+ * or \em. A URL is the core's href family.+ *+ * Scope blob, one record per line after the tag line "c1" (tab-separated):+ * D kind link name qn parent a definition the graph has a node for:+ * kind f (function), v (variable), t (type: typedef,+ * struct, union or enum), e (enum constant), r (a+ * struct or union field), m (object-like macro), M+ * (function-like macro); link x (visible in every file:+ * external linkage, or a type, constant or macro of a+ * header) or s (this file only: static, a type,+ * constant or macro of a .c file, a field); qn the+ * node's qualified name; parent the enum of a constant+ * or the struct of a field ("-" for none)+ * A name a Doxygen page, group, anchor or section the file's+ * docs define+ * The blob holds no line, so it is its own persisted form.+ */+#include "doclink.h"++#include "arena.h"+#include "helpers.h"+#include "foundation/constants.h"+#include "foundation/hash_table.h"+#include "foundation/mem_core.h"+#include "tree_sitter/api.h"++#include <ctype.h>+#include <stdint.h>+#include <stdio.h>+#include <stdlib.h>+#include <string.h>++enum { C_OPENER_LEN = 3, C_FENCE_LEN = 3, C_CMD_MAX = 32 };++/* True for a .c or .h file: the only files this leg reads. */+static bool c_leg_file(const char *rel_path) {+ size_t n = rel_path ? strlen(rel_path) : 0;+ return n > PAIR_LEN && rel_path[n - PAIR_LEN] == '.' &&+ (rel_path[n - SKIP_ONE] == 'c' || rel_path[n - SKIP_ONE] == 'h');+}++/* ── Doc lines ───────────────────────────────────────────────────── */++typedef struct {+ const char *p;+ size_t n;+ uint32_t line;+} c_line_t;++static bool c_has(const char *p, size_t n, const char *lit) {+ size_t l = strlen(lit);+ return n >= l && memcmp(p, lit, l) == 0;+}++/* One raw line of a doc comment without its comment marks. */+static c_line_t c_strip_line(const char *s, const char *le, bool first, bool *block,+ uint32_t line) {+ while (s < le && (*s == ' ' || *s == '\t')) {+ s++;+ }+ size_t n = (size_t)(le - s);+ if (first && (c_has(s, n, "/**") || c_has(s, n, "/*!"))) {+ *block = true;+ s += C_OPENER_LEN;+ } else if (!*block && (c_has(s, n, "///") || c_has(s, n, "//!"))) {+ s += C_OPENER_LEN;+ } else if (*block && s < le && *s == '*' && !(s + SKIP_ONE < le && s[SKIP_ONE] == '/')) {+ s++;+ }+ if (s < le && *s == '<') {+ s++; /* a member's trailing doc */+ }+ const char *t = le;+ while (t > s && (t[-SKIP_ONE] == ' ' || t[-SKIP_ONE] == '\t' || t[-SKIP_ONE] == '\r')) {+ t--;+ }+ if (*block && t - s >= PAIR_LEN && t[-SKIP_ONE] == '/' && t[-PAIR_LEN] == '*') {+ t -= PAIR_LEN;+ while (t > s && (t[-SKIP_ONE] == ' ' || t[-SKIP_ONE] == '\t')) {+ t--;+ }+ }+ while (s < t && (*s == ' ' || *s == '\t')) {+ s++;+ }+ return (c_line_t){s, (size_t)(t - s), line};+}++/* The doc's lines without their comment marks. */+static int c_doc_lines(CBMArena *a, const char *doc, uint32_t doc_line, c_line_t **out) {+ int cap = SKIP_ONE;+ for (const char *p = doc; *p; p++) {+ cap += *p == '\n';+ }+ c_line_t *lines = (c_line_t *)cbm_arena_alloc(a, (size_t)cap * sizeof(c_line_t));+ if (!lines) {+ return 0;+ }+ int n = 0;+ bool block = false;+ for (const char *p = doc; n < cap;) {+ const char *le = strchr(p, '\n');+ if (!le) {+ le = p + strlen(p);+ }+ lines[n] = c_strip_line(p, le, n == 0, &block, doc_line + (uint32_t)n);+ n++;+ if (!*le) {+ break;+ }+ p = le + SKIP_ONE;+ }+ *out = lines;+ return n;+}++/* ── Tokens ──────────────────────────────────────────────────────── */++typedef struct {+ CBMExtractCtx *ctx;+ const CBMDefinition *def;+ bool see; /* inside an @see paragraph */+ int verbatim; /* inside a code block: the index of its end command, else -1 */+ bool fence;+} c_emit_t;++static bool c_ident_start(char c) {+ return isalpha((unsigned char)c) || c == '_';+}++static bool c_ident_char(char c) {+ return isalnum((unsigned char)c) || c == '_';+}++static bool c_is_url(const char *t, size_t n) {+ size_t i = 0;+ while (i < n && (isalnum((unsigned char)t[i]) || t[i] == '+' || t[i] == '.' || t[i] == '-')) {+ i++;+ }+ if (i > 0 && i + CBM_SZ_3 <= n && memcmp(t + i, "://", CBM_SZ_3) == 0) {+ return true;+ }+ return (n > CBM_SZ_4 && strncmp(t, "www.", CBM_SZ_4) == 0) ||+ (n > CBM_SZ_7 && strncmp(t, "mailto:", CBM_SZ_7) == 0);+}++static void c_push(const c_emit_t *em, const char *ref, size_t n, int syntax, uint32_t line) {+ if (n == 0) {+ return;+ }+ if (n > CBM_DOCLINK_C_REF_MAX) {+ n = CBM_DOCLINK_C_REF_MAX + SKIP_ONE; /* clipped: the resolver calls it unparseable */+ }+ if (c_is_url(ref, n)) {+ syntax = CBM_DOCLINK_HREF;+ }+ char *copy = cbm_arena_strndup(em->ctx->arena, ref, n);+ if (!copy) {+ return;+ }+ CBMDocLink link = {+ .source_qn = em->def->qualified_name,+ .raw = copy,+ .line = line,+ .def_line = em->def->start_line,+ .syntax = (uint16_t)syntax,+ };+ cbm_doclinks_push(&em->ctx->result->doc_links, em->ctx->arena, link);+}++/* Mark the bytes of a line that sit in a code span or a quoted label. */+static void c_mask(const c_line_t *ln, bool *mask) {+ for (size_t i = 0; i < ln->n;) {+ char q = ln->p[i];+ if (q != '`' && q != '"') {+ i++;+ continue;+ }+ size_t j = i + SKIP_ONE;+ while (j < ln->n && ln->p[j] != q) {+ j++;+ }+ if (j >= ln->n) {+ i++; /* unpaired */+ continue;+ }+ for (size_t k = i; k <= j; k++) {+ mask[k] = true;+ }+ i = j + SKIP_ONE;+ }+}++/* A command at p[i] (`\word` or `@word`, not inside a word or an address):+ * the word's length, else 0. */+static size_t c_command_at(const char *p, size_t i, size_t n) {+ if ((p[i] != '\\' && p[i] != '@') ||+ (i > 0 &&+ (c_ident_char(p[i - SKIP_ONE]) || p[i - SKIP_ONE] == '\\' || p[i - SKIP_ONE] == '@'))) {+ return 0;+ }+ size_t k = i + SKIP_ONE;+ while (k < n && isalpha((unsigned char)p[k])) {+ k++;+ }+ return k - i - SKIP_ONE;+}++static bool c_word_is(const char *w, size_t n, const char *lit) {+ return strlen(lit) == n && memcmp(w, lit, n) == 0;+}++static bool c_inline_cmd(const char *w, size_t n) {+ return c_word_is(w, n, "c") || c_word_is(w, n, "p") || c_word_is(w, n, "a") ||+ c_word_is(w, n, "b") || c_word_is(w, n, "e") || c_word_is(w, n, "em");+}++static const char *const C_BLOCK_OPEN[] = {"code", "verbatim", "dot", "msc", "startuml", NULL};+static const char *const C_BLOCK_CLOSE[] = {"endcode", "endverbatim", "enddot",+ "endmsc", "enduml", NULL};++static int c_block_index(const char *const *list, const char *w, size_t n) {+ for (int i = 0; list[i]; i++) {+ if (c_word_is(w, n, list[i])) {+ return i;+ }+ }+ return CBM_NOT_FOUND;+}++/* The end of the next non-space position of p[j, n). */+static size_t c_skip_space(const char *p, size_t j, size_t n) {+ while (j < n && isspace((unsigned char)p[j])) {+ j++;+ }+ return j;+}++/* `@ref name`: the name after the command (sentence punctuation dropped,+ * `()` kept); returns the position after it. */+static size_t c_ref(const c_emit_t *em, const c_line_t *ln, size_t j, const bool *mask) {+ j = c_skip_space(ln->p, j, ln->n);+ size_t k = j;+ while (k < ln->n && !isspace((unsigned char)ln->p[k]) && ln->p[k] != '"' && !mask[k]) {+ k++;+ }+ size_t e = k;+ while (e > j && strchr(".,;:", ln->p[e - SKIP_ONE])) {+ e--;+ }+ if (e > j && ln->p[e - SKIP_ONE] == ')' && !(e - j >= PAIR_LEN && ln->p[e - PAIR_LEN] == '(')) {+ e--; /* a closing parenthesis of the prose around it */+ }+ c_push(em, ln->p + j, e - j, CBM_DOCLINK_C_REF, ln->line);+ return k;+}++/* A word of an @see paragraph: a token when it has the shape of a symbol. */+static void c_see_word(const c_emit_t *em, const char *w, size_t n, uint32_t line) {+ while (n > 0 && strchr(".,;:", w[n - SKIP_ONE])) {+ n--;+ }+ if (c_is_url(w, n)) {+ c_push(em, w, n, CBM_DOCLINK_HREF, line);+ return;+ }+ size_t i = (n >= PAIR_LEN && w[0] == ':' && w[SKIP_ONE] == ':') ? PAIR_LEN : 0;+ if (i >= n || !c_ident_start(w[i])) {+ return;+ }+ while (i < n && c_ident_char(w[i])) {+ i++;+ }+ if (i + PAIR_LEN == n && w[i] == '(' && w[i + SKIP_ONE] == ')') {+ i = n;+ }+ if (i == n) {+ c_push(em, w, n, CBM_DOCLINK_C_SEE, line);+ }+}++/* One line outside code blocks: commands, and the words of an @see+ * paragraph. */+static void c_line(c_emit_t *em, const c_line_t *ln, const bool *mask) {+ size_t i = 0;+ bool line_start = true;+ while (i < ln->n) {+ if (mask[i] || isspace((unsigned char)ln->p[i]) || ln->p[i] == ',') {+ i++;+ continue;+ }+ size_t cl = c_command_at(ln->p, i, ln->n);+ if (cl > 0) {+ const char *w = ln->p + i + SKIP_ONE;+ size_t j = i + SKIP_ONE + cl;+ if (c_word_is(w, cl, "ref")) {+ i = c_ref(em, ln, j, mask);+ } else if (c_word_is(w, cl, "see") || c_word_is(w, cl, "sa")) {+ em->see = true;+ i = j;+ } else if (c_inline_cmd(w, cl)) {+ j = c_skip_space(ln->p, j, ln->n);+ while (j < ln->n && !isspace((unsigned char)ln->p[j])) {+ j++; /* the word it formats is text */+ }+ i = j;+ } else {+ int open = c_block_index(C_BLOCK_OPEN, w, cl);+ if (open >= 0) {+ em->verbatim = open;+ return;+ }+ if (line_start) {+ em->see = false; /* a new paragraph */+ }+ i = j;+ }+ line_start = false;+ continue;+ }+ size_t k = i;+ while (k < ln->n && !isspace((unsigned char)ln->p[k]) && ln->p[k] != ',' && !mask[k] &&+ c_command_at(ln->p, k, ln->n) == 0) {+ k++;+ }+ if (k == i) {+ k = i + SKIP_ONE;+ } else if (em->see) {+ c_see_word(em, ln->p + i, k - i, ln->line);+ }+ line_start = false;+ i = k;+ }+}++/* The end command of the open code block on this line, if any. */+static bool c_closes_block(const c_line_t *ln, int open) {+ for (size_t i = 0; i < ln->n; i++) {+ size_t cl = c_command_at(ln->p, i, ln->n);+ if (cl && c_word_is(ln->p + i + SKIP_ONE, cl, C_BLOCK_CLOSE[open])) {+ return true;+ }+ }+ return false;+}++static void c_harvest(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,+ uint32_t doc_line) {+ CBMArena *a = ctx->scratch ? ctx->scratch : ctx->arena;+ c_line_t *lines = NULL;+ int n = c_doc_lines(a, doc, doc_line, &lines);+ c_emit_t em = {ctx, def, false, CBM_NOT_FOUND, false};+ for (int i = 0; i < n; i++) {+ const c_line_t *ln = &lines[i];+ if (em.verbatim >= 0) {+ if (c_closes_block(ln, em.verbatim)) {+ em.verbatim = CBM_NOT_FOUND;+ }+ continue;+ }+ if (ln->n >= C_FENCE_LEN &&+ (memcmp(ln->p, "```", C_FENCE_LEN) == 0 || memcmp(ln->p, "~~~", C_FENCE_LEN) == 0)) {+ em.fence = !em.fence;+ continue;+ }+ if (em.fence) {+ continue;+ }+ if (ln->n == 0) {+ em.see = false; /* an empty line ends a paragraph */+ continue;+ }+ bool *mask = (bool *)cbm_arena_calloc(a, ln->n + SKIP_ONE);+ if (!mask) {+ return;+ }+ c_mask(ln, mask);+ c_line(&em, ln, mask);+ }+}++void cbm_doclink_c_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,+ uint32_t doc_line) {+ if (!ctx || !ctx->result || !def || !doc || !def->qualified_name ||+ !c_leg_file(ctx->rel_path)) {+ return;+ }+ c_harvest(ctx, def, doc, doc_line);+}++/* ── Loose docs ──────────────────────────────────────────────────── */++static bool c_kind(TSNode n, const char *k) {+ return !ts_node_is_null(n) && strcmp(ts_node_type(n), k) == 0;+}++/* A comment node's Doxygen style: 'b' a block, 'l' a line, 0 none. */+static char c_doc_style(const char *src, TSNode n) {+ uint32_t b = ts_node_start_byte(n);+ uint32_t e = ts_node_end_byte(n);+ const char *p = src + b;+ size_t len = e - b;+ if (c_has(p, len, "/**/") || c_has(p, len, "/***")) {+ return 0;+ }+ if (c_has(p, len, "/**") || c_has(p, len, "/*!")) {+ return 'b';+ }+ if (c_has(p, len, "////")) {+ return 0;+ }+ return (c_has(p, len, "///") || c_has(p, len, "//!")) ? 'l' : 0;+}++typedef struct {+ CBMExtractCtx *ctx;+ cbm_doclink_taken_fn taken;+ const CBMDefinition *file_def;+ uint32_t start_byte; /* a pending run of line comments */+ uint32_t end_byte;+ uint32_t first;+ uint32_t last;+ bool pending;+} c_loose_t;++static void c_loose_emit(c_loose_t *lw, uint32_t sb, uint32_t eb, uint32_t first, uint32_t last) {+ if (lw->taken(lw->ctx, first, last)) {+ return; /* a definition's doc: harvested with the definition */+ }+ CBMArena *a = lw->ctx->scratch ? lw->ctx->scratch : lw->ctx->arena;+ char *doc = cbm_arena_strndup(a, lw->ctx->source + sb, eb - sb);+ if (doc) {+ c_harvest(lw->ctx, lw->file_def, doc, first);+ }+}++static void c_loose_flush(c_loose_t *lw) {+ if (lw->pending) {+ c_loose_emit(lw, lw->start_byte, lw->end_byte, lw->first, lw->last);+ lw->pending = false;+ }+}++static void c_loose_comment(c_loose_t *lw, TSNode n) {+ char style = c_doc_style(lw->ctx->source, n);+ uint32_t row = ts_node_start_point(n).row + SKIP_ONE;+ if (style == 'l' && lw->pending && row == lw->last + SKIP_ONE) {+ lw->end_byte = ts_node_end_byte(n); /* the run goes on */+ lw->last = row;+ return;+ }+ c_loose_flush(lw);+ if (style == 'l') {+ lw->pending = true;+ lw->start_byte = ts_node_start_byte(n);+ lw->end_byte = ts_node_end_byte(n);+ lw->first = row;+ lw->last = row;+ } else if (style == 'b') {+ c_loose_emit(lw, ts_node_start_byte(n), ts_node_end_byte(n), row,+ ts_node_end_point(n).row + SKIP_ONE);+ }+}++void cbm_doclink_c_loose_docs(CBMExtractCtx *ctx, const CBMDefinition *file_def,+ cbm_doclink_taken_fn taken) {+ if (!ctx || !ctx->result || !file_def || !taken || ts_node_is_null(ctx->root) ||+ !c_leg_file(ctx->rel_path)) {+ return;+ }+ c_loose_t lw = {.ctx = ctx, .taken = taken, .file_def = file_def};+ TSTreeCursor cur = ts_tree_cursor_new(ctx->root);+ for (bool more = ts_tree_cursor_goto_first_child(&cur); more;) {+ TSNode n = ts_tree_cursor_current_node(&cur);+ if (c_kind(n, "comment")) {+ c_loose_comment(&lw, n);+ } else if (ts_node_is_named(n)) {+ c_loose_flush(&lw); /* code between: the run ends */+ }+ /* Doxygen reads no comment inside a function body */+ if (!c_kind(n, "compound_statement") && ts_tree_cursor_goto_first_child(&cur)) {+ continue;+ }+ while (!ts_tree_cursor_goto_next_sibling(&cur)) {+ if (!ts_tree_cursor_goto_parent(&cur)) {+ more = false;+ break;+ }+ }+ }+ ts_tree_cursor_delete(&cur);+ c_loose_flush(&lw);+}++/* ── Scope blob ──────────────────────────────────────────────────── */++typedef struct {+ CBMArena *a;+ char *buf;+ size_t len;+ size_t cap;+ bool oom;+} c_sb_t;++static void c_sb_put(c_sb_t *sb, const char *s, size_t n) {+ if (sb->oom) {+ return;+ }+ if (sb->len + n + SKIP_ONE > sb->cap) {+ size_t ncap = sb->cap ? sb->cap * PAIR_LEN : CBM_SZ_256;+ while (ncap < sb->len + n + SKIP_ONE) {+ ncap *= PAIR_LEN;+ }+ char *grown = (char *)cbm_arena_alloc(sb->a, ncap);+ if (!grown) {+ sb->oom = true;+ return;+ }+ if (sb->len) {+ memcpy(grown, sb->buf, sb->len);+ }+ sb->buf = grown;+ sb->cap = ncap;+ }+ memcpy(sb->buf + sb->len, s, n);+ sb->len += n;+ sb->buf[sb->len] = '\0';+}++static void c_sb_field(c_sb_t *sb, const char *s, size_t n) {+ c_sb_put(sb, "\t", SKIP_ONE);+ for (size_t i = 0; i < n; i++) {+ char c = (s[i] == '\t' || s[i] == '\n' || s[i] == '\r') ? ' ' : s[i];+ c_sb_put(sb, &c, SKIP_ONE);+ }+}++/* The name a declarator declares (through pointers, arrays, functions and+ * parentheses). */+static TSNode c_declarator_name(TSNode d) {+ for (int guard = 0; guard < CBM_SZ_32 && !ts_node_is_null(d); guard++) {+ if (c_kind(d, "identifier") || c_kind(d, "type_identifier")) {+ return d;+ }+ TSNode inner = ts_node_child_by_field_name(d, TS_FIELD("declarator"));+ if (ts_node_is_null(inner)) {+ inner = ts_node_named_child(d, 0); /* a parenthesized declarator */+ }+ d = inner;+ }+ return (TSNode){0};+}++static bool c_is_static(const char *src, TSNode decl) {+ uint32_t nc = ts_node_named_child_count(decl);+ for (uint32_t i = 0; i < nc; i++) {+ TSNode c = ts_node_named_child(decl, i);+ if (!c_kind(c, "storage_class_specifier")) {+ continue;+ }+ uint32_t b = ts_node_start_byte(c);+ uint32_t e = ts_node_end_byte(c);+ if (e - b == CBM_SZ_6 && memcmp(src + b, "static", CBM_SZ_6) == 0) {+ return true;+ }+ }+ return false;+}++/* The names a static declaration or definition declares. */+static void c_static_names(CBMExtractCtx *ctx, CBMHashTable *names, TSNode decl) {+ if (!c_is_static(ctx->source, decl)) {+ return;+ }+ TSTreeCursor cur = ts_tree_cursor_new(decl);+ for (bool more = ts_tree_cursor_goto_first_child(&cur); more;+ more = ts_tree_cursor_goto_next_sibling(&cur)) {+ const char *field = ts_tree_cursor_current_field_name(&cur);+ if (!field || strcmp(field, "declarator") != 0) {+ continue;+ }+ TSNode name = c_declarator_name(ts_tree_cursor_current_node(&cur));+ if (ts_node_is_null(name)) {+ continue;+ }+ uint32_t b = ts_node_start_byte(name);+ char *key = cbm_arena_strndup(ctx->arena, ctx->source + b, ts_node_end_byte(name) - b);+ if (key) {+ cbm_ht_set(names, key, (void *)(uintptr_t)SKIP_ONE);+ }+ }+ ts_tree_cursor_delete(&cur);+}++/* The static names of the file: top-level declarations, also inside+ * preprocessor conditionals and extern "C" blocks. */+static void c_collect_static(CBMExtractCtx *ctx, CBMHashTable *names) {+ TSTreeCursor cur = ts_tree_cursor_new(ctx->root);+ for (bool more = ts_tree_cursor_goto_first_child(&cur); more;) {+ TSNode n = ts_tree_cursor_current_node(&cur);+ bool container = c_kind(n, "preproc_if") || c_kind(n, "preproc_ifdef") ||+ c_kind(n, "preproc_else") || c_kind(n, "preproc_elif") ||+ c_kind(n, "preproc_elifdef") || c_kind(n, "linkage_specification") ||+ c_kind(n, "declaration_list");+ if (c_kind(n, "function_definition") || c_kind(n, "declaration")) {+ c_static_names(ctx, names, n);+ }+ if (container && ts_tree_cursor_goto_first_child(&cur)) {+ continue;+ }+ while (!ts_tree_cursor_goto_next_sibling(&cur)) {+ if (!ts_tree_cursor_goto_parent(&cur)) {+ more = false;+ break;+ }+ }+ }+ ts_tree_cursor_delete(&cur);+}++static char c_def_kind(const CBMDefinition *d) {+ const char *l = d->label;+ if (strcmp(l, "Function") == 0) {+ return 'f';+ }+ if (strcmp(l, "Variable") == 0) {+ return d->parent_class ? 'e' : 'v';+ }+ if (strcmp(l, "Field") == 0) {+ return 'r';+ }+ if (strcmp(l, "Macro") == 0) {+ return d->signature ? 'M' : 'm';+ }+ if (strcmp(l, "Type") == 0 || strcmp(l, "Class") == 0 || strcmp(l, "Enum") == 0) {+ return 't';+ }+ return 0;+}++/* `\page name`, `\defgroup name` ... in one doc text: A records. */+static void c_anchors(c_sb_t *sb, const char *doc) {+ static const char *const cmds[] = {"page", "defgroup", "addtogroup", "anchor",+ "section", "subsection", "subsubsection", NULL};+ size_t n = strlen(doc);+ for (size_t i = 0; i < n; i++) {+ size_t cl = c_command_at(doc, i, n);+ if (!cl) {+ continue;+ }+ bool hit = false;+ for (int k = 0; cmds[k] && !hit; k++) {+ hit = c_word_is(doc + i + SKIP_ONE, cl, cmds[k]);+ }+ size_t j = i + SKIP_ONE + cl;+ if (!hit || j >= n || (doc[j] != ' ' && doc[j] != '\t')) {+ continue;+ }+ j = c_skip_space(doc, j, n);+ size_t k = j;+ while (k < n && (c_ident_char(doc[k]) || doc[k] == '.' || doc[k] == '-')) {+ k++;+ }+ if (k > j) {+ c_sb_put(sb, "\nA", PAIR_LEN);+ c_sb_field(sb, doc + j, k - j);+ }+ i = k;+ }+}++/* The anchors every Doxygen comment of the file defines. */+static void c_scope_anchors(CBMExtractCtx *ctx, c_sb_t *sb) {+ TSTreeCursor cur = ts_tree_cursor_new(ctx->root);+ for (bool more = ts_tree_cursor_goto_first_child(&cur); more;) {+ TSNode n = ts_tree_cursor_current_node(&cur);+ if (c_kind(n, "comment") && c_doc_style(ctx->source, n)) {+ uint32_t b = ts_node_start_byte(n);+ char *text = cbm_arena_strndup(sb->a, ctx->source + b, ts_node_end_byte(n) - b);+ if (text) {+ c_anchors(sb, text);+ }+ }+ if (!c_kind(n, "compound_statement") && ts_tree_cursor_goto_first_child(&cur)) {+ continue;+ }+ while (!ts_tree_cursor_goto_next_sibling(&cur)) {+ if (!ts_tree_cursor_goto_parent(&cur)) {+ more = false;+ break;+ }+ }+ }+ ts_tree_cursor_delete(&cur);+}++const char *cbm_doclink_c_scan_scope(CBMExtractCtx *ctx) {+ if (!ctx || !ctx->result || ts_node_is_null(ctx->root) || !c_leg_file(ctx->rel_path)) {+ return NULL;+ }+ c_sb_t sb = {.a = ctx->arena};+ c_sb_put(&sb, CBM_DOCLINK_C_SCOPE_TAG, strlen(CBM_DOCLINK_C_SCOPE_TAG));+ CBMHashTable *statics = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, CBM_SZ_32);+ CBMHashTable *seen = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, CBM_SZ_64);+ if (!statics || !seen) {+ cbm_ht_free(statics);+ cbm_ht_free(seen);+ return NULL;+ }+ c_collect_static(ctx, statics);+ size_t pl = strlen(ctx->rel_path);+ bool header = ctx->rel_path[pl - SKIP_ONE] == 'h';+ const CBMDefArray *defs = &ctx->result->defs;+ for (int i = 0; i < defs->count && !sb.oom; i++) {+ const CBMDefinition *d = &defs->items[i];+ char kind = (d->label && d->name && d->qualified_name) ? c_def_kind(d) : 0;+ if (!kind || cbm_ht_get(seen, d->qualified_name)) {+ continue; /* one node per qualified name (#if variants) */+ }+ cbm_ht_set(seen, d->qualified_name, (void *)(uintptr_t)SKIP_ONE);+ bool object = kind == 'f' || kind == 'v';+ char link = object ? (cbm_ht_get(statics, d->name) ? 's' : 'x')+ : (header && kind != 'r' ? 'x' : 's');+ c_sb_put(&sb, "\nD", PAIR_LEN);+ c_sb_field(&sb, &kind, SKIP_ONE);+ c_sb_field(&sb, &link, SKIP_ONE);+ c_sb_field(&sb, d->name, strlen(d->name));+ c_sb_field(&sb, d->qualified_name, strlen(d->qualified_name));+ const char *parent =+ (kind == 'e' || kind == 'r') && d->parent_class ? d->parent_class : "-";+ c_sb_field(&sb, parent, strlen(parent));+ }+ cbm_ht_free(statics);+ cbm_ht_free(seen);+ c_scope_anchors(ctx, &sb);+ return sb.oom ? NULL : sb.buf;+}diff --git a/src/pipeline/doc_links.c b/src/pipeline/doc_links.cindex 802665a35..a71aefb5c 100644--- a/src/pipeline/doc_links.c+++ b/src/pipeline/doc_links.c@@ -48,7 +48,7 @@ static const cbm_doclink_resolver_t *const DOCLINK_RESOLVERS[] = {&cbm_doclink_cs_resolver, &cbm_doclink_md_resolver, &cbm_doclink_pdf_resolver,&cbm_doclink_rst_resolver, &cbm_doclink_adoc_resolver, &cbm_doclink_go_resolver,&cbm_doclink_jvm_resolver, &cbm_doclink_rs_resolver, &cbm_doclink_perl_resolver,- &cbm_doclink_ts_resolver, &cbm_doclink_php_resolver,+ &cbm_doclink_ts_resolver, &cbm_doclink_php_resolver, &cbm_doclink_c_resolver,};enum { DOCLINK_RESOLVER_COUNT = sizeof(DOCLINK_RESOLVERS) / sizeof(DOCLINK_RESOLVERS[0]) };diff --git a/src/pipeline/doc_links.h b/src/pipeline/doc_links.hindex 11ab9ec34..9ae1e07c7 100644--- a/src/pipeline/doc_links.h+++ b/src/pipeline/doc_links.h@@ -301,6 +301,7 @@ extern const cbm_doclink_resolver_t cbm_doclink_rs_resolver;extern const cbm_doclink_resolver_t cbm_doclink_perl_resolver;extern const cbm_doclink_resolver_t cbm_doclink_ts_resolver;extern const cbm_doclink_resolver_t cbm_doclink_php_resolver;+extern const cbm_doclink_resolver_t cbm_doclink_c_resolver;/* True when `rel_path` is a scope input of some language (scope_input). */bool cbm_doclinks_is_scope_input(const char *rel_path);diff --git a/src/pipeline/doc_links_c.c b/src/pipeline/doc_links_c.cnew file mode 100644index 000000000..044d69852--- /dev/null+++ b/src/pipeline/doc_links_c.c@@ -0,0 +1,481 @@+/*+ * doc_links_c.c — resolving C doc references (doclink_c.c): Doxygen @ref and+ * @see names, with the lookup Doxygen itself has, which knows no imports.+ *+ * A name (`name`, `name()`, `::name`) is looked up+ * 1. among the Doxygen pages, groups, anchors and sections of the+ * repository's docs: such a name is no code entity (a graph gap), and+ * never binds to a symbol of the same name;+ * 2. among the definitions of the documented file, static ones included;+ * 3. among the definitions every file sees: external linkage, and the types,+ * enum constants and macros of headers. A static definition of another+ * file is not visible.+ * A field of the documented file (`@ref field`) comes after its other+ * definitions and before what every file sees. `Type::member` names a field+ * of the struct or union Type, or a constant of the enum Type, Type found by+ * the same levels.+ * The first level with a candidate decides. Its candidates are counted by+ * qualified name: a prototype and its definition, and the #if variants of+ * one definition, are one node, the one the graph keeps for that name. A+ * definition (function, variable, type, enum constant) wins over a macro of+ * the same name; with `()` written, a function or function-like macro wins+ * over the others. One candidate binds (exact in the documented file,+ * unique elsewhere), several are ambiguous, none is missing; but a word of an+ * @see paragraph that names nothing and is a plain lowercase word (no `_`,+ * digit, capital, `()` or `::`) is prose, which Doxygen prints as text: no+ * row. Test code binds only from test code.+ */+#include "pipeline/doc_links.h"+#include "cbm.h"+#include "doclink.h"+#include "helpers.h" /* 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 { CR_FIELDS = 6, CR_NAME_MAX = 256, CR_CANDS = 64, CR_QN_MAX = 2048 };++/* ── The index ───────────────────────────────────────────────────── */++typedef struct {+ int file;+ char kind; /* f v t e r m M */+ bool global;+ const char *name;+ const char *qn;+ const char *parent; /* the enum of a constant, the struct of a field; NULL */+ int next; /* the next definition of the same name, or -1 */+} cr_def_t;++typedef struct {+ const char *path;+ bool test;+} cr_file_t;++typedef struct {+ CBMArena arena;+ cr_file_t *files;+ int nfiles;+ int *run_to_file;+ int run_count;+ cr_def_t *defs;+ int ndefs;+ int cap_defs;+ CBMHashTable *by_name; /* name -> the first definition's index + 1 */+ CBMHashTable *anchors; /* a Doxygen page, group, anchor or section name */+ CBMHashTable *by_path; /* rel_path -> file index + 1 */+ bool oom;+} cr_index_t;++static const char *cr_copy(cr_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 cr_grow(cr_index_t *ix) {+ if (ix->ndefs < ix->cap_defs) {+ return true;+ }+ int ncap = ix->cap_defs ? ix->cap_defs * PAIR_LEN : CBM_SZ_64;+ cr_def_t *g = (cr_def_t *)cbm_arena_alloc(&ix->arena, (size_t)ncap * sizeof(cr_def_t));+ if (!g) {+ ix->oom = true;+ return false;+ }+ if (ix->ndefs) {+ memcpy(g, ix->defs, (size_t)ix->ndefs * sizeof(cr_def_t));+ }+ ix->defs = g;+ ix->cap_defs = ncap;+ return true;+}++static void cr_read_record(cr_index_t *ix, int fi, const char **fl, const size_t *ln, int n) {+ if (fl[0][0] == 'D' && n >= CR_FIELDS - SKIP_ONE && cr_grow(ix)) { /* parent optional */+ cr_def_t *d = &ix->defs[ix->ndefs++];+ d->file = fi;+ d->kind = fl[1][0];+ d->global = fl[PAIR_LEN][0] == 'x';+ d->name = cr_copy(ix, fl[CBM_SZ_3], ln[CBM_SZ_3]);+ d->qn = cr_copy(ix, fl[CBM_SZ_4], ln[CBM_SZ_4]);+ bool none = n <= CBM_SZ_5 || (ln[CBM_SZ_5] == SKIP_ONE && fl[CBM_SZ_5][0] == '-');+ d->parent = none ? NULL : cr_copy(ix, fl[CBM_SZ_5], ln[CBM_SZ_5]);+ d->next = CBM_NOT_FOUND;+ } else if (fl[0][0] == 'A' && n >= PAIR_LEN) {+ const char *name = cr_copy(ix, fl[1], ln[1]);+ if (name && !cbm_ht_get(ix->anchors, name)) {+ cbm_ht_set(ix->anchors, name, (void *)(uintptr_t)SKIP_ONE);+ }+ }+}++static void cr_read_blob(cr_index_t *ix, 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[CR_FIELDS];+ size_t ln[CR_FIELDS];+ int n = 0;+ const char *s = b;+ for (const char *p = b; p <= e && n < CR_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) {+ cr_read_record(ix, fi, fl, ln, n);+ }+ line = *e ? e : NULL;+ }+}++static void cr_destroy(void *index) {+ cr_index_t *ix = (cr_index_t *)index;+ if (!ix) {+ return;+ }+ cbm_ht_free(ix->by_name);+ cbm_ht_free(ix->anchors);+ 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);+}++/* Chain every definition into its name's list, in index order. */+static bool cr_link(cr_index_t *ix) {+ ix->by_name = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, (uint32_t)(ix->ndefs + SKIP_ONE));+ if (!ix->by_name) {+ return false;+ }+ for (int i = ix->ndefs - SKIP_ONE; i >= 0; i--) {+ cr_def_t *d = &ix->defs[i];+ if (!d->name || !d->qn) {+ continue;+ }+ void *prev = cbm_ht_get(ix->by_name, d->name);+ d->next = prev ? (int)((uintptr_t)prev - SKIP_ONE) : CBM_NOT_FOUND;+ cbm_ht_set(ix->by_name, d->name, (void *)(uintptr_t)(i + SKIP_ONE));+ }+ return true;+}++static void *cr_build(const cbm_doclink_build_in_t *in) {+ cr_index_t *ix = (cr_index_t *)cbm_calloc(CBM_MEM_CLASS_OTHER, sizeof(*ix));+ if (!ix) {+ return NULL;+ }+ cbm_arena_init(&ix->arena);+ ix->nfiles = in->file_count;+ ix->run_count = in->run_file_count;+ ix->files =+ in->file_count+ ? (cr_file_t *)cbm_arena_calloc(&ix->arena, (size_t)in->file_count * sizeof(cr_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));+ ix->anchors = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, CBM_SZ_64);+ bool ok = (!in->file_count || ix->files) && ix->run_to_file && ix->by_path && ix->anchors;+ 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];+ cr_file_t *f = &ix->files[i];+ f->path = src->rel_path;+ f->test = cbm_is_test_file(src->rel_path, CBM_LANG_C);+ 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) {+ cr_read_blob(ix, i, src->scope);+ }+ }+ ok = ok && !ix->oom && cr_link(ix);+ if (!ok) {+ cbm_log_error("doc_links.c.error", "step", "index", "reason", "alloc");+ cr_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->ndefs);+ snprintf(b[PAIR_LEN], sizeof(b[PAIR_LEN]), "%u", cbm_ht_count(ix->anchors));+ cbm_log_info("doc_links.c.index", "files", b[0], "definitions", b[SKIP_ONE], "anchors",+ b[PAIR_LEN]);+ return ix;+}++/* ── Resolution ──────────────────────────────────────────────────── */++/* The candidates of one level, one per qualified name. */+typedef struct {+ const cr_def_t *items[CR_CANDS];+ int n;+ bool full; /* more than CR_CANDS: ambiguous */+} cr_cands_t;++static void cr_add(cr_cands_t *c, const cr_def_t *d) {+ for (int i = 0; i < c->n; i++) {+ if (strcmp(c->items[i]->qn, d->qn) == 0) {+ return;+ }+ }+ if (c->n == CR_CANDS) {+ c->full = true;+ return;+ }+ c->items[c->n++] = d;+}++static bool cr_macro(const cr_def_t *d) {+ return d->kind == 'm' || d->kind == 'M';+}++static bool cr_callable(const cr_def_t *d) {+ return d->kind == 'f' || d->kind == 'M';+}++/* Keep the candidates `keep` accepts, when there is one. */+static void cr_prefer(cr_cands_t *c, bool (*keep)(const cr_def_t *), bool want) {+ int k = 0;+ for (int i = 0; i < c->n; i++) {+ k += keep(c->items[i]) == want;+ }+ if (k == 0 || k == c->n) {+ return;+ }+ int w = 0;+ for (int i = 0; i < c->n; i++) {+ if (keep(c->items[i]) == want) {+ c->items[w++] = c->items[i];+ }+ }+ c->n = w;+}++enum { CR_LEVEL_OWN = 0, CR_LEVEL_FIELD = 1, CR_LEVEL_GLOBAL = 2, CR_LEVELS = 3 };++/* The definitions of `name` one level sees: the documented file's own (any+ * linkage, fields apart), its fields, or those every file sees. */+static void cr_level(const cr_index_t *ix, const char *name, int src, int level, cr_cands_t *c) {+ void *v = cbm_ht_get(ix->by_name, name);+ for (int i = v ? (int)((uintptr_t)v - SKIP_ONE) : CBM_NOT_FOUND; i >= 0; i = ix->defs[i].next) {+ const cr_def_t *d = &ix->defs[i];+ bool field = d->kind == 'r';+ bool in = level == CR_LEVEL_GLOBAL ? d->global+ : d->file == src && field == (level == CR_LEVEL_FIELD);+ if (in) {+ cr_add(c, d);+ }+ }+}++static void cr_out_node(const cr_index_t *ix, int src, const cr_def_t *d, bool exact,+ const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {+ const cbm_gbuf_node_t *node = cbm_gbuf_find_by_qn(graph, d->qn);+ if (!node || !node->label) {+ out->reason = CBM_DOCLINK_REASON_GRAPH_GAP;+ return;+ }+ if (ix->files[d->file].test && !ix->files[src].test) {+ out->reason = CBM_DOCLINK_REASON_TEST_ONLY;+ return;+ }+ out->kind = CBM_DOCLINK_EDGE;+ out->target = node;+ out->exact = exact;+}++static bool cr_ident(const char *s, size_t n) {+ if (n == 0 || !(isalpha((unsigned char)s[0]) || s[0] == '_')) {+ return false;+ }+ for (size_t i = 0; i < n; i++) {+ if (!isalnum((unsigned char)s[i]) && s[i] != '_') {+ return false;+ }+ }+ return true;+}++/* The name of a reference, `::` in front and `()` behind dropped, and the+ * type of `Type::member` (scope, "" for none); false when it is no C name. */+static bool cr_name(const char *raw, char *out, char *scope, size_t cap, bool *call) {+ size_t n = strlen(raw);+ if (n >= PAIR_LEN && raw[0] == ':' && raw[SKIP_ONE] == ':') {+ raw += PAIR_LEN;+ n -= PAIR_LEN;+ }+ *call = n >= PAIR_LEN && raw[n - PAIR_LEN] == '(' && raw[n - SKIP_ONE] == ')';+ if (*call) {+ n -= PAIR_LEN;+ }+ scope[0] = '\0';+ const char *sep = NULL;+ for (size_t i = 0; i + SKIP_ONE < n && !sep; i++) {+ sep = raw[i] == ':' && raw[i + SKIP_ONE] == ':' ? raw + i : NULL;+ }+ if (sep) {+ size_t sl = (size_t)(sep - raw);+ if (sl >= cap || !cr_ident(raw, sl)) {+ return false;+ }+ memcpy(scope, raw, sl);+ scope[sl] = '\0';+ n -= sl + PAIR_LEN;+ raw = sep + PAIR_LEN;+ }+ if (n >= cap || !cr_ident(raw, n)) {+ return false;+ }+ memcpy(out, raw, n);+ out[n] = '\0';+ return true;+}++static bool cr_type(const cr_def_t *d) {+ return d->kind == 't';+}++/* `Type::member`: the type by the usual levels, then its field (a node at+ * the type's qualified name + `.` + member) or its enum constant. */+static void cr_member(const cr_index_t *ix, int src, const char *scope, const char *name,+ const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {+ const cr_def_t *type = NULL;+ for (int level = 0; level < CR_LEVELS && !type; level++) {+ cr_cands_t c = {.n = 0};+ cr_level(ix, scope, src, level, &c);+ cr_prefer(&c, cr_type, true);+ if (c.n == 0 || !cr_type(c.items[0])) {+ continue;+ }+ if (c.full || c.n > SKIP_ONE) {+ out->reason = CBM_DOCLINK_REASON_AMBIGUOUS;+ return;+ }+ type = c.items[0];+ }+ if (!type) {+ return; /* missing */+ }+ char qn[CR_QN_MAX];+ int n = snprintf(qn, sizeof(qn), "%s.%s", type->qn, name);+ cr_def_t field = {.file = type->file, .kind = 'r', .name = name, .qn = qn};+ if (n > 0 && (size_t)n < sizeof(qn) && cbm_gbuf_find_by_qn(graph, qn)) {+ cr_out_node(ix, src, &field, true, graph, out);+ return;+ }+ void *v = cbm_ht_get(ix->by_name, name);+ for (int i = v ? (int)((uintptr_t)v - SKIP_ONE) : CBM_NOT_FOUND; i >= 0; i = ix->defs[i].next) {+ const cr_def_t *d = &ix->defs[i];+ if (d->kind == 'e' && d->parent && strcmp(d->parent, type->qn) == 0) {+ cr_out_node(ix, src, d, true, graph, out);+ return;+ }+ }+}++/* A plain lowercase word: what an @see paragraph's prose is made of. */+static bool cr_plain_word(const char *s) {+ for (; *s; s++) {+ if (*s < 'a' || *s > 'z') {+ return false;+ }+ }+ return true;+}++static void cr_resolve_name(const cr_index_t *ix, int src, const CBMDocLink *link,+ const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out);++static void cr_resolve(const void *index, void *state, int run_file, const CBMDocLink *link,+ const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {+ (void)state; /* C keeps no per-file working state */+ const cr_index_t *ix = (const cr_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;+ }+ int src = ix->run_to_file[run_file];+ cr_resolve_name(ix, src, link, graph, out);+ if (link->syntax == CBM_DOCLINK_C_SEE && out->kind == CBM_DOCLINK_UNRESOLVED &&+ out->reason == CBM_DOCLINK_REASON_MISSING && cr_plain_word(link->raw)) {+ out->kind = CBM_DOCLINK_LOCAL; /* prose: Doxygen prints it as text */+ }+}++static void cr_resolve_name(const cr_index_t *ix, int src, const CBMDocLink *link,+ const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {+ if (cbm_ht_get(ix->anchors, link->raw)) {+ out->reason = CBM_DOCLINK_REASON_GRAPH_GAP; /* a page, group or anchor */+ return;+ }+ char name[CR_NAME_MAX];+ char scope[CR_NAME_MAX];+ bool call = false;+ if (strlen(link->raw) > CBM_DOCLINK_C_REF_MAX ||+ !cr_name(link->raw, name, scope, sizeof(name), &call)) {+ out->reason = CBM_DOCLINK_REASON_UNPARSEABLE;+ return;+ }+ if (scope[0]) {+ cr_member(ix, src, scope, name, graph, out);+ return;+ }+ if (cbm_ht_get(ix->anchors, name)) {+ out->reason = CBM_DOCLINK_REASON_GRAPH_GAP;+ return;+ }+ for (int level = 0; level < CR_LEVELS; level++) {+ cr_cands_t c = {.n = 0};+ cr_level(ix, name, src, level, &c);+ if (c.n == 0) {+ continue;+ }+ if (call) {+ cr_prefer(&c, cr_callable, true); /* `()` written: what can be called */+ }+ cr_prefer(&c, cr_macro, false); /* then a definition before a macro */+ if (c.full || c.n > SKIP_ONE) {+ out->reason = CBM_DOCLINK_REASON_AMBIGUOUS;+ return;+ }+ cr_out_node(ix, src, c.items[0], level != CR_LEVEL_GLOBAL, graph, out);+ return;+ }+}++const cbm_doclink_resolver_t cbm_doclink_c_resolver = {+ .langs = {CBM_LANG_C, CBM_LANG_CPP},+ .lang_count = PAIR_LEN,+ .scope_tag = CBM_DOCLINK_C_SCOPE_TAG,+ .build = cr_build,+ .destroy = cr_destroy,+ .resolve = cr_resolve,+};diff --git a/tests/test_doc_mentions_c.c b/tests/test_doc_mentions_c.cnew file mode 100644index 000000000..b4fe96e84--- /dev/null+++ b/tests/test_doc_mentions_c.c@@ -0,0 +1,341 @@+/*+ * test_doc_mentions_c.c -- C doc-comment references (Doxygen @ref, @see).+ */+#include "../src/foundation/compat.h"+#include "test_framework.h"+#include "test_helpers.h"+#include "test_doc_mentions_helpers.h"++#include "cbm.h"+#include "doclink.h"++#include <stdio.h>+#include <stdlib.h>+#include <string.h>++/* ── extraction ──────────────────────────────────────────────────── */++static const char *const C_WIDGET =+ "#include \"api.h\"\n" /* 1 */+ "\n" /* 2 */+ "/**\n" /* 3 */+ " * Makes widgets. @ref widget_free \"free it\" and \\ref api_counter.\n" /* 4 */+ " * Not `@ref Hidden` nor \"@ref Quoted\".\n" /* 5 */+ " * @code\n" /* 6 */+ " * @ref InCode\n" /* 7 */+ " * @endcode\n" /* 8 */+ " * ```\n" /* 9 */+ " * @ref Fenced\n" /* 10 */+ " * ```\n" /* 11 */+ " * @see widget_free(), helper, ::api_counter, https://example.com/w\n" /* 12 */+ " * also_this\n" /* 13 */+ " *\n" /* 14 */+ " * after_blank\n" /* 15 */+ " * \\sa \\c not_this, Other_thing.\n" /* 16 */+ " * @param n not_a_see\n" /* 17 */+ " */\n" /* 18 */+ "int widget_new(int n) { return n; }\n" /* 19 */+ "\n" /* 20 */+ "/// Line doc. @ref API_MAX\n" /* 21 */+ "/// @sa widget_new()\n" /* 22 */+ "static int helper(int x) { return x; }\n" /* 23 */+ "\n" /* 24 */+ "/** @defgroup grp The group */\n" /* 25 */+ "\n" /* 26 */+ "/** A prototype's doc: @ref grp and @ref widget_new. */\n" /* 27 */+ "int f2(void);\n" /* 28 */+ "#define API_MAX 3\n" /* 29 */+ "#define TWICE(x) ((x) * 2)\n" /* 30 */+ "static int counter;\n" /* 31 */+ "int api_counter = 0;\n" /* 32 */+ "enum mode { MODE_A };\n"; /* 33 */++static bool c_token_is(const CBMFileResult *r, const char *raw, uint32_t line, int syntax,+ bool file) {+ if (dm_count_tokens(r, raw) != 1) {+ printf(" token %s: %d found\n", raw, dm_count_tokens(r, raw));+ return false;+ }+ const CBMDocLink *t = dm_find_token(r, raw);+ bool is_file = (t->flags & CBM_DOCLINK_FLAG_FILE) != 0;+ if (t->line != line || t->syntax != syntax || is_file != file) {+ printf(" token %s: line %u syntax %d file %d\n", raw, t->line, t->syntax, is_file);+ return false;+ }+ return true;+}++TEST(doc_mentions_c_tokens) {+ CBMFileResult *r = dm_extract(C_WIDGET, CBM_LANG_C, "src/widget.c");+ ASSERT_NOT_NULL(r);+ ASSERT_TRUE(c_token_is(r, "widget_free", 4, CBM_DOCLINK_C_REF, false));+ ASSERT_TRUE(c_token_is(r, "api_counter", 4, CBM_DOCLINK_C_REF, false));+ /* the names an @see paragraph lists, to its empty line */+ ASSERT_TRUE(c_token_is(r, "widget_free()", 12, CBM_DOCLINK_C_SEE, false));+ ASSERT_TRUE(c_token_is(r, "helper", 12, CBM_DOCLINK_C_SEE, false));+ ASSERT_TRUE(c_token_is(r, "::api_counter", 12, CBM_DOCLINK_C_SEE, false));+ ASSERT_TRUE(c_token_is(r, "https://example.com/w", 12, CBM_DOCLINK_HREF, false));+ ASSERT_TRUE(c_token_is(r, "also_this", 13, CBM_DOCLINK_C_SEE, false));+ ASSERT_TRUE(c_token_is(r, "Other_thing", 16, CBM_DOCLINK_C_SEE, false));+ /* a /// run */+ ASSERT_TRUE(c_token_is(r, "API_MAX", 21, CBM_DOCLINK_C_REF, false));+ ASSERT_TRUE(c_token_is(r, "widget_new()", 22, CBM_DOCLINK_C_SEE, false));+ /* a prototype has no node: its doc belongs to the file */+ ASSERT_TRUE(c_token_is(r, "grp", 27, CBM_DOCLINK_C_REF, true));+ ASSERT_TRUE(c_token_is(r, "widget_new", 27, CBM_DOCLINK_C_REF, true));+ /* code spans, quotes, code blocks, fences, a new paragraph, \c */+ ASSERT_EQ(dm_count_tokens(r, "Hidden"), 0);+ ASSERT_EQ(dm_count_tokens(r, "Quoted"), 0);+ ASSERT_EQ(dm_count_tokens(r, "InCode"), 0);+ ASSERT_EQ(dm_count_tokens(r, "Fenced"), 0);+ ASSERT_EQ(dm_count_tokens(r, "after_blank"), 0);+ ASSERT_EQ(dm_count_tokens(r, "not_this"), 0);+ ASSERT_EQ(dm_count_tokens(r, "not_a_see"), 0);+ ASSERT_EQ(r->doc_links.count, 12);+ cbm_free_result(r);+ PASS();+}++/* A C++ file is not part of the leg; a header is. */+TEST(doc_mentions_c_files) {+ const char *src = "/** See @ref other_fn. */\nint fn(void) { return 0; }\n";+ CBMFileResult *r = dm_extract(src, CBM_LANG_CPP, "src/x.cpp");+ ASSERT_NOT_NULL(r);+ ASSERT_EQ(r->doc_links.count, 0);+ ASSERT_NULL(r->doc_scope);+ cbm_free_result(r);+ r = dm_extract(src, CBM_LANG_CPP, "include/x.h");+ ASSERT_NOT_NULL(r);+ ASSERT_EQ(dm_count_tokens(r, "other_fn"), 1);+ cbm_free_result(r);+ PASS();+}++static bool c_has_prefix_line(const char *blob, const char *prefix) {+ size_t n = strlen(prefix);+ for (const char *p = blob; p && *p;) {+ const char *nl = strchr(p, '\n');+ size_t len = nl ? (size_t)(nl - p) : strlen(p);+ if (len >= n && memcmp(p, prefix, n) == 0) {+ return true;+ }+ p = nl ? nl + 1 : NULL;+ }+ printf(" no line: %s...\n", prefix);+ return false;+}++TEST(doc_mentions_c_scope_blob) {+ CBMFileResult *r = dm_extract(C_WIDGET, CBM_LANG_C, "src/widget.c");+ ASSERT_NOT_NULL(r);+ const char *s = r->doc_scope;+ ASSERT_NOT_NULL(s);+ ASSERT(strncmp(s, "c1\n", 3) == 0);+ ASSERT(c_has_prefix_line(s, "D\tf\tx\twidget_new\t"));+ ASSERT(c_has_prefix_line(s, "D\tf\ts\thelper\t"));+ ASSERT(c_has_prefix_line(s, "D\tv\ts\tcounter\t"));+ ASSERT(c_has_prefix_line(s, "D\tv\tx\tapi_counter\t"));+ /* types, constants and macros of a .c file are its own */+ ASSERT(c_has_prefix_line(s, "D\tm\ts\tAPI_MAX\t"));+ ASSERT(c_has_prefix_line(s, "D\tM\ts\tTWICE\t"));+ ASSERT(c_has_prefix_line(s, "D\tt\ts\tmode\t"));+ ASSERT(c_has_prefix_line(s, "D\te\ts\tMODE_A\t"));+ ASSERT(c_has_prefix_line(s, "A\tgrp"));+ cbm_free_result(r);+ PASS();+}++/* ── resolution ──────────────────────────────────────────────────── */++static void c_write_repo(const char *repo) {+ th_write_file(TH_PATH(repo, "include/api.h"), "#ifndef API_H\n"+ "#define API_H\n"+ "/** @defgroup widgets Widgets */\n"+ "/** Makes one, see @ref widget_free. */\n"+ "int widget_new(int n);\n"+ "void widget_free(int w);\n"+ "#define API_MAX 16\n"+ "#define api_twice(x) ((x) * 2)\n"+ "int dual(int x);\n"+ "#define dual(x) ((x) + 1)\n"+ "#define level(x) (x)\n"+ "enum color { RED, GREEN };\n"+ "struct st { int fld; };\n"+ "typedef struct widget { int n; } widget_t;\n"+ "extern int api_counter;\n"+ "#endif\n");+ th_write_file(TH_PATH(repo, "src/widget.c"),+ "#include \"api.h\"\n"+ "int api_counter;\n"+ "int level;\n"+ "static int helper(int x) { return x; }\n"+ "int widget_new(int n) { return n; }\n"+ "void widget_free(int w) { (void)w; }\n"+ "int (dual)(int x) { return x; }\n"+ "/**\n"+ " * The core. @ref helper, @ref api_counter, @ref API_MAX, @ref dual,\n"+ " * @ref RED, @ref widgets, @ref other_static, @ref twin, @ref nope,\n"+ " * @ref widget_t, @ref test_only_fn, @ref st::fld, @ref color::GREEN,\n"+ " * @ref lfield, @ref st::nofield.\n"+ " * @see api_twice() for details, unknown_fn()\n"+ " */\n"+ "int core(void) { return helper(0); }\n"+ "struct local { int lfield; };\n");+ th_write_file(TH_PATH(repo, "src/other.c"), "#include \"api.h\"\n"+ "static int other_static(void) { return 0; }\n"+ "int twin(void) { return 1; }\n"+ "/** Other: @ref dual, @ref level and\n"+ " * @ref level(). */\n"+ "int other(void) { return other_static(); }\n");+ th_write_file(TH_PATH(repo, "src/third.c"), "int twin(void) { return 2; }\n");+ th_write_file(TH_PATH(repo, "tests/test_widget.c"), "int test_only_fn(void) { return 0; }\n");+}++static bool c_edge(const char *db, const char *src, const char *tgt) {+ char props[512];+ int n = 0;+ dm_edge(db, src, tgt, props, sizeof(props), &n);+ if (n != 1) {+ printf(" edge %s -> %s: %d found\n", src, tgt, n);+ return false;+ }+ return true;+}++static bool c_row(const char *db, const char *raw, const char *reason) {+ char got[64];+ dm_row(db, "src/widget.c", raw, got, sizeof(got), NULL, 0);+ if (strcmp(got, reason) != 0) {+ printf(" row [%s]: \"%s\", expected \"%s\"\n", raw, got, reason);+ return false;+ }+ return true;+}++TEST(doc_mentions_c_resolution) {+ char tmp[256];+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlc_XXXXXX");+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));+ char repo[512];+ char db[512];+ snprintf(repo, sizeof(repo), "%s/repo", tmp);+ snprintf(db, sizeof(db), "%s/g.db", tmp);+ c_write_repo(repo);+ ASSERT_EQ(dm_index(repo, db, NULL), 0);+ const char *core = "src.widget.core";+ /* the documented file's own definitions, a static one too */+ ASSERT_TRUE(c_edge(db, core, "src.widget.helper"));+ ASSERT_TRUE(c_edge(db, core, "src.widget.api_counter"));+ ASSERT_TRUE(c_edge(db, core, "src.widget.dual"));+ /* what every file sees: a header's macros, constants and types */+ ASSERT_TRUE(c_edge(db, core, "include.api.API_MAX#macro"));+ ASSERT_TRUE(c_edge(db, core, "include.api.RED"));+ ASSERT_TRUE(c_edge(db, core, "include.api.widget_t"));+ ASSERT_TRUE(c_edge(db, core, "include.api.api_twice#macro"));+ /* a group is no code entity; another file's static is not visible */+ ASSERT_TRUE(c_row(db, "widgets", "graph_gap"));+ ASSERT_TRUE(c_row(db, "other_static", "missing"));+ ASSERT_TRUE(c_row(db, "nope", "missing"));+ ASSERT_TRUE(c_row(db, "twin", "ambiguous"));+ ASSERT_TRUE(c_row(db, "test_only_fn", "test_only_target"));+ /* Type::member: a struct field, an enum constant; a field of the file */+ ASSERT_TRUE(c_edge(db, core, "include.api.st.fld"));+ ASSERT_TRUE(c_edge(db, core, "include.api.GREEN"));+ ASSERT_TRUE(c_edge(db, core, "src.widget.local.lfield"));+ ASSERT_TRUE(c_row(db, "st::nofield", "missing"));+ /* prose in an @see paragraph is text; a code-shaped name is missing */+ ASSERT_TRUE(c_row(db, "for", ""));+ ASSERT_TRUE(c_row(db, "details", ""));+ ASSERT_TRUE(c_row(db, "unknown_fn()", "missing"));+ /* a definition before a macro; with (), a function-like macro first */+ ASSERT_TRUE(c_edge(db, "src.other.other", "src.widget.dual"));+ ASSERT_TRUE(c_edge(db, "src.other.other", "src.widget.level"));+ ASSERT_TRUE(c_edge(db, "src.other.other", "include.api.level#macro"));+ /* a header prototype's doc: the header file is its source */+ ASSERT_TRUE(c_edge(db, "include.api.h.__file__", "src.widget.widget_free"));+ th_cleanup(tmp);+ PASS();+}++/* ── incremental == full; one worker == several ──────────────────── */++TEST(doc_mentions_c_incremental_equals_full) {+ char tmp[256];+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlc_inc_XXXXXX");+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));+ char repo[512];+ char inc_db[512];+ char full_db[512];+ snprintf(repo, sizeof(repo), "%s/repo", tmp);+ snprintf(inc_db, sizeof(inc_db), "%s/inc.db", tmp);+ snprintf(full_db, sizeof(full_db), "%s/full.db", tmp);+ th_write_file(TH_PATH(repo, "src/lib.c"),+ "int a(void) { return 0; }\nint b(void) { return 1; }\n");+ th_write_file(TH_PATH(repo, "src/use.c"),+ "/** Uses @ref a. */\nint user(void) { return 0; }\n");+ ASSERT_EQ(dm_index(repo, inc_db, NULL), 0);+ ASSERT_TRUE(c_edge(inc_db, "src.use.user", "src.lib.a"));++ /* a doc edit: the file is repaired alone */+ th_write_file(TH_PATH(repo, "src/use.c"),+ "/** Uses @ref a and @ref nope. */\nint user(void) { return 0; }\n");+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "doc edit", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);++ /* a body edit in the target file: its scope is unchanged */+ th_write_file(TH_PATH(repo, "src/lib.c"),+ "int a(void) { return 2; }\nint b(void) { return 1; }\n");+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "body edit", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);+ ASSERT_TRUE(c_edge(inc_db, "src.use.user", "src.lib.a"));++ /* a becomes static: without a scope_delta hook that is a full run */+ th_write_file(TH_PATH(repo, "src/lib.c"),+ "static int a(void) { return 0; }\nint b(void) { return 1; }\n");+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "made static", CBM_INCREMENTAL_ROUTE_FORCED_FULL), 0);+ char props[512];+ int n = 0;+ dm_edge(inc_db, "src.use.user", "src.lib.a", props, sizeof(props), &n);+ ASSERT_EQ(n, 0);+ th_cleanup(tmp);+ PASS();+}++TEST(doc_mentions_c_workers_agree) {+ char tmp[256];+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlc_par_XXXXXX");+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));+ char repo[512];+ char par_db[512];+ char seq_db[512];+ snprintf(repo, sizeof(repo), "%s/repo", tmp);+ snprintf(par_db, sizeof(par_db), "%s/par.db", tmp);+ snprintf(seq_db, sizeof(seq_db), "%s/seq.db", tmp);+ enum { MODULES = 60 }; /* past the parallel threshold */+ for (int i = 0; i < MODULES; i++) {+ char rel[64];+ char src[1024];+ int next = (i + 1) % MODULES;+ snprintf(rel, sizeof(rel), "src/m%02d.c", i);+ snprintf(src, sizeof(src),+ "/** F%02d; see @ref f%02d, @ref K%02d, @ref nope.\n"+ " * @see g%02d() */\n"+ "int f%02d(void) { return 0; }\n"+ "int g%02d(void) { return 1; }\n"+ "#define K%02d 1\n",+ i, next, next, next, i, i, i);+ th_write_file(TH_PATH(repo, rel), src);+ }+ ASSERT_EQ(dm_workers_agree(repo, par_db, seq_db), 0);+ ASSERT_TRUE(c_edge(par_db, "src.m00.f00", "src.m01.f01"));+ th_cleanup(tmp);+ PASS();+}++SUITE(doc_mentions_c) {+ dm_ship_held_families();+ RUN_TEST(doc_mentions_c_tokens);+ RUN_TEST(doc_mentions_c_files);+ RUN_TEST(doc_mentions_c_scope_blob);+ RUN_TEST(doc_mentions_c_resolution);+ RUN_TEST(doc_mentions_c_incremental_equals_full);+ RUN_TEST(doc_mentions_c_workers_agree);+}diff --git a/tests/test_doc_mentions_helpers.h b/tests/test_doc_mentions_helpers.hindex eb32af893..95e5f0503 100644--- a/tests/test_doc_mentions_helpers.h+++ b/tests/test_doc_mentions_helpers.h@@ -442,6 +442,7 @@ static const int DM_HELD_FAMILIES[] = {CBM_DOCLINK_RS_LINK_DEF, CBM_DOCLINK_PERL_POD_L,CBM_DOCLINK_TS_LINK, CBM_DOCLINK_TS_LINKCODE,CBM_DOCLINK_TS_SEE, CBM_DOCLINK_PHP_SEE,+ CBM_DOCLINK_C_REF, CBM_DOCLINK_C_SEE,};static inline void dm_ship_held_families(void) {diff --git a/tests/test_main.c b/tests/test_main.cindex cff0ee468..de3d80508 100644--- a/tests/test_main.c+++ b/tests/test_main.c@@ -1831,6 +1831,7 @@ extern void suite_doc_mentions_rs(void);extern void suite_doc_mentions_perl(void);extern void suite_doc_mentions_ts(void);extern void suite_doc_mentions_php(void);+extern void suite_doc_mentions_c(void);extern void suite_infrascan(void);extern void suite_cli(void);extern void suite_agent_clients(void);@@ -2308,6 +2309,7 @@ int main(int argc, char **argv) {RUN_SELECTED_SUITE(doc_mentions_perl);RUN_SELECTED_SUITE(doc_mentions_ts);RUN_SELECTED_SUITE(doc_mentions_php);+ RUN_SELECTED_SUITE(doc_mentions_c);/* Infrastructure scanning */RUN_SELECTED_SUITE(infrascan);