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(go): Go doc links become MENTIONS edges, held until their audit

Martin Vogel0c7ca3441904
diff --git a/Makefile.cbm b/Makefile.cbm
index cd5eb4124..bee0f531d 100644
--- a/Makefile.cbm
+++ b/Makefile.cbm
@@ -386,6 +386,7 @@ EXTRACTION_SRCS = \
$(CBM_DIR)/pdf/pdf_text.c \
$(CBM_DIR)/pdf/pdf_tables.c \
$(CBM_DIR)/pdf/pdf_unicode.c \
+ $(CBM_DIR)/doclink_go.c \
$(CBM_DIR)/sql_values.c \
$(CBM_DIR)/helpers.c \
$(CBM_DIR)/cpp_branch_views.c \
@@ -512,6 +513,7 @@ PIPELINE_SRCS = \
src/pipeline/doc_links_pdf.c \
src/pipeline/doc_links_rst.c \
src/pipeline/doc_links_adoc.c \
+ src/pipeline/doc_links_go.c \
src/pipeline/doc_links_msbuild.c \
src/pipeline/pass_route_nodes.c \
src/pipeline/pass_enrichment.c \
@@ -774,7 +776,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_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_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_WATCHER_SRCS = tests/test_watcher.c
diff --git a/internal/cbm/doclink.c b/internal/cbm/doclink.c
index 09ee36c25..0d8c1e753 100644
--- a/internal/cbm/doclink.c
+++ b/internal/cbm/doclink.c
@@ -180,6 +180,16 @@ static const doclink_lang_t DOCLINK_LANGS[] = {
{.lang = CBM_LANG_YAML,
.scan_scope = cbm_doclink_antora_scan_scope,
.scope_tag = CBM_DOCLINK_ADOC_SCOPE_TAG},
+ {.lang = CBM_LANG_GO,
+ .parse_doc = cbm_doclink_go_parse_doc,
+ .scan_scope = cbm_doclink_go_scan_scope,
+ .scope_tag = CBM_DOCLINK_GO_SCOPE_TAG,
+ .portable_scope = cbm_doclink_go_portable_scope},
+ {.lang = CBM_LANG_GOMOD,
+ .parse_doc = cbm_doclink_gomod_parse_doc,
+ .scan_scope = cbm_doclink_gomod_scan_scope,
+ .scope_tag = CBM_DOCLINK_GO_SCOPE_TAG,
+ .portable_scope = cbm_doclink_go_portable_scope},
};
static const doclink_lang_t *doclink_lang(CBMLanguage lang) {
diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.h
index b33812dec..ab97ac0f4 100644
--- a/internal/cbm/doclink.h
+++ b/internal/cbm/doclink.h
@@ -83,6 +83,8 @@
X(CBM_DOCLINK_CS_SEEALSO, CBM_LANG_CSHARP, "seealso", false, true, "MENTIONS") \
X(CBM_DOCLINK_CS_EXCEPTION, CBM_LANG_CSHARP, "exception", false, true, "MENTIONS") \
X(CBM_DOCLINK_CS_INHERITDOC, CBM_LANG_CSHARP, "inheritdoc", false, true, "MENTIONS") \
+ /* go (doclink_go.c): [Name] doc links; held until its held-out audit passes */ \
+ X(CBM_DOCLINK_GO_DOC_LINK, CBM_LANG_GO, "doc_link", 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") \
@@ -385,5 +387,45 @@ void cbm_pdf_test_scan_page(CBMExtractCtx *ctx, const char *text, size_t len, ui
/* candidates the scanner's joins have compared so far (a cost counter) */
size_t cbm_pdf_test_join_steps(void);
#endif
+/* ── Go (doclink_go.c) ─────────────────────────────────────────────── */
+
+void cbm_doclink_go_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,
+ uint32_t doc_line);
+const char *cbm_doclink_go_scan_scope(CBMExtractCtx *ctx);
+char *cbm_doclink_go_portable_scope(const char *scope);
+
+/* A go.mod file has no doc links; its scope is the module path, in the Go
+ * scope format, so that import paths map to the repository's directories. */
+void cbm_doclink_gomod_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,
+ uint32_t doc_line);
+const char *cbm_doclink_gomod_scan_scope(CBMExtractCtx *ctx);
+
+/* The parts of a Go doc link as go/doc/comment splits it (docLink,
+ * splitDocName): `pkg`, `recv` and `name` are slices of the reference text,
+ * each possibly empty. [Name] {name}; [Recv.Name] {recv, name}; [pkg] {pkg};
+ * [pkg.Name] {pkg, name}; [pkg.Recv.Name] {pkg, recv, name}. */
+typedef struct {
+ const char *pkg; /* a package name, or an import path when it has a '/' */
+ size_t pkg_len;
+ const char *recv;
+ size_t recv_len;
+ const char *name;
+ size_t name_len;
+} CBMDocLinkGoRef;
+
+/* The longest reference text, and the longest name, the Go leg handles. A
+ * longer bracket text made of doc-link characters is harvested clipped to at
+ * most one byte more than this, and the resolver reports it as unparseable:
+ * a reference is never resolved by its beginning. */
+enum { CBM_DOCLINK_GO_REF_MAX = 512 };
+
+/* Split the text between the brackets (a leading `*` is skipped). False for
+ * text that go/doc/comment could not take for a doc link whatever the package
+ * declares or imports (nothing is harvested from it), and for text longer than
+ * CBM_DOCLINK_GO_REF_MAX. */
+bool cbm_doclink_go_parse_ref(const char *raw, size_t len, CBMDocLinkGoRef *out);
+
+/* The Go scope blob (Go files and go.mod files) starts with this tag line. */
+#define CBM_DOCLINK_GO_SCOPE_TAG "go1"
#endif /* CBM_DOCLINK_H */
diff --git a/internal/cbm/doclink_go.c b/internal/cbm/doclink_go.c
new file mode 100644
index 000000000..97dab618d
--- /dev/null
+++ b/internal/cbm/doclink_go.c
@@ -0,0 +1,2045 @@
+/*
+ * doclink_go.c — Go doc links and the Go doc-link scope.
+ *
+ * Tokens. A Go doc comment has no link markup of its own kind: a doc link is
+ * bracketed text that go/doc/comment decides to treat as one. This file ports
+ * the half of that decision that needs only the comment (go/ast
+ * CommentGroup.Text, then go/doc/comment unindent, parseSpans, link
+ * definitions, parseLinkedText's bracket scan with its border rule, and the
+ * name shape of docLink/splitDocName). What it emits are CANDIDATES:
+ * [Name] [Recv.Name] [pkg] [pkg.Name] [pkg.Recv.Name]
+ * each optionally with a leading `*`, where pkg is an identifier or an import
+ * path. The other half of the decision (does the package declare the name,
+ * does the file import the package) needs the whole package and is the
+ * resolver's (src/pipeline/doc_links_go.c): a candidate that fails it is plain
+ * text, exactly as go/doc renders it, and leaves neither an edge nor a row.
+ * A `[Text]` with a link definition `[Text]: scheme://...` in the same comment
+ * is a URL: one `href` token per use.
+ *
+ * Never a link: code blocks (indented lines), `# ` headings (go/doc keeps
+ * heading text plain), the link-definition paragraphs themselves, and a
+ * bracket pair that touches a letter or digit (`map[K]V`, `a[i]`).
+ *
+ * Scope blob (first line "go1", then one record per line, tab-separated,
+ * sorted; only exported names are recorded, a doc link can name nothing else):
+ * P name flags package clause; flags: i build-ignored file
+ * (`//go:build ignore`), c another build-constraint
+ * line, e parse errors in the file, - none
+ * I local path import; local `-` when not renamed (dot and blank
+ * imports are no qualifiers and are left out); path
+ * `?` when it is none this scan can record
+ * F name w function
+ * M recv name w method (recv `?` when the receiver type is not a
+ * plain name)
+ * T name kind alias w type; kind s struct, i interface, a alias, o other;
+ * alias: the target of `type X = Y` / `= pkg.Y`
+ * V name w variable or constant
+ * f type name node struct field (node 0: embedded, or not the first
+ * name of its declaration)
+ * m type name interface method
+ * g first last names type parameters (','-joined) of the declaration
+ * that spans the lines first..last. Only in the
+ * blob of a fresh extraction; the persisted blob
+ * drops these lines and so carries no line number
+ * at all.
+ * G path go.mod: the module path
+ * w says who keeps the node. A Go method node has a FLAT qualified name
+ * (<dir>.<Method>), so a function, the methods of every receiver, a type and
+ * a value of one name all claim the node <dir>.<name>, and within a file the
+ * declaration on the LAST line keeps it (cbm_gbuf_upsert_node). w is 1 for
+ * that declaration, 0 for the others of that name, x when two of them start
+ * on that last line, and - for a value the extractor gives no node at all
+ * (it gives one to the first name of a constant spec and of a parenthesis-
+ * free `var`).
+ * The records are sorted and w is the only order-dependent field: the blob
+ * does not change when declarations merely move, and it does change when a
+ * move hands a node to another declaration.
+ */
+#include "doclink.h"
+
+#include "cbm.h"
+#include "foundation/arena.h"
+#include "foundation/constants.h"
+#include "foundation/mem_core.h"
+#include "tree_sitter/api.h"
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+enum {
+ GO_REF_MAX = CBM_DOCLINK_GO_REF_MAX, /* longest bracket text and name handled */
+ GO_URL_MAX = 2048, /* a link-definition URL is stored up to here */
+ GO_PATH_MAX = 1024, /* longest import or module path recorded */
+ GO_ARRAY_INIT = 16,
+ GO_MARKER_LEN = 2, /* "//", the opening and the closing of a block comment */
+ GO_LINKDEF_TAIL = 3, /* "]: " */
+ GO_ASCII_END = 0x80, /* first non-ASCII byte */
+ GO_ASCII_DEL = 0x7F,
+ GO_RECV_UNWRAP = 4, /* pointer_type / generic_type levels of a receiver, as the extractor */
+ GO_EMBED_UNWRAP = 8, /* the same for an embedded field: *pkg.T[A] and some slack */
+ GO_SB_INIT = 64,
+ GO_NODE_FLAG = 1, /* "node" field of a V or f record */
+};
+
+/* ── Small helpers ───────────────────────────────────────────────── */
+
+static CBMArena *go_scratch(CBMExtractCtx *ctx) {
+ return ctx->scratch ? ctx->scratch : ctx->arena;
+}
+
+/* Room for one more element of an arena array (the old block is abandoned to
+ * the arena); NULL when memory ran out. */
+static void *go_grow(CBMArena *a, void *items, int count, int *cap, size_t elem) {
+ if (count < *cap) {
+ return items;
+ }
+ int ncap = *cap ? *cap * PAIR_LEN : GO_ARRAY_INIT;
+ void *grown = cbm_arena_alloc(a, (size_t)ncap * elem);
+ if (!grown) {
+ return NULL;
+ }
+ if (count > 0) {
+ memcpy(grown, items, (size_t)count * elem);
+ }
+ *cap = ncap;
+ return grown;
+}
+
+static bool go_space(char c) {
+ return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '\v' || c == '\f';
+}
+
+static bool go_blank_or_tab(char c) {
+ return c == ' ' || c == '\t';
+}
+
+static bool go_has_prefix(const char *s, size_t n, const char *prefix) {
+ size_t pl = strlen(prefix);
+ return n >= pl && memcmp(s, prefix, pl) == 0;
+}
+
+static bool go_ascii_alpha(unsigned char c) {
+ return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+}
+
+static bool go_ascii_digit(unsigned char c) {
+ return c >= '0' && c <= '9';
+}
+
+static void go_trim(const char **s, size_t *n) {
+ while (*n > 0 && go_space((*s)[0])) {
+ (*s)++;
+ (*n)--;
+ }
+ while (*n > 0 && go_space((*s)[*n - SKIP_ONE])) {
+ (*n)--;
+ }
+}
+
+/* ── UTF-8 and the two Unicode classes go/doc/comment asks for ───── */
+
+typedef struct {
+ uint32_t lo;
+ uint32_t hi;
+ uint32_t stride;
+} go_range_t;
+
+/* General category P* above U+007F (Unicode 16.0.0), ascending. */
+static const go_range_t GO_PUNCT[] = {
+ {0x00A1, 0x00A1, 1}, {0x00A7, 0x00A7, 1}, {0x00AB, 0x00AB, 1}, {0x00B6, 0x00B7, 1},
+ {0x00BB, 0x00BB, 1}, {0x00BF, 0x00BF, 1}, {0x037E, 0x037E, 1}, {0x0387, 0x0387, 1},
+ {0x055A, 0x055F, 1}, {0x0589, 0x058A, 1}, {0x05BE, 0x05BE, 1}, {0x05C0, 0x05C0, 1},
+ {0x05C3, 0x05C3, 1}, {0x05C6, 0x05C6, 1}, {0x05F3, 0x05F4, 1}, {0x0609, 0x060A, 1},
+ {0x060C, 0x060D, 1}, {0x061B, 0x061B, 1}, {0x061D, 0x061F, 1}, {0x066A, 0x066D, 1},
+ {0x06D4, 0x06D4, 1}, {0x0700, 0x070D, 1}, {0x07F7, 0x07F9, 1}, {0x0830, 0x083E, 1},
+ {0x085E, 0x085E, 1}, {0x0964, 0x0965, 1}, {0x0970, 0x0970, 1}, {0x09FD, 0x09FD, 1},
+ {0x0A76, 0x0A76, 1}, {0x0AF0, 0x0AF0, 1}, {0x0C77, 0x0C77, 1}, {0x0C84, 0x0C84, 1},
+ {0x0DF4, 0x0DF4, 1}, {0x0E4F, 0x0E4F, 1}, {0x0E5A, 0x0E5B, 1}, {0x0F04, 0x0F12, 1},
+ {0x0F14, 0x0F14, 1}, {0x0F3A, 0x0F3D, 1}, {0x0F85, 0x0F85, 1}, {0x0FD0, 0x0FD4, 1},
+ {0x0FD9, 0x0FDA, 1}, {0x104A, 0x104F, 1}, {0x10FB, 0x10FB, 1}, {0x1360, 0x1368, 1},
+ {0x1400, 0x1400, 1}, {0x166E, 0x166E, 1}, {0x169B, 0x169C, 1}, {0x16EB, 0x16ED, 1},
+ {0x1735, 0x1736, 1}, {0x17D4, 0x17D6, 1}, {0x17D8, 0x17DA, 1}, {0x1800, 0x180A, 1},
+ {0x1944, 0x1945, 1}, {0x1A1E, 0x1A1F, 1}, {0x1AA0, 0x1AA6, 1}, {0x1AA8, 0x1AAD, 1},
+ {0x1B4E, 0x1B4F, 1}, {0x1B5A, 0x1B60, 1}, {0x1B7D, 0x1B7F, 1}, {0x1BFC, 0x1BFF, 1},
+ {0x1C3B, 0x1C3F, 1}, {0x1C7E, 0x1C7F, 1}, {0x1CC0, 0x1CC7, 1}, {0x1CD3, 0x1CD3, 1},
+ {0x2010, 0x2027, 1}, {0x2030, 0x2043, 1}, {0x2045, 0x2051, 1}, {0x2053, 0x205E, 1},
+ {0x207D, 0x207E, 1}, {0x208D, 0x208E, 1}, {0x2308, 0x230B, 1}, {0x2329, 0x232A, 1},
+ {0x2768, 0x2775, 1}, {0x27C5, 0x27C6, 1}, {0x27E6, 0x27EF, 1}, {0x2983, 0x2998, 1},
+ {0x29D8, 0x29DB, 1}, {0x29FC, 0x29FD, 1}, {0x2CF9, 0x2CFC, 1}, {0x2CFE, 0x2CFF, 1},
+ {0x2D70, 0x2D70, 1}, {0x2E00, 0x2E2E, 1}, {0x2E30, 0x2E4F, 1}, {0x2E52, 0x2E5D, 1},
+ {0x3001, 0x3003, 1}, {0x3008, 0x3011, 1}, {0x3014, 0x301F, 1}, {0x3030, 0x3030, 1},
+ {0x303D, 0x303D, 1}, {0x30A0, 0x30A0, 1}, {0x30FB, 0x30FB, 1}, {0xA4FE, 0xA4FF, 1},
+ {0xA60D, 0xA60F, 1}, {0xA673, 0xA673, 1}, {0xA67E, 0xA67E, 1}, {0xA6F2, 0xA6F7, 1},
+ {0xA874, 0xA877, 1}, {0xA8CE, 0xA8CF, 1}, {0xA8F8, 0xA8FA, 1}, {0xA8FC, 0xA8FC, 1},
+ {0xA92E, 0xA92F, 1}, {0xA95F, 0xA95F, 1}, {0xA9C1, 0xA9CD, 1}, {0xA9DE, 0xA9DF, 1},
+ {0xAA5C, 0xAA5F, 1}, {0xAADE, 0xAADF, 1}, {0xAAF0, 0xAAF1, 1}, {0xABEB, 0xABEB, 1},
+ {0xFD3E, 0xFD3F, 1}, {0xFE10, 0xFE19, 1}, {0xFE30, 0xFE52, 1}, {0xFE54, 0xFE61, 1},
+ {0xFE63, 0xFE63, 1}, {0xFE68, 0xFE68, 1}, {0xFE6A, 0xFE6B, 1}, {0xFF01, 0xFF03, 1},
+ {0xFF05, 0xFF0A, 1}, {0xFF0C, 0xFF0F, 1}, {0xFF1A, 0xFF1B, 1}, {0xFF1F, 0xFF20, 1},
+ {0xFF3B, 0xFF3D, 1}, {0xFF3F, 0xFF3F, 1}, {0xFF5B, 0xFF5B, 1}, {0xFF5D, 0xFF5D, 1},
+ {0xFF5F, 0xFF65, 1}, {0x10100, 0x10102, 1}, {0x1039F, 0x1039F, 1}, {0x103D0, 0x103D0, 1},
+ {0x1056F, 0x1056F, 1}, {0x10857, 0x10857, 1}, {0x1091F, 0x1091F, 1}, {0x1093F, 0x1093F, 1},
+ {0x10A50, 0x10A58, 1}, {0x10A7F, 0x10A7F, 1}, {0x10AF0, 0x10AF6, 1}, {0x10B39, 0x10B3F, 1},
+ {0x10B99, 0x10B9C, 1}, {0x10D6E, 0x10D6E, 1}, {0x10EAD, 0x10EAD, 1}, {0x10F55, 0x10F59, 1},
+ {0x10F86, 0x10F89, 1}, {0x11047, 0x1104D, 1}, {0x110BB, 0x110BC, 1}, {0x110BE, 0x110C1, 1},
+ {0x11140, 0x11143, 1}, {0x11174, 0x11175, 1}, {0x111C5, 0x111C8, 1}, {0x111CD, 0x111CD, 1},
+ {0x111DB, 0x111DB, 1}, {0x111DD, 0x111DF, 1}, {0x11238, 0x1123D, 1}, {0x112A9, 0x112A9, 1},
+ {0x113D4, 0x113D5, 1}, {0x113D7, 0x113D8, 1}, {0x1144B, 0x1144F, 1}, {0x1145A, 0x1145B, 1},
+ {0x1145D, 0x1145D, 1}, {0x114C6, 0x114C6, 1}, {0x115C1, 0x115D7, 1}, {0x11641, 0x11643, 1},
+ {0x11660, 0x1166C, 1}, {0x116B9, 0x116B9, 1}, {0x1173C, 0x1173E, 1}, {0x1183B, 0x1183B, 1},
+ {0x11944, 0x11946, 1}, {0x119E2, 0x119E2, 1}, {0x11A3F, 0x11A46, 1}, {0x11A9A, 0x11A9C, 1},
+ {0x11A9E, 0x11AA2, 1}, {0x11B00, 0x11B09, 1}, {0x11BE1, 0x11BE1, 1}, {0x11C41, 0x11C45, 1},
+ {0x11C70, 0x11C71, 1}, {0x11EF7, 0x11EF8, 1}, {0x11F43, 0x11F4F, 1}, {0x11FFF, 0x11FFF, 1},
+ {0x12470, 0x12474, 1}, {0x12FF1, 0x12FF2, 1}, {0x16A6E, 0x16A6F, 1}, {0x16AF5, 0x16AF5, 1},
+ {0x16B37, 0x16B3B, 1}, {0x16B44, 0x16B44, 1}, {0x16D6D, 0x16D6F, 1}, {0x16E97, 0x16E9A, 1},
+ {0x16FE2, 0x16FE2, 1}, {0x1BC9F, 0x1BC9F, 1}, {0x1DA87, 0x1DA8B, 1}, {0x1E5FF, 0x1E5FF, 1},
+ {0x1E95E, 0x1E95F, 1},
+};
+
+/* General category Lu above U+007F (Unicode 16.0.0), ascending; a stride of 2
+ * covers the runs where upper and lower case alternate. */
+static const go_range_t GO_UPPER[] = {
+ {0x00C0, 0x00D6, 1}, {0x00D8, 0x00DE, 1}, {0x0100, 0x0136, 2}, {0x0139, 0x0147, 2},
+ {0x014A, 0x0176, 2}, {0x0178, 0x0179, 1}, {0x017B, 0x017D, 2}, {0x0181, 0x0182, 1},
+ {0x0184, 0x0184, 1}, {0x0186, 0x0187, 1}, {0x0189, 0x018B, 1}, {0x018E, 0x0191, 1},
+ {0x0193, 0x0194, 1}, {0x0196, 0x0198, 1}, {0x019C, 0x019D, 1}, {0x019F, 0x01A0, 1},
+ {0x01A2, 0x01A4, 2}, {0x01A6, 0x01A7, 1}, {0x01A9, 0x01A9, 1}, {0x01AC, 0x01AC, 1},
+ {0x01AE, 0x01AF, 1}, {0x01B1, 0x01B3, 1}, {0x01B5, 0x01B5, 1}, {0x01B7, 0x01B8, 1},
+ {0x01BC, 0x01BC, 1}, {0x01C4, 0x01C4, 1}, {0x01C7, 0x01C7, 1}, {0x01CA, 0x01CA, 1},
+ {0x01CD, 0x01DB, 2}, {0x01DE, 0x01EE, 2}, {0x01F1, 0x01F1, 1}, {0x01F4, 0x01F4, 1},
+ {0x01F6, 0x01F8, 1}, {0x01FA, 0x0232, 2}, {0x023A, 0x023B, 1}, {0x023D, 0x023E, 1},
+ {0x0241, 0x0241, 1}, {0x0243, 0x0246, 1}, {0x0248, 0x024E, 2}, {0x0370, 0x0372, 2},
+ {0x0376, 0x0376, 1}, {0x037F, 0x037F, 1}, {0x0386, 0x0386, 1}, {0x0388, 0x038A, 1},
+ {0x038C, 0x038C, 1}, {0x038E, 0x038F, 1}, {0x0391, 0x03A1, 1}, {0x03A3, 0x03AB, 1},
+ {0x03CF, 0x03CF, 1}, {0x03D2, 0x03D4, 1}, {0x03D8, 0x03EE, 2}, {0x03F4, 0x03F4, 1},
+ {0x03F7, 0x03F7, 1}, {0x03F9, 0x03FA, 1}, {0x03FD, 0x042F, 1}, {0x0460, 0x0480, 2},
+ {0x048A, 0x04BE, 2}, {0x04C0, 0x04C1, 1}, {0x04C3, 0x04CD, 2}, {0x04D0, 0x052E, 2},
+ {0x0531, 0x0556, 1}, {0x10A0, 0x10C5, 1}, {0x10C7, 0x10C7, 1}, {0x10CD, 0x10CD, 1},
+ {0x13A0, 0x13F5, 1}, {0x1C89, 0x1C89, 1}, {0x1C90, 0x1CBA, 1}, {0x1CBD, 0x1CBF, 1},
+ {0x1E00, 0x1E94, 2}, {0x1E9E, 0x1EFE, 2}, {0x1F08, 0x1F0F, 1}, {0x1F18, 0x1F1D, 1},
+ {0x1F28, 0x1F2F, 1}, {0x1F38, 0x1F3F, 1}, {0x1F48, 0x1F4D, 1}, {0x1F59, 0x1F5F, 2},
+ {0x1F68, 0x1F6F, 1}, {0x1FB8, 0x1FBB, 1}, {0x1FC8, 0x1FCB, 1}, {0x1FD8, 0x1FDB, 1},
+ {0x1FE8, 0x1FEC, 1}, {0x1FF8, 0x1FFB, 1}, {0x2102, 0x2102, 1}, {0x2107, 0x2107, 1},
+ {0x210B, 0x210D, 1}, {0x2110, 0x2112, 1}, {0x2115, 0x2115, 1}, {0x2119, 0x211D, 1},
+ {0x2124, 0x2128, 2}, {0x212A, 0x212D, 1}, {0x2130, 0x2133, 1}, {0x213E, 0x213F, 1},
+ {0x2145, 0x2145, 1}, {0x2183, 0x2183, 1}, {0x2C00, 0x2C2F, 1}, {0x2C60, 0x2C60, 1},
+ {0x2C62, 0x2C64, 1}, {0x2C67, 0x2C6B, 2}, {0x2C6D, 0x2C70, 1}, {0x2C72, 0x2C72, 1},
+ {0x2C75, 0x2C75, 1}, {0x2C7E, 0x2C80, 1}, {0x2C82, 0x2CE2, 2}, {0x2CEB, 0x2CED, 2},
+ {0x2CF2, 0x2CF2, 1}, {0xA640, 0xA66C, 2}, {0xA680, 0xA69A, 2}, {0xA722, 0xA72E, 2},
+ {0xA732, 0xA76E, 2}, {0xA779, 0xA77B, 2}, {0xA77D, 0xA77E, 1}, {0xA780, 0xA786, 2},
+ {0xA78B, 0xA78D, 2}, {0xA790, 0xA792, 2}, {0xA796, 0xA7A8, 2}, {0xA7AA, 0xA7AE, 1},
+ {0xA7B0, 0xA7B4, 1}, {0xA7B6, 0xA7C2, 2}, {0xA7C4, 0xA7C7, 1}, {0xA7C9, 0xA7C9, 1},
+ {0xA7CB, 0xA7CC, 1}, {0xA7D0, 0xA7D0, 1}, {0xA7D6, 0xA7DC, 2}, {0xA7F5, 0xA7F5, 1},
+ {0xFF21, 0xFF3A, 1}, {0x10400, 0x10427, 1}, {0x104B0, 0x104D3, 1}, {0x10570, 0x1057A, 1},
+ {0x1057C, 0x1058A, 1}, {0x1058C, 0x10592, 1}, {0x10594, 0x10595, 1}, {0x10C80, 0x10CB2, 1},
+ {0x10D50, 0x10D65, 1}, {0x118A0, 0x118BF, 1}, {0x16E40, 0x16E5F, 1}, {0x1D400, 0x1D419, 1},
+ {0x1D434, 0x1D44D, 1}, {0x1D468, 0x1D481, 1}, {0x1D49C, 0x1D49C, 1}, {0x1D49E, 0x1D49F, 1},
+ {0x1D4A2, 0x1D4A2, 1}, {0x1D4A5, 0x1D4A6, 1}, {0x1D4A9, 0x1D4AC, 1}, {0x1D4AE, 0x1D4B5, 1},
+ {0x1D4D0, 0x1D4E9, 1}, {0x1D504, 0x1D505, 1}, {0x1D507, 0x1D50A, 1}, {0x1D50D, 0x1D514, 1},
+ {0x1D516, 0x1D51C, 1}, {0x1D538, 0x1D539, 1}, {0x1D53B, 0x1D53E, 1}, {0x1D540, 0x1D544, 1},
+ {0x1D546, 0x1D546, 1}, {0x1D54A, 0x1D550, 1}, {0x1D56C, 0x1D585, 1}, {0x1D5A0, 0x1D5B9, 1},
+ {0x1D5D4, 0x1D5ED, 1}, {0x1D608, 0x1D621, 1}, {0x1D63C, 0x1D655, 1}, {0x1D670, 0x1D689, 1},
+ {0x1D6A8, 0x1D6C0, 1}, {0x1D6E2, 0x1D6FA, 1}, {0x1D71C, 0x1D734, 1}, {0x1D756, 0x1D76E, 1},
+ {0x1D790, 0x1D7A8, 1}, {0x1D7CA, 0x1D7CA, 1}, {0x1E900, 0x1E921, 1},
+};
+
+enum {
+ GO_PUNCT_COUNT = sizeof(GO_PUNCT) / sizeof(GO_PUNCT[0]),
+ GO_UPPER_COUNT = sizeof(GO_UPPER) / sizeof(GO_UPPER[0]),
+ GO_U8_CONT_MASK = 0xC0,
+ GO_U8_CONT = 0x80,
+ GO_U8_PAYLOAD = 0x3F,
+ GO_U8_SHIFT = 6,
+ GO_U8_LEAD2 = 0xC0,
+ GO_U8_LEAD3 = 0xE0,
+ GO_U8_LEAD4 = 0xF0,
+ GO_U8_LEAD_END = 0xF8,
+ GO_U8_MASK2 = 0x1F,
+ GO_U8_MASK3 = 0x0F,
+ GO_U8_MASK4 = 0x07,
+ GO_U8_MIN2 = 0x80,
+ GO_U8_MIN3 = 0x800,
+ GO_U8_MIN4 = 0x10000,
+ GO_U8_LEN3 = 3,
+ GO_U8_LEN4 = 4,
+ GO_SURROGATE_LO = 0xD800,
+ GO_SURROGATE_HI = 0xDFFF,
+ GO_RUNE_MAX = 0x10FFFF,
+};
+
+/* Not a rune: invalid UTF-8. */
+static const uint32_t GO_RUNE_BAD = 0xFFFFFFFFU;
+
+/* Length of the sequence a lead byte announces; 0 for a byte that leads none. */
+static int go_u8_len(unsigned char c) {
+ if (c < GO_ASCII_END) {
+ return SKIP_ONE;
+ }
+ if (c < GO_U8_LEAD2 || c >= GO_U8_LEAD_END) {
+ return 0;
+ }
+ if (c < GO_U8_LEAD3) {
+ return PAIR_LEN;
+ }
+ return c < GO_U8_LEAD4 ? GO_U8_LEN3 : GO_U8_LEN4;
+}
+
+/* The rune encoded by exactly s[0..n), or GO_RUNE_BAD. Overlong forms,
+ * surrogates and values past U+10FFFF are invalid, as for utf8.DecodeRune. */
+static uint32_t go_rune_decode(const unsigned char *s, int n) {
+ if (n == SKIP_ONE) {
+ return s[0];
+ }
+ static const uint32_t min_value[] = {0, 0, GO_U8_MIN2, GO_U8_MIN3, GO_U8_MIN4};
+ static const unsigned char lead_mask[] = {0, 0, GO_U8_MASK2, GO_U8_MASK3, GO_U8_MASK4};
+ uint32_t r = (uint32_t)(s[0] & lead_mask[n]);
+ for (int i = SKIP_ONE; i < n; i++) {
+ if ((s[i] & GO_U8_CONT_MASK) != GO_U8_CONT) {
+ return GO_RUNE_BAD;
+ }
+ r = (r << GO_U8_SHIFT) | (uint32_t)(s[i] & GO_U8_PAYLOAD);
+ }
+ if (r < min_value[n] || r > GO_RUNE_MAX || (r >= GO_SURROGATE_LO && r <= GO_SURROGATE_HI)) {
+ return GO_RUNE_BAD;
+ }
+ return r;
+}
+
+/* The rune that starts at s[at] (s has n bytes, at < n). */
+static uint32_t go_rune_at(const char *s, size_t n, size_t at) {
+ const unsigned char *u = (const unsigned char *)s + at;
+ int len = go_u8_len(u[0]);
+ if (len == 0 || (size_t)len > n - at) {
+ return GO_RUNE_BAD;
+ }
+ return go_rune_decode(u, len);
+}
+
+/* The rune that ends just before s[end] (end > 0). */
+static uint32_t go_rune_before(const char *s, size_t end) {
+ const unsigned char *u = (const unsigned char *)s;
+ size_t start = end - SKIP_ONE;
+ int back = SKIP_ONE;
+ while (start > 0 && back < GO_U8_LEN4 && (u[start] & GO_U8_CONT_MASK) == GO_U8_CONT) {
+ start--;
+ back++;
+ }
+ if (go_u8_len(u[start]) != back) {
+ return GO_RUNE_BAD;
+ }
+ return go_rune_decode(u + start, back);
+}
+
+static bool go_in_ranges(const go_range_t *ranges, int count, uint32_t r) {
+ int lo = 0;
+ int hi = count - SKIP_ONE;
+ while (lo <= hi) {
+ int mid = lo + ((hi - lo) / PAIR_LEN);
+ if (r < ranges[mid].lo) {
+ hi = mid - SKIP_ONE;
+ } else if (r > ranges[mid].hi) {
+ lo = mid + SKIP_ONE;
+ } else {
+ return (r - ranges[mid].lo) % ranges[mid].stride == 0;
+ }
+ }
+ return false;
+}
+
+/* unicode.IsPunct. */
+static bool go_is_punct(uint32_t r) {
+ if (r < GO_ASCII_END) {
+ return r != 0 && strchr("!\"#%&'()*,-./:;?@[\\]_{}", (int)r) != NULL;
+ }
+ return go_in_ranges(GO_PUNCT, GO_PUNCT_COUNT, r);
+}
+
+/* unicode.IsUpper. */
+static bool go_is_upper(uint32_t r) {
+ if (r < GO_ASCII_END) {
+ return r >= 'A' && r <= 'Z';
+ }
+ return r != GO_RUNE_BAD && go_in_ranges(GO_UPPER, GO_UPPER_COUNT, r);
+}
+
+/* docLink's border rule for one neighbour of the brackets. */
+static bool go_border_ok(uint32_t r) {
+ return r == ' ' || r == '\t' || r == '\n' || (r != GO_RUNE_BAD && go_is_punct(r));
+}
+
+/* ── Identifiers and reference shape (docLink, splitDocName) ─────── */
+
+/* A byte of a Go identifier. Every non-ASCII byte counts as a letter: text
+ * that is no identifier then names nothing a package declares, and the
+ * resolver treats it as plain text. */
+static bool go_ident_byte(unsigned char c) {
+ return go_ascii_alpha(c) || go_ascii_digit(c) || c == '_' || c >= GO_ASCII_END;
+}
+
+/* go/doc/comment ident(): s is one Go identifier. */
+static bool go_is_ident(const char *s, size_t n) {
+ if (n == 0 || n > GO_REF_MAX || go_ascii_digit((unsigned char)s[0])) {
+ return false;
+ }
+ for (size_t i = 0; i < n; i++) {
+ if (!go_ident_byte((unsigned char)s[i])) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* go/doc/comment isName(): an identifier whose first letter is upper case,
+ * which is also what makes a Go identifier exported. */
+static bool go_is_name(const char *s, size_t n) {
+ return go_is_ident(s, n) && go_is_upper(go_rune_at(s, n, 0));
+}
+
+static bool go_import_path_byte(unsigned char c) {
+ return go_ascii_alpha(c) || go_ascii_digit(c) || c == '-' || c == '.' || c == '_' || c == '~' ||
+ c == '+';
+}
+
+static bool go_import_elem_ok(const char *s, size_t n) {
+ if (n == 0 || s[0] == '.' || s[n - SKIP_ONE] == '.') {
+ return false;
+ }
+ for (size_t i = 0; i < n; i++) {
+ if (!go_import_path_byte((unsigned char)s[i])) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* go/doc/comment validImportPath. */
+static bool go_valid_import_path(const char *s, size_t n) {
+ if (n == 0 || n > GO_PATH_MAX || s[0] == '-' || s[n - SKIP_ONE] == '/') {
+ return false;
+ }
+ size_t start = 0;
+ for (size_t i = 0; i <= n; i++) {
+ if (i == n || s[i] == '/') {
+ if (!go_import_elem_ok(s + start, i - start)) {
+ return false;
+ }
+ start = i + SKIP_ONE;
+ }
+ }
+ return true;
+}
+
+/* An import name as a file can give one: identifier bytes only. */
+static bool go_pkg_word(const char *s, size_t n) {
+ if (n == 0 || n > GO_REF_MAX) {
+ return false;
+ }
+ for (size_t i = 0; i < n; i++) {
+ if (!go_ident_byte((unsigned char)s[i])) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* splitDocName: `before.Name` with a capitalized Name. False when the text
+ * after the last dot is no Name (then nothing is split off). */
+static bool go_split_name(const char *s, size_t n, size_t *before_len, const char **name,
+ size_t *name_len) {
+ size_t dot = n;
+ for (size_t i = n; i > 0; i--) {
+ if (s[i - SKIP_ONE] == '.') {
+ dot = i - SKIP_ONE;
+ break;
+ }
+ }
+ size_t ns = dot < n ? dot + SKIP_ONE : 0;
+ if (!go_is_name(s + ns, n - ns)) {
+ return false;
+ }
+ *name = s + ns;
+ *name_len = n - ns;
+ *before_len = dot < n ? dot : 0;
+ return true;
+}
+
+bool cbm_doclink_go_parse_ref(const char *raw, size_t len, CBMDocLinkGoRef *out) {
+ memset(out, 0, sizeof(*out));
+ if (!raw || len == 0 || len > GO_REF_MAX) {
+ return false;
+ }
+ const char *s = raw;
+ size_t n = len;
+ if (s[0] == '*') {
+ s++;
+ n--;
+ }
+ size_t before = 0;
+ out->pkg = s;
+ out->pkg_len = n;
+ if (go_split_name(s, n, &before, &out->name, &out->name_len)) {
+ size_t pkg_len = 0;
+ out->pkg_len = before;
+ if (go_split_name(s, before, &pkg_len, &out->recv, &out->recv_len)) {
+ out->pkg_len = pkg_len;
+ }
+ }
+ if (out->pkg_len == 0) {
+ return out->name_len > 0; /* [Name], [Recv.Name]: the current package */
+ }
+ if (memchr(out->pkg, '/', out->pkg_len)) {
+ return go_valid_import_path(out->pkg, out->pkg_len);
+ }
+ return go_pkg_word(out->pkg, out->pkg_len);
+}
+
+/* Bracket text longer than this scan handles: true when its bytes are those a
+ * doc link is made of, so that it is reported instead of dropped. */
+static bool go_long_ref_shaped(const char *s, size_t n) {
+ size_t i = (n > 0 && s[0] == '*') ? SKIP_ONE : 0;
+ if (i >= n) {
+ return false;
+ }
+ for (; i < n; i++) {
+ unsigned char c = (unsigned char)s[i];
+ if (!go_ident_byte(c) && !go_import_path_byte(c) && c != '/') {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* The longest prefix of s[0..n) of at most `max` bytes that ends on a rune
+ * boundary. */
+static size_t go_clip(const char *s, size_t n, size_t max) {
+ if (n <= max) {
+ return n;
+ }
+ size_t cut = max;
+ while (cut > 0 && ((unsigned char)s[cut] & GO_U8_CONT_MASK) == GO_U8_CONT) {
+ cut--;
+ }
+ return cut;
+}
+
+/* ── Doc text model ──────────────────────────────────────────────── */
+
+/* One line of the comment text: a slice of the doc string. */
+typedef struct {
+ const char *s;
+ uint32_t len;
+ uint32_t line; /* 1-based source line */
+} go_line_t;
+
+enum { GO_SPAN_CODE = 1, GO_SPAN_HEADING, GO_SPAN_LIST, GO_SPAN_PARA };
+
+typedef struct {
+ int start;
+ int end;
+ int kind;
+} go_span_t;
+
+/* `[text]: url`, one line of a link-definition paragraph. */
+typedef struct {
+ const char *text;
+ size_t text_len;
+ const char *url;
+ size_t url_len;
+ int order;
+} go_linkdef_t;
+
+typedef struct {
+ CBMExtractCtx *ctx;
+ CBMArena *tmp;
+ const char *source_qn;
+ const char **params; /* the documented definition's parameter names, or NULL */
+ uint32_t def_line;
+ go_line_t *lines;
+ int nlines;
+ int lines_cap;
+ go_span_t *spans;
+ int nspans;
+ int spans_cap;
+ go_linkdef_t *defs;
+ int ndefs;
+ int defs_cap;
+ go_line_t *para; /* the lines of one list-item paragraph */
+ bool failed;
+} go_doc_t;
+
+static void go_push_line(go_doc_t *d, const char *s, size_t len, uint32_t line) {
+ while (len > 0 && go_space(s[len - SKIP_ONE])) {
+ len--; /* ast.CommentGroup.Text strips trailing white space */
+ }
+ go_line_t *grown =
+ (go_line_t *)go_grow(d->tmp, d->lines, d->nlines, &d->lines_cap, sizeof(go_line_t));
+ if (!grown) {
+ d->failed = true;
+ return;
+ }
+ d->lines = grown;
+ d->lines[d->nlines++] = (go_line_t){.s = s, .len = (uint32_t)len, .line = line};
+}
+
+static bool go_lower_or_digit(char b) {
+ return (b >= 'a' && b <= 'z') || (b >= '0' && b <= '9');
+}
+
+/* go/ast isDirective: //line, //extern, //export and //[a-z0-9]+:[a-z0-9]. */
+static bool go_is_directive(const char *c, size_t n) {
+ if (go_has_prefix(c, n, "line ") || go_has_prefix(c, n, "extern ") ||
+ go_has_prefix(c, n, "export ")) {
+ return true;
+ }
+ const char *colon = (const char *)memchr(c, ':', n);
+ if (!colon || colon == c || (size_t)(colon - c) + SKIP_ONE >= n) {
+ return false;
+ }
+ size_t ci = (size_t)(colon - c);
+ for (size_t i = 0; i <= ci + SKIP_ONE; i++) {
+ if (i != ci && !go_lower_or_digit(c[i])) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* The text of one `//` comment (c = what follows the slashes). */
+static void go_line_comment(go_doc_t *d, const char *c, size_t n, uint32_t line) {
+ if (n > 0 && c[0] == ' ') {
+ go_push_line(d, c + SKIP_ONE, n - SKIP_ONE, line);
+ } else if (n == 0 || !go_is_directive(c, n)) {
+ go_push_line(d, c, n, line);
+ }
+}
+
+/* The lines of one block comment body [c, end); returns the line breaks in it. */
+static uint32_t go_block_comment(go_doc_t *d, const char *c, const char *end, uint32_t line) {
+ uint32_t added = 0;
+ for (;;) {
+ const char *nl = (const char *)memchr(c, '\n', (size_t)(end - c));
+ const char *le = nl ? nl : end;
+ go_push_line(d, c, (size_t)(le - c), line + added);
+ if (!nl) {
+ return added;
+ }
+ added++;
+ c = nl + SKIP_ONE;
+ }
+}
+
+/* ast.CommentGroup.Text over the stored comment group: one comment per text
+ * line, a block comment keeping its own lines. Text line k of the group is
+ * source line doc_line + k. Every byte is looked at once: a comment is
+ * consumed whole, then the scan continues behind its line. */
+static void go_group_lines(go_doc_t *d, const char *doc, uint32_t doc_line) {
+ const char *p = doc;
+ uint32_t line = doc_line;
+ while (*p && !d->failed) {
+ const char *rest = p;
+ if (p[0] == '/' && p[SKIP_ONE] == '/') {
+ const char *eol = strchr(p, '\n');
+ const char *end = eol ? eol : p + strlen(p);
+ go_line_comment(d, p + GO_MARKER_LEN, (size_t)(end - p) - GO_MARKER_LEN, line);
+ rest = end;
+ } else if (p[0] == '/' && p[SKIP_ONE] == '*') {
+ const char *body = p + GO_MARKER_LEN;
+ const char *close = strstr(body, "*/");
+ const char *end = close ? close : body + strlen(body);
+ line += go_block_comment(d, body, end, line);
+ rest = close ? close + GO_MARKER_LEN : end;
+ }
+ const char *eol = strchr(rest, '\n');
+ if (!eol) {
+ break;
+ }
+ p = eol + SKIP_ONE;
+ line++;
+ }
+}
+
+static size_t go_leading_space(const go_line_t *l) {
+ size_t i = 0;
+ while (i < l->len && go_blank_or_tab(l->s[i])) {
+ i++;
+ }
+ return i;
+}
+
+/* go/doc/comment unindent: drop the blank lines at both ends and the common
+ * space/tab prefix of the others. */
+static void go_unindent(go_doc_t *d) {
+ int first = 0;
+ int last = d->nlines;
+ while (first < last && d->lines[first].len == 0) {
+ first++;
+ }
+ while (last > first && d->lines[last - SKIP_ONE].len == 0) {
+ last--;
+ }
+ d->lines += first;
+ d->nlines = last - first;
+ d->lines_cap -= first;
+ if (d->nlines == 0) {
+ return;
+ }
+ const char *prefix = d->lines[0].s;
+ size_t plen = go_leading_space(&d->lines[0]);
+ for (int i = SKIP_ONE; i < d->nlines && plen > 0; i++) {
+ const go_line_t *l = &d->lines[i];
+ if (l->len == 0) {
+ continue;
+ }
+ size_t ls = go_leading_space(l);
+ size_t k = 0;
+ while (k < plen && k < ls && prefix[k] == l->s[k]) {
+ k++;
+ }
+ plen = k;
+ }
+ for (int i = 0; i < d->nlines && plen > 0; i++) {
+ go_line_t *l = &d->lines[i];
+ if (l->len >= plen) {
+ l->s += plen;
+ l->len -= (uint32_t)plen;
+ }
+ }
+}
+
+static bool go_indented(const go_line_t *l) {
+ return l->len > 0 && go_blank_or_tab(l->s[0]);
+}
+
+/* go/doc/comment listMarker: the text after a bullet (`*`, `+`, `-`, U+2022)
+ * or a number followed by `.` or `)`; NULL when the line starts no list item.
+ * The marker must be followed by a space or tab and then text. */
+static const char *go_list_marker(const go_line_t *l, size_t *rest_len, bool *numbered) {
+ static const char bullet[] = "\xE2\x80\xA2";
+ const size_t bullet_len = sizeof(bullet) - SKIP_ONE;
+ const char *s = l->s;
+ size_t n = l->len;
+ go_trim(&s, &n);
+ size_t skip = 0;
+ *numbered = false;
+ if (n > 0 && (s[0] == '*' || s[0] == '+' || s[0] == '-')) {
+ skip = SKIP_ONE;
+ } else if (go_has_prefix(s, n, bullet)) {
+ skip = bullet_len;
+ } else {
+ while (skip < n && go_ascii_digit((unsigned char)s[skip])) {
+ skip++;
+ }
+ if (skip == 0 || skip >= n || (s[skip] != '.' && s[skip] != ')')) {
+ return NULL;
+ }
+ skip++;
+ *numbered = true;
+ }
+ const char *rest = s + skip;
+ size_t rn = n - skip;
+ if (rn == 0 || !go_blank_or_tab(rest[0])) {
+ return NULL;
+ }
+ *rest_len = rn;
+ return rest; /* n was trimmed, so text follows the white space */
+}
+
+static bool go_is_list(const go_line_t *l) {
+ size_t rest_len = 0;
+ bool numbered = false;
+ return go_list_marker(l, &rest_len, &numbered) != NULL;
+}
+
+/* go/doc/comment isHeading (trailing white space is already gone). */
+static bool go_is_heading(const go_line_t *l) {
+ return l->len >= PAIR_LEN && l->s[0] == '#' && go_blank_or_tab(l->s[SKIP_ONE]);
+}
+
+static bool go_push_span(go_doc_t *d, int start, int end, int kind) {
+ go_span_t *grown =
+ (go_span_t *)go_grow(d->tmp, d->spans, d->nspans, &d->spans_cap, sizeof(go_span_t));
+ if (!grown) {
+ d->failed = true;
+ return false;
+ }
+ d->spans = grown;
+ d->spans[d->nspans++] = (go_span_t){.start = start, .end = end, .kind = kind};
+ return true;
+}
+
+/* An indented (or force-indented) run starting at `start`: a code block or a
+ * list. Blank lines belong to it; an unindented list that is being treated as
+ * indented takes further unindented list items up to the first blank line. A
+ * `}` line right after the run is taken along (pasted, unindented code). */
+static int go_indented_span(const go_doc_t *d, int start, int force_indent, int *kind) {
+ const go_line_t *L = d->lines;
+ bool starts_list = go_is_list(&L[start]);
+ bool unindented_list_ok = starts_list && start < force_indent;
+ int i = start + SKIP_ONE;
+ while (i < d->nlines && (L[i].len == 0 || i < force_indent || go_indented(&L[i]) ||
+ (unindented_list_ok && go_is_list(&L[i])))) {
+ if (L[i].len == 0) {
+ unindented_list_ok = false;
+ }
+ i++;
+ }
+ int end = i;
+ while (end > start && L[end - SKIP_ONE].len == 0) {
+ end--;
+ }
+ if (end < d->nlines && L[end].len > 0 && L[end].s[0] == '}') {
+ end++;
+ }
+ *kind = starts_list ? GO_SPAN_LIST : GO_SPAN_CODE;
+ return end;
+}
+
+static bool go_ends_with(const go_line_t *l, char c) {
+ return l->len > 0 && l->s[l->len - SKIP_ONE] == c;
+}
+
+/* An unindented run starting at `start`: a paragraph or a heading. When an
+ * indented code block follows without a blank line, trailing lines that look
+ * like its unindented beginning (list items; a line ending in `{` or `\`)
+ * are left for it: *force_indent is then the block's first indented line. */
+static int go_unindented_span(const go_doc_t *d, int start, int *force_indent) {
+ const go_line_t *L = d->lines;
+ int i = start + SKIP_ONE;
+ while (i < d->nlines && L[i].len > 0 && !go_indented(&L[i])) {
+ i++;
+ }
+ int end = i;
+ if (i < d->nlines && L[i].len > 0 && !go_is_list(&L[i])) {
+ if (go_is_list(&L[i - SKIP_ONE])) {
+ *force_indent = end;
+ end--;
+ while (end > start && go_is_list(&L[end - SKIP_ONE])) {
+ end--;
+ }
+ } else if (go_ends_with(&L[i - SKIP_ONE], '{') || go_ends_with(&L[i - SKIP_ONE], '\\')) {
+ *force_indent = end;
+ end--;
+ }
+ }
+ return end;
+}
+
+/* go/doc/comment parseSpans. A line is looked at as unindented text at most
+ * once and as part of an indented run at most once. */
+static void go_parse_spans(go_doc_t *d) {
+ int i = 0;
+ int force_indent = 0;
+ while (!d->failed) {
+ while (i < d->nlines && d->lines[i].len == 0) {
+ i++;
+ }
+ if (i >= d->nlines) {
+ return;
+ }
+ int kind = GO_SPAN_PARA;
+ bool indented = i < force_indent || go_indented(&d->lines[i]);
+ int end = indented ? go_indented_span(d, i, force_indent, &kind)
+ : go_unindented_span(d, i, &force_indent);
+ if (end == i) {
+ continue; /* every line was left for the block: now force-indented */
+ }
+ if (!indented && end == i + SKIP_ONE && go_is_heading(&d->lines[i])) {
+ kind = GO_SPAN_HEADING; /* one unindented line: `# Title` */
+ }
+ if (!go_push_span(d, i, end, kind)) {
+ return;
+ }
+ i = end;
+ }
+}
+
+/* ── Link definitions ────────────────────────────────────────────── */
+
+static bool go_is_scheme(const char *s, size_t n) {
+ static const char *const schemes[] = {"file", "ftp", "gopher", "http",
+ "https", "mailto", "nntp"};
+ for (size_t i = 0; i < sizeof(schemes) / sizeof(schemes[0]); i++) {
+ if (strlen(schemes[i]) == n && memcmp(schemes[i], s, n) == 0) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/* Offset of the first occurrence of the two bytes `a b` in s, or n. */
+static size_t go_find2(const char *s, size_t n, char a, char b) {
+ for (size_t i = 0; i + SKIP_ONE < n; i++) {
+ if (s[i] == a && s[i + SKIP_ONE] == b) {
+ return i;
+ }
+ }
+ return n;
+}
+
+/* go/doc/comment parseLink: `[text]: url` with a known scheme. */
+static bool go_parse_linkdef(const go_line_t *l, go_linkdef_t *out) {
+ const char *s = l->s;
+ size_t n = l->len;
+ if (n == 0 || s[0] != '[') {
+ return false;
+ }
+ size_t close = go_find2(s, n, ']', ':');
+ if (close + GO_LINKDEF_TAIL >= n || !go_blank_or_tab(s[close + PAIR_LEN])) {
+ return false;
+ }
+ const char *url = s + close + GO_LINKDEF_TAIL;
+ size_t url_len = n - close - GO_LINKDEF_TAIL;
+ go_trim(&url, &url_len);
+ size_t colon = go_find2(url, url_len, ':', '/');
+ if (colon + PAIR_LEN >= url_len || url[colon + PAIR_LEN] != '/' || !go_is_scheme(url, colon)) {
+ return false;
+ }
+ out->text = s + SKIP_ONE;
+ out->text_len = close - SKIP_ONE;
+ out->url = url;
+ out->url_len = url_len;
+ return true;
+}
+
+/* A paragraph whose every line is a link definition defines links and is no
+ * text. */
+static bool go_para_is_linkdefs(const go_line_t *lines, int n) {
+ go_linkdef_t def;
+ for (int i = 0; i < n; i++) {
+ if (!go_parse_linkdef(&lines[i], &def)) {
+ return false;
+ }
+ }
+ return n > 0;
+}
+
+typedef void (*go_para_fn)(go_doc_t *d, const go_line_t *lines, int n);
+
+static void go_collect_linkdefs(go_doc_t *d, const go_line_t *lines, int n) {
+ if (!go_para_is_linkdefs(lines, n)) {
+ return;
+ }
+ for (int i = 0; i < n && !d->failed; i++) {
+ go_linkdef_t def = {0};
+ (void)go_parse_linkdef(&lines[i], &def);
+ go_linkdef_t *grown =
+ (go_linkdef_t *)go_grow(d->tmp, d->defs, d->ndefs, &d->defs_cap, sizeof(go_linkdef_t));
+ if (!grown) {
+ d->failed = true;
+ return;
+ }
+ d->defs = grown;
+ def.order = d->ndefs;
+ d->defs[d->ndefs++] = def;
+ }
+}
+
+/* Byte order of two link texts; the key side reads newline and tab as a
+ * space, as parseLinkedText does for the text between the brackets. */
+static int go_linktext_cmp(const char *key, size_t key_len, const char *text, size_t text_len,
+ bool fold_key) {
+ size_t n = key_len < text_len ? key_len : text_len;
+ for (size_t i = 0; i < n; i++) {
+ unsigned char k = (unsigned char)key[i];
+ if (fold_key && (k == '\n' || k == '\t')) {
+ k = ' ';
+ }
+ unsigned char t = (unsigned char)text[i];
+ if (k != t) {
+ return k < t ? -SKIP_ONE : SKIP_ONE;
+ }
+ }
+ if (key_len == text_len) {
+ return 0;
+ }
+ return key_len < text_len ? -SKIP_ONE : SKIP_ONE;
+}
+
+static int go_linkdef_cmp(const void *a, const void *b) {
+ const go_linkdef_t *x = (const go_linkdef_t *)a;
+ const go_linkdef_t *y = (const go_linkdef_t *)b;
+ int c = go_linktext_cmp(x->text, x->text_len, y->text, y->text_len, false);
+ return c ? c : x->order - y->order;
+}
+
+/* The first definition of the link text `key`, or NULL. */
+static const go_linkdef_t *go_find_linkdef(const go_doc_t *d, const char *key, size_t key_len) {
+ int lo = 0;
+ int hi = d->ndefs - SKIP_ONE;
+ const go_linkdef_t *hit = NULL;
+ while (lo <= hi) {
+ int mid = lo + ((hi - lo) / PAIR_LEN);
+ int c = go_linktext_cmp(key, key_len, d->defs[mid].text, d->defs[mid].text_len, true);
+ if (c == 0) {
+ hit = &d->defs[mid];
+ hi = mid - SKIP_ONE; /* the first of equal texts: defined first */
+ } else if (c < 0) {
+ hi = mid - SKIP_ONE;
+ } else {
+ lo = mid + SKIP_ONE;
+ }
+ }
+ return hit;
+}
+
+/* ── Bracket scan (parseLinkedText, docLink) ─────────────────────── */
+
+static void go_emit(go_doc_t *d, const char *raw, size_t len, uint32_t line, int syntax) {
+ char *copy = cbm_arena_strndup(d->ctx->arena, raw, len);
+ if (!copy) {
+ d->failed = true;
+ return;
+ }
+ CBMDocLink link = {
+ .source_qn = d->source_qn,
+ .raw = copy,
+ .line = line,
+ .def_line = d->def_line,
+ .syntax = (uint16_t)syntax,
+ };
+ cbm_doclinks_push(&d->ctx->result->doc_links, d->ctx->arena, link);
+}
+
+/* True when the reference is one word that names a parameter of the
+ * documented definition: local, never a reference. */
+static bool go_names_own_param(const go_doc_t *d, const CBMDocLinkGoRef *ref) {
+ if (!d->params || ref->recv_len > 0 || (ref->pkg_len > 0 && ref->name_len > 0)) {
+ return false;
+ }
+ const char *word = ref->pkg_len > 0 ? ref->pkg : ref->name;
+ size_t len = ref->pkg_len > 0 ? ref->pkg_len : ref->name_len;
+ for (const char **p = d->params; *p; p++) {
+ if (strlen(*p) == len && memcmp(*p, word, len) == 0) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/* The link definition the pair text[open] .. text[close] names, or NULL.
+ * parseLinkedText collects the looked-up text from the FIRST opening bracket
+ * since the last closing one and leaves the brackets themselves out: with one
+ * opening bracket that is the pair's own text, with `[a [b]` it is `a b`. */
+static const go_linkdef_t *go_pair_linkdef(go_doc_t *d, const char *text, size_t first, size_t open,
+ size_t close) {
+ if (d->ndefs == 0) {
+ return NULL;
+ }
+ if (first == open) {
+ return go_find_linkdef(d, text + open + SKIP_ONE, close - open - SKIP_ONE);
+ }
+ char *key = (char *)cbm_arena_alloc(d->tmp, close - first);
+ if (!key) {
+ d->failed = true;
+ return NULL;
+ }
+ size_t w = 0;
+ for (size_t i = first + SKIP_ONE; i < close; i++) {
+ if (text[i] != '[') {
+ key[w++] = text[i];
+ }
+ }
+ return go_find_linkdef(d, key, w);
+}
+
+/* One bracket pair text[open] .. text[close] of a paragraph; `first` is the
+ * first opening bracket since the last closing one. */
+static void go_bracket(go_doc_t *d, const char *text, size_t len, size_t first, size_t open,
+ size_t close, uint32_t line) {
+ const char *inner = text + open + SKIP_ONE;
+ size_t inner_len = close - open - SKIP_ONE;
+ const go_linkdef_t *def = go_pair_linkdef(d, text, first, open, close);
+ if (def) {
+ /* a URL is external whatever it says: a long one is stored clipped */
+ go_emit(d, def->url, go_clip(def->url, def->url_len, GO_URL_MAX), line, CBM_DOCLINK_HREF);
+ return;
+ }
+ if (open > 0 && !go_border_ok(go_rune_before(text, open))) {
+ return;
+ }
+ if (close + SKIP_ONE < len && !go_border_ok(go_rune_at(text, len, close + SKIP_ONE))) {
+ return;
+ }
+ if (inner_len > GO_REF_MAX) {
+ /* Not decided here, and never by its beginning: the resolver reports
+ * the clipped text as unparseable. */
+ if (go_long_ref_shaped(inner, inner_len)) {
+ go_emit(d, inner, go_clip(inner, inner_len, (size_t)GO_REF_MAX + SKIP_ONE), line,
+ CBM_DOCLINK_GO_DOC_LINK);
+ }
+ return;
+ }
+ CBMDocLinkGoRef ref;
+ if (!cbm_doclink_go_parse_ref(inner, inner_len, &ref) || go_names_own_param(d, &ref)) {
+ return;
+ }
+ go_emit(d, inner, inner_len, line, CBM_DOCLINK_GO_DOC_LINK);
+}
+
+/* The paragraph's lines joined by newlines, scanned for bracket pairs: `[`
+ * (re)starts a pair, the next `]` closes it. */
+static void go_scan_paragraph(go_doc_t *d, const go_line_t *lines, int n) {
+ if (go_para_is_linkdefs(lines, n)) {
+ return;
+ }
+ size_t total = 0;
+ bool any = false;
+ for (int i = 0; i < n; i++) {
+ total += (size_t)lines[i].len + SKIP_ONE;
+ any = any || memchr(lines[i].s, '[', lines[i].len) != NULL;
+ }
+ if (!any) {
+ return;
+ }
+ char *text = (char *)cbm_arena_alloc(d->tmp, total + SKIP_ONE);
+ if (!text) {
+ d->failed = true;
+ return;
+ }
+ size_t len = 0;
+ for (int i = 0; i < n; i++) {
+ if (i > 0) {
+ text[len++] = '\n';
+ }
+ memcpy(text + len, lines[i].s, lines[i].len);
+ len += lines[i].len;
+ }
+ text[len] = '\0';
+ int piece = 0; /* the line the scan is in */
+ int open_piece = 0;
+ size_t open = len; /* len: no open bracket */
+ size_t first = len; /* the first opening bracket since the last closing one */
+ for (size_t i = 0; i < len && !d->failed; i++) {
+ char c = text[i];
+ if (c == '\n') {
+ piece++;
+ } else if (c == '[') {
+ first = open < len ? first : i;
+ open = i;
+ open_piece = piece;
+ } else if (c == ']') {
+ if (open < len) {
+ go_bracket(d, text, len, first, open, i, lines[open_piece].line);
+ }
+ open = len;
+ }
+ }
+}
+
+/* ── Paragraphs of the comment ───────────────────────────────────── */
+
+/* go/doc/comment list(): each item is a run of paragraphs; an item starts at
+ * a marker of the list's own kind, a blank line ends a paragraph, and every
+ * line is trimmed. */
+static void go_list_paragraphs(go_doc_t *d, const go_span_t *sp, go_para_fn fn) {
+ size_t rest_len = 0;
+ bool numbered = false;
+ bool list_numbered = false;
+ (void)go_list_marker(&d->lines[sp->start], &rest_len, &list_numbered);
+ int count = 0;
+ for (int i = sp->start; i < sp->end; i++) {
+ go_line_t l = d->lines[i];
+ const char *rest = go_list_marker(&l, &rest_len, &numbered);
+ bool new_item = rest && numbered == list_numbered;
+ if (new_item) {
+ l.s = rest;
+ l.len = (uint32_t)rest_len;
+ }
+ const char *s = l.s;
+ size_t n = l.len;
+ go_trim(&s, &n);
+ if ((new_item || n == 0) && count > 0) {
+ fn(d, d->para, count);
+ count = 0;
+ }
+ if (n > 0) {
+ d->para[count++] = (go_line_t){.s = s, .len = (uint32_t)n, .line = l.line};
+ }
+ }
+ if (count > 0) {
+ fn(d, d->para, count);
+ }
+}
+
+static void go_each_paragraph(go_doc_t *d, go_para_fn fn) {
+ for (int i = 0; i < d->nspans && !d->failed; i++) {
+ const go_span_t *sp = &d->spans[i];
+ if (sp->kind == GO_SPAN_PARA) {
+ fn(d, &d->lines[sp->start], sp->end - sp->start);
+ } else if (sp->kind == GO_SPAN_LIST) {
+ go_list_paragraphs(d, sp, fn);
+ }
+ }
+}
+
+void cbm_doclink_go_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,
+ uint32_t doc_line) {
+ if (!doc || !strchr(doc, '[') || !strchr(doc, ']')) {
+ return; /* nearly every comment: no bracket, nothing to model */
+ }
+ go_doc_t d = {.ctx = ctx,
+ .tmp = go_scratch(ctx),
+ .source_qn = def->qualified_name,
+ .params = def->param_names,
+ .def_line = def->start_line};
+ go_group_lines(&d, doc, doc_line);
+ go_unindent(&d);
+ if (d.failed || d.nlines == 0) {
+ return;
+ }
+ d.para = (go_line_t *)cbm_arena_alloc(d.tmp, (size_t)d.nlines * sizeof(go_line_t));
+ if (!d.para) {
+ return;
+ }
+ go_parse_spans(&d);
+ /* Definitions first: a link may be used before the paragraph defining it. */
+ go_each_paragraph(&d, go_collect_linkdefs);
+ if (d.ndefs > SKIP_ONE) {
+ qsort(d.defs, (size_t)d.ndefs, sizeof(d.defs[0]), go_linkdef_cmp);
+ }
+ go_each_paragraph(&d, go_scan_paragraph);
+}
+
+void cbm_doclink_gomod_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,
+ uint32_t doc_line) {
+ (void)ctx;
+ (void)def;
+ (void)doc;
+ (void)doc_line; /* a go.mod comment is no Go doc comment */
+}
+
+/* ── Scope scan ──────────────────────────────────────────────────── */
+
+/* A declaration that claims the flat node name <dir>.<name>: its record gets
+ * the w flag once the file's claims of that name are all known. */
+typedef struct {
+ const char *name;
+ size_t name_len;
+ uint32_t start; /* byte offset: document order */
+ uint32_t row;
+ int rec; /* index into recs */
+} go_claim_t;
+
+typedef struct {
+ CBMExtractCtx *ctx;
+ CBMArena *tmp;
+ char **recs;
+ int nrecs;
+ int recs_cap;
+ go_claim_t *claims;
+ int nclaims;
+ int claims_cap;
+ bool failed;
+} go_scan_t;
+
+/* A string that grows in the scratch arena. */
+typedef struct {
+ CBMArena *a;
+ char *buf;
+ size_t len;
+ size_t cap;
+ bool failed;
+} go_sb_t;
+
+static void go_sb_put(go_sb_t *sb, const char *s, size_t n) {
+ if (sb->failed) {
+ return;
+ }
+ if (sb->len + n + SKIP_ONE > sb->cap) {
+ size_t ncap = sb->cap ? sb->cap : GO_SB_INIT;
+ while (ncap < sb->len + n + SKIP_ONE) {
+ ncap *= PAIR_LEN;
+ }
+ char *grown = (char *)cbm_arena_alloc(sb->a, ncap);
+ if (!grown) {
+ sb->failed = true;
+ return;
+ }
+ if (sb->len > 0) {
+ 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';
+}
+
+/* Append one name to a ','-joined list. */
+static void go_sb_name(go_sb_t *sb, const char *s, size_t n) {
+ if (sb->len > 0) {
+ go_sb_put(sb, ",", SKIP_ONE);
+ }
+ go_sb_put(sb, s, n);
+}
+
+/* The children of a node, one after the other, in linear time (ts_node_child
+ * by index is linear per call). After the last child, or after go_kids_end,
+ * the cursor is released. */
+typedef struct {
+ TSTreeCursor cur;
+ bool live;
+} go_kids_t;
+
+static void go_kids_end(go_kids_t *k) {
+ if (k->live) {
+ ts_tree_cursor_delete(&k->cur);
+ k->live = false;
+ }
+}
+
+static bool go_kids_first(go_kids_t *k, TSNode parent, TSNode *out) {
+ *k = (go_kids_t){0}; /* both are defined on every path, for the caller's loop */
+ *out = (TSNode){0};
+ if (ts_node_is_null(parent)) {
+ return false;
+ }
+ k->cur = ts_tree_cursor_new(parent);
+ k->live = true;
+ if (!ts_tree_cursor_goto_first_child(&k->cur)) {
+ go_kids_end(k);
+ return false;
+ }
+ *out = ts_tree_cursor_current_node(&k->cur);
+ return true;
+}
+
+static bool go_kids_next(go_kids_t *k, TSNode *out) {
+ if (!k->live || !ts_tree_cursor_goto_next_sibling(&k->cur)) {
+ go_kids_end(k);
+ return false;
+ }
+ *out = ts_tree_cursor_current_node(&k->cur);
+ return true;
+}
+
+/* True when the child the iteration stands on is the parent's `field`. */
+static bool go_kid_is_field(go_kids_t *k, const char *field) {
+ const char *name = k->live ? ts_tree_cursor_current_field_name(&k->cur) : NULL;
+ return name && strcmp(name, field) == 0;
+}
+
+static const char *go_node_span(const go_scan_t *s, TSNode n, size_t *len) {
+ *len = 0;
+ if (ts_node_is_null(n) || !s->ctx->source) {
+ return "";
+ }
+ uint32_t sb = ts_node_start_byte(n);
+ uint32_t eb = ts_node_end_byte(n);
+ if (eb < sb || eb > (uint32_t)s->ctx->source_len) {
+ return "";
+ }
+ *len = eb - sb;
+ return s->ctx->source + sb;
+}
+
+static bool go_kind_is(TSNode n, const char *kind) {
+ return !ts_node_is_null(n) && strcmp(ts_node_type(n), kind) == 0;
+}
+
+/* The first child of `parent` with this node kind (a null node when none). */
+static TSNode go_first_child_of_kind(TSNode parent, const char *kind) {
+ TSNode found = {0};
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, parent, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ if (strcmp(ts_node_type(ch), kind) == 0) {
+ found = ch;
+ go_kids_end(&k);
+ }
+ }
+ return found;
+}
+
+/* The text of an exported identifier node; NULL for anything else. */
+static const char *go_exported(const go_scan_t *s, TSNode n, size_t *len) {
+ const char *t = go_node_span(s, n, len);
+ return go_is_name(t, *len) ? t : NULL;
+}
+
+/* Append a record; returns its index, or CBM_NOT_FOUND. */
+static int go_push_rec(go_scan_t *s, char *rec) {
+ if (!rec) {
+ s->failed = true;
+ return CBM_NOT_FOUND;
+ }
+ char **grown = (char **)go_grow(s->tmp, s->recs, s->nrecs, &s->recs_cap, sizeof(char *));
+ if (!grown) {
+ s->failed = true;
+ return CBM_NOT_FOUND;
+ }
+ s->recs = grown;
+ s->recs[s->nrecs] = rec;
+ return s->nrecs++;
+}
+
+/* The names a type parameter list declares. */
+static void go_type_param_names(const go_scan_t *s, TSNode list, go_sb_t *out) {
+ go_kids_t decls;
+ TSNode decl;
+ for (bool ok = go_kids_first(&decls, list, &decl); ok; ok = go_kids_next(&decls, &decl)) {
+ if (!go_kind_is(decl, "type_parameter_declaration")) {
+ continue;
+ }
+ go_kids_t ids;
+ TSNode id;
+ for (bool more = go_kids_first(&ids, decl, &id); more; more = go_kids_next(&ids, &id)) {
+ size_t len = 0;
+ const char *t = go_node_span(s, id, &len);
+ if (go_kind_is(id, "identifier") && go_kid_is_field(&ids, "name") &&
+ go_is_ident(t, len)) {
+ go_sb_name(out, t, len);
+ }
+ }
+ }
+}
+
+/* The type arguments of a generic receiver `(l *List[T, U])` are the method's
+ * type parameters. */
+static void go_type_arg_names(const go_scan_t *s, TSNode args, go_sb_t *out) {
+ go_kids_t k;
+ TSNode arg;
+ for (bool ok = go_kids_first(&k, args, &arg); ok; ok = go_kids_next(&k, &arg)) {
+ TSNode id = go_kind_is(arg, "type_elem") && ts_node_named_child_count(arg) > 0
+ ? ts_node_named_child(arg, 0)
+ : arg;
+ size_t len = 0;
+ const char *t = go_node_span(s, id, &len);
+ if (go_kind_is(id, "type_identifier") && go_is_ident(t, len)) {
+ go_sb_name(out, t, len);
+ }
+ }
+}
+
+/* `g first last names`: the type parameters in scope of the declaration at
+ * `node`, from its first line to its last (a generic type's fields and method
+ * specifications are declared inside it). */
+static void go_push_generics(go_scan_t *s, TSNode node, const go_sb_t *names) {
+ if (names->failed) {
+ s->failed = true;
+ } else if (names->len > 0) {
+ (void)go_push_rec(s, cbm_arena_sprintf(s->tmp, "g\t%u\t%u\t%s",
+ ts_node_start_point(node).row + TS_LINE_OFFSET,
+ ts_node_end_point(node).row + TS_LINE_OFFSET,
+ names->buf));
+ }
+}
+
+/* The type parameters a declaration itself lists (`type_parameters`). */
+static void go_scan_type_params(go_scan_t *s, TSNode decl) {
+ TSNode tparams = ts_node_child_by_field_name(decl, TS_FIELD("type_parameters"));
+ if (ts_node_is_null(tparams)) {
+ return;
+ }
+ go_sb_t names = {.a = s->tmp};
+ go_type_param_names(s, tparams, &names);
+ go_push_generics(s, decl, &names);
+}
+
+/* Append the record of a declaration that claims the node <dir>.<name>; its w
+ * field is added by go_finish_claims. `at` is the declaration's node. */
+static void go_push_claim(go_scan_t *s, char *rec, const char *name, size_t len, TSNode at) {
+ int idx = go_push_rec(s, rec);
+ go_claim_t *grown =
+ (go_claim_t *)go_grow(s->tmp, s->claims, s->nclaims, &s->claims_cap, sizeof(go_claim_t));
+ if (idx < 0 || !grown) {
+ s->failed = true;
+ return;
+ }
+ s->claims = grown;
+ s->claims[s->nclaims++] = (go_claim_t){.name = name,
+ .name_len = len,
+ .start = ts_node_start_byte(at),
+ .row = ts_node_start_point(at).row,
+ .rec = idx};
+}
+
+static void go_scan_func(go_scan_t *s, TSNode fn) {
+ go_scan_type_params(s, fn);
+ size_t len = 0;
+ const char *name = go_exported(s, ts_node_child_by_field_name(fn, TS_FIELD("name")), &len);
+ if (name) {
+ go_push_claim(s, cbm_arena_sprintf(s->tmp, "F\t%.*s", (int)len, name), name, len, fn);
+ }
+}
+
+/* The receiver's base type name (as extract_defs.c go_receiver_type_name:
+ * through pointer_type and generic_type); its type arguments go to
+ * `generics`. NULL when the receiver type is no plain name. */
+static const char *go_receiver_type(const go_scan_t *s, TSNode recv, size_t *len,
+ go_sb_t *generics) {
+ TSNode decl = go_first_child_of_kind(recv, "parameter_declaration");
+ if (ts_node_is_null(decl)) {
+ return NULL;
+ }
+ TSNode tn = ts_node_child_by_field_name(decl, TS_FIELD("type"));
+ for (int guard = 0; guard < GO_RECV_UNWRAP && !ts_node_is_null(tn); guard++) {
+ if (go_kind_is(tn, "type_identifier")) {
+ const char *t = go_node_span(s, tn, len);
+ return go_is_ident(t, *len) ? t : NULL;
+ }
+ if (!go_kind_is(tn, "pointer_type") && !go_kind_is(tn, "generic_type")) {
+ return NULL;
+ }
+ TSNode targs = ts_node_child_by_field_name(tn, TS_FIELD("type_arguments"));
+ if (!ts_node_is_null(targs)) {
+ go_type_arg_names(s, targs, generics);
+ }
+ TSNode inner = ts_node_child_by_field_name(tn, TS_FIELD("type"));
+ tn = ts_node_is_null(inner) ? ts_node_named_child(tn, 0) : inner;
+ }
+ return NULL;
+}
+
+static void go_scan_method(go_scan_t *s, TSNode m) {
+ go_sb_t generics = {.a = s->tmp};
+ size_t recv_len = 0;
+ const char *recv = go_receiver_type(s, ts_node_child_by_field_name(m, TS_FIELD("receiver")),
+ &recv_len, &generics);
+ go_push_generics(s, m, &generics);
+ size_t len = 0;
+ const char *name = go_exported(s, ts_node_child_by_field_name(m, TS_FIELD("name")), &len);
+ if (!name) {
+ return;
+ }
+ if (!recv) {
+ recv = "?";
+ recv_len = SKIP_ONE;
+ }
+ go_push_claim(s,
+ cbm_arena_sprintf(s->tmp, "M\t%.*s\t%.*s", (int)recv_len, recv, (int)len, name),
+ name, len, m);
+}
+
+/* The implied name of an embedded field: the type's own name, without
+ * pointer, package qualifier and type arguments. */
+static const char *go_embedded_name(const go_scan_t *s, TSNode field, size_t *len) {
+ TSNode tn = ts_node_child_by_field_name(field, TS_FIELD("type"));
+ for (int guard = 0; guard < GO_EMBED_UNWRAP && !ts_node_is_null(tn); guard++) {
+ if (go_kind_is(tn, "type_identifier")) {
+ return go_exported(s, tn, len);
+ }
+ if (go_kind_is(tn, "qualified_type")) {
+ tn = ts_node_child_by_field_name(tn, TS_FIELD("name"));
+ } else if (go_kind_is(tn, "generic_type") || go_kind_is(tn, "pointer_type")) {
+ TSNode inner = ts_node_child_by_field_name(tn, TS_FIELD("type"));
+ tn = ts_node_is_null(inner) ? ts_node_named_child(tn, 0) : inner;
+ } else {
+ return NULL;
+ }
+ }
+ return NULL;
+}
+
+static void go_push_field(go_scan_t *s, const char *type, size_t type_len, const char *name,
+ size_t len, bool node) {
+ (void)go_push_rec(s, cbm_arena_sprintf(s->tmp, "f\t%.*s\t%.*s\t%d", (int)type_len, type,
+ (int)len, name, node ? GO_NODE_FLAG : 0));
+}
+
+/* `f type name node` for every exported name of one field declaration. The
+ * extractor gives a node to the declaration's first name only. */
+static void go_scan_field(go_scan_t *s, const char *type, size_t type_len, TSNode field) {
+ bool first = true;
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, field, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ if (!go_kid_is_field(&k, "name")) {
+ continue;
+ }
+ size_t len = 0;
+ const char *name = go_exported(s, ch, &len);
+ if (name) {
+ go_push_field(s, type, type_len, name, len, first);
+ }
+ first = false;
+ }
+ if (first) { /* no name: an embedded field */
+ size_t len = 0;
+ const char *name = go_embedded_name(s, field, &len);
+ if (name) {
+ go_push_field(s, type, type_len, name, len, false);
+ }
+ }
+}
+
+/* The fields of a struct type / the methods of an interface type. */
+static void go_scan_members(go_scan_t *s, const char *type, size_t type_len, TSNode body) {
+ TSNode list = go_kind_is(body, "struct_type")
+ ? go_first_child_of_kind(body, "field_declaration_list")
+ : body;
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, list, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ if (go_kind_is(ch, "field_declaration")) {
+ go_scan_field(s, type, type_len, ch);
+ } else if (go_kind_is(ch, "method_elem")) {
+ size_t len = 0;
+ const char *name =
+ go_exported(s, ts_node_child_by_field_name(ch, TS_FIELD("name")), &len);
+ if (name) {
+ (void)go_push_rec(s, cbm_arena_sprintf(s->tmp, "m\t%.*s\t%.*s", (int)type_len, type,
+ (int)len, name));
+ }
+ }
+ }
+}
+
+/* The target of `type X = Y`: "Y" or "pkg.Y" (type arguments dropped); "-"
+ * for anything that is no named type. */
+static const char *go_alias_target(go_scan_t *s, TSNode type) {
+ TSNode tn = go_kind_is(type, "generic_type")
+ ? ts_node_child_by_field_name(type, TS_FIELD("type"))
+ : type;
+ size_t len = 0;
+ const char *target = "-";
+ if (go_kind_is(tn, "type_identifier")) {
+ const char *t = go_exported(s, tn, &len);
+ target = t ? cbm_arena_strndup(s->tmp, t, len) : "-";
+ } else if (go_kind_is(tn, "qualified_type")) {
+ size_t pkg_len = 0;
+ const char *pkg =
+ go_node_span(s, ts_node_child_by_field_name(tn, TS_FIELD("package")), &pkg_len);
+ const char *name = go_exported(s, ts_node_child_by_field_name(tn, TS_FIELD("name")), &len);
+ if (name && go_is_ident(pkg, pkg_len)) {
+ target = cbm_arena_sprintf(s->tmp, "%.*s.%.*s", (int)pkg_len, pkg, (int)len, name);
+ }
+ }
+ s->failed = s->failed || !target;
+ return target ? target : "-";
+}
+
+/* One type_spec or type_alias. */
+static void go_scan_type(go_scan_t *s, TSNode spec) {
+ go_scan_type_params(s, spec);
+ size_t len = 0;
+ const char *name = go_exported(s, ts_node_child_by_field_name(spec, TS_FIELD("name")), &len);
+ if (!name) {
+ return;
+ }
+ TSNode type = ts_node_child_by_field_name(spec, TS_FIELD("type"));
+ char kind = 'o';
+ const char *alias = "-";
+ if (go_kind_is(spec, "type_alias")) {
+ kind = 'a';
+ alias = go_alias_target(s, type);
+ } else if (go_kind_is(type, "struct_type")) {
+ kind = 's';
+ } else if (go_kind_is(type, "interface_type")) {
+ kind = 'i';
+ }
+ go_push_claim(s, cbm_arena_sprintf(s->tmp, "T\t%.*s\t%c\t%s", (int)len, name, kind, alias),
+ name, len, spec);
+ if (kind == 's' || kind == 'i') {
+ go_scan_members(s, name, len, type);
+ }
+}
+
+static void go_scan_type_decl(go_scan_t *s, TSNode decl) {
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, decl, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ if (go_kind_is(ch, "type_spec") || go_kind_is(ch, "type_alias")) {
+ go_scan_type(s, ch);
+ }
+ }
+}
+
+/* `V name w` for every exported name of a const_spec / var_spec. The extractor
+ * gives a node to the FIRST name of a spec that is a direct child of its
+ * declaration (every constant spec; a `var` without parentheses): that name
+ * claims <dir>.<name>, the others have w `-`. */
+static void go_scan_value_spec(go_scan_t *s, TSNode spec, bool spec_has_node) {
+ bool first = true;
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, spec, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ if (!go_kid_is_field(&k, "name")) {
+ continue;
+ }
+ size_t len = 0;
+ const char *name = go_exported(s, ch, &len);
+ if (name && first && spec_has_node) {
+ go_push_claim(s, cbm_arena_sprintf(s->tmp, "V\t%.*s", (int)len, name), name, len, spec);
+ } else if (name) {
+ (void)go_push_rec(s, cbm_arena_sprintf(s->tmp, "V\t%.*s\t-", (int)len, name));
+ }
+ first = false;
+ }
+}
+
+/* The specs of a parenthesized `var ( ... )`: none of them has a node. */
+static void go_scan_var_list(go_scan_t *s, TSNode list) {
+ go_kids_t k;
+ TSNode spec;
+ for (bool ok = go_kids_first(&k, list, &spec); ok; ok = go_kids_next(&k, &spec)) {
+ if (go_kind_is(spec, "var_spec")) {
+ go_scan_value_spec(s, spec, false);
+ }
+ }
+}
+
+static void go_scan_value_decl(go_scan_t *s, TSNode decl) {
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, decl, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ if (go_kind_is(ch, "const_spec") || go_kind_is(ch, "var_spec")) {
+ go_scan_value_spec(s, ch, true);
+ } else if (go_kind_is(ch, "var_spec_list")) {
+ go_scan_var_list(s, ch);
+ }
+ }
+}
+
+/* The content of an import path literal; NULL when it is none this scan can
+ * record (not a plain string, empty, too long, or with bytes no path has). */
+static const char *go_import_path(const go_scan_t *s, TSNode lit, size_t *len) {
+ const char *t = go_node_span(s, lit, len);
+ if (*len < PAIR_LEN || (t[0] != '"' && t[0] != '`') || t[*len - SKIP_ONE] != t[0]) {
+ return NULL;
+ }
+ t++;
+ *len -= PAIR_LEN;
+ if (*len == 0 || *len > GO_PATH_MAX) {
+ return NULL;
+ }
+ for (size_t i = 0; i < *len; i++) {
+ unsigned char c = (unsigned char)t[i];
+ if (c <= ' ' || c == '\\' || c == '"' || c == '`' || c == GO_ASCII_DEL) {
+ return NULL;
+ }
+ }
+ return t;
+}
+
+static void go_scan_import_spec(go_scan_t *s, TSNode spec) {
+ size_t path_len = 0;
+ const char *path =
+ go_import_path(s, ts_node_child_by_field_name(spec, TS_FIELD("path")), &path_len);
+ TSNode name = ts_node_child_by_field_name(spec, TS_FIELD("name"));
+ size_t len = 0;
+ const char *local = go_node_span(s, name, &len);
+ if (ts_node_is_null(name)) {
+ local = "-";
+ len = SKIP_ONE;
+ } else if (!go_kind_is(name, "package_identifier") || !go_is_ident(local, len) ||
+ (len == SKIP_ONE && local[0] == '_')) {
+ return; /* `.` and `_` imports give no qualifier */
+ }
+ if (!path && ts_node_is_null(name)) {
+ return; /* neither a name nor a path to derive one from */
+ }
+ if (!path) {
+ path = "?"; /* the qualifier exists; where it leads is not known */
+ path_len = SKIP_ONE;
+ }
+ (void)go_push_rec(
+ s, cbm_arena_sprintf(s->tmp, "I\t%.*s\t%.*s", (int)len, local, (int)path_len, path));
+}
+
+static void go_scan_import_list(go_scan_t *s, TSNode list) {
+ go_kids_t k;
+ TSNode spec;
+ for (bool ok = go_kids_first(&k, list, &spec); ok; ok = go_kids_next(&k, &spec)) {
+ if (go_kind_is(spec, "import_spec")) {
+ go_scan_import_spec(s, spec);
+ }
+ }
+}
+
+static void go_scan_imports(go_scan_t *s, TSNode decl) {
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, decl, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ if (go_kind_is(ch, "import_spec")) {
+ go_scan_import_spec(s, ch);
+ } else if (go_kind_is(ch, "import_spec_list")) {
+ go_scan_import_list(s, ch);
+ }
+ }
+}
+
+/* A `//go:build` or `// +build` line: the file is built only under a
+ * constraint. *ignore is set when the constraint is the word `ignore`: such a
+ * file is in no package. */
+static bool go_comment_is_build_line(const go_scan_t *s, TSNode comment, bool *ignore) {
+ size_t n = 0;
+ const char *t = go_node_span(s, comment, &n);
+ static const char *const forms[] = {"//go:build", "// +build", "//+build"};
+ static const char word[] = "ignore";
+ for (size_t i = 0; i < sizeof(forms) / sizeof(forms[0]); i++) {
+ size_t fl = strlen(forms[i]);
+ if (!go_has_prefix(t, n, forms[i]) || (n > fl && !go_space(t[fl]))) {
+ continue;
+ }
+ const char *rest = t + fl;
+ size_t rn = n - fl;
+ go_trim(&rest, &rn);
+ *ignore = *ignore || (rn == sizeof(word) - SKIP_ONE && memcmp(rest, word, rn) == 0);
+ return true;
+ }
+ return false;
+}
+
+/* A declaration that names nodes wherever the extractor's definition walk
+ * finds it. */
+static bool go_scan_decl(go_scan_t *s, TSNode n) {
+ if (go_kind_is(n, "function_declaration")) {
+ go_scan_func(s, n);
+ } else if (go_kind_is(n, "method_declaration")) {
+ go_scan_method(s, n);
+ } else if (go_kind_is(n, "type_declaration")) {
+ go_scan_type_decl(s, n);
+ } else {
+ return false;
+ }
+ return true;
+}
+
+/* Push the children of `n` on the walk's stack. */
+static TSNode *go_push_children(go_scan_t *s, TSNode n, TSNode *stack, int *top, int *cap) {
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, n, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ TSNode *grown = (TSNode *)go_grow(s->tmp, stack, *top, cap, sizeof(TSNode));
+ if (!grown) {
+ s->failed = true;
+ go_kids_end(&k);
+ continue;
+ }
+ stack = grown;
+ stack[(*top)++] = ch;
+ }
+ return stack;
+}
+
+/* A tree with parse errors: functions, methods and types are found wherever
+ * the extractor's walk finds them (it descends into everything but function
+ * nodes), so that this scan and the graph agree on what is declared. An
+ * explicit stack: the depth is the input's. */
+static void go_scan_error_tree(go_scan_t *s, TSNode root) {
+ int cap = 0;
+ int top = 0;
+ TSNode *stack = (TSNode *)go_grow(s->tmp, NULL, 0, &cap, sizeof(TSNode));
+ if (!stack) {
+ s->failed = true;
+ return;
+ }
+ stack[top++] = root;
+ while (top > 0 && !s->failed) {
+ TSNode n = stack[--top];
+ if (go_scan_decl(s, n) || go_kind_is(n, "method_elem") || go_kind_is(n, "func_literal")) {
+ continue;
+ }
+ stack = go_push_children(s, n, stack, &top, &cap);
+ }
+}
+
+static int go_claim_cmp(const void *a, const void *b) {
+ const go_claim_t *x = (const go_claim_t *)a;
+ const go_claim_t *y = (const go_claim_t *)b;
+ size_t n = x->name_len < y->name_len ? x->name_len : y->name_len;
+ int c = memcmp(x->name, y->name, n);
+ if (c == 0 && x->name_len != y->name_len) {
+ c = x->name_len < y->name_len ? -SKIP_ONE : SKIP_ONE;
+ }
+ if (c != 0) {
+ return c;
+ }
+ return (x->start > y->start) - (x->start < y->start);
+}
+
+static bool go_claim_same_name(const go_claim_t *a, const go_claim_t *b) {
+ return a->name_len == b->name_len && memcmp(a->name, b->name, a->name_len) == 0;
+}
+
+/* The w flag of the claims [first, end) of one name, in text order: they share
+ * one node name, and the graph keeps the declaration that starts on the LAST
+ * line (cbm_gbuf_upsert_node: largest start_line). Two on that line:
+ * contested. */
+static void go_flag_claims(go_scan_t *s, int first, int end) {
+ uint32_t last_row = s->claims[end - SKIP_ONE].row;
+ bool contested = end - first > SKIP_ONE && s->claims[end - PAIR_LEN].row == last_row;
+ for (int k = first; k < end; k++) {
+ char w = '0';
+ if (contested && s->claims[k].row == last_row) {
+ w = 'x';
+ } else if (!contested && k == end - SKIP_ONE) {
+ w = '1';
+ }
+ int rec = s->claims[k].rec;
+ s->recs[rec] = cbm_arena_sprintf(s->tmp, "%s\t%c", s->recs[rec], w);
+ s->failed = s->failed || !s->recs[rec];
+ }
+}
+
+static void go_finish_claims(go_scan_t *s) {
+ if (s->nclaims > SKIP_ONE) {
+ qsort(s->claims, (size_t)s->nclaims, sizeof(s->claims[0]), go_claim_cmp);
+ }
+ int i = 0;
+ while (i < s->nclaims && !s->failed) {
+ int end = i + SKIP_ONE;
+ while (end < s->nclaims && go_claim_same_name(&s->claims[i], &s->claims[end])) {
+ end++;
+ }
+ go_flag_claims(s, i, end);
+ i = end;
+ }
+}
+
+static int go_rec_cmp(const void *a, const void *b) {
+ return strcmp(*(char *const *)a, *(char *const *)b);
+}
+
+/* "go1" and the sorted, de-duplicated records, in the result arena. */
+static const char *go_blob(go_scan_t *s) {
+ if (s->failed) {
+ return NULL;
+ }
+ if (s->nrecs > SKIP_ONE) {
+ qsort(s->recs, (size_t)s->nrecs, sizeof(s->recs[0]), go_rec_cmp);
+ }
+ size_t total = sizeof(CBM_DOCLINK_GO_SCOPE_TAG);
+ for (int i = 0; i < s->nrecs; i++) {
+ total += strlen(s->recs[i]) + SKIP_ONE;
+ }
+ char *blob = (char *)cbm_arena_alloc(s->ctx->arena, total + SKIP_ONE);
+ if (!blob) {
+ return NULL;
+ }
+ size_t w = sizeof(CBM_DOCLINK_GO_SCOPE_TAG) - SKIP_ONE;
+ memcpy(blob, CBM_DOCLINK_GO_SCOPE_TAG, w);
+ for (int i = 0; i < s->nrecs; i++) {
+ if (i > 0 && strcmp(s->recs[i], s->recs[i - SKIP_ONE]) == 0) {
+ continue;
+ }
+ size_t len = strlen(s->recs[i]);
+ blob[w++] = '\n';
+ memcpy(blob + w, s->recs[i], len);
+ w += len;
+ }
+ blob[w] = '\0';
+ return blob;
+}
+
+/* What the file's head says about its package. */
+typedef struct {
+ const char *pkg;
+ size_t pkg_len;
+ bool seen_package;
+ bool ignored;
+ bool constrained;
+ bool has_error;
+} go_head_t;
+
+/* One child of the source file. Values are declared at this level only (the
+ * extractor reads variables and constants from the root's children); the
+ * other declarations are taken here when the tree has no parse error. */
+static void go_scan_top(go_scan_t *s, TSNode ch, go_head_t *h) {
+ if (go_kind_is(ch, "comment")) {
+ if (!h->seen_package && go_comment_is_build_line(s, ch, &h->ignored)) {
+ h->constrained = true;
+ }
+ } else if (go_kind_is(ch, "package_clause")) {
+ h->seen_package = true;
+ if (!h->pkg && ts_node_named_child_count(ch) > 0) {
+ const char *t = go_node_span(s, ts_node_named_child(ch, 0), &h->pkg_len);
+ h->pkg = go_is_ident(t, h->pkg_len) ? t : NULL;
+ }
+ } else if (go_kind_is(ch, "import_declaration")) {
+ go_scan_imports(s, ch);
+ } else if (go_kind_is(ch, "const_declaration") || go_kind_is(ch, "var_declaration")) {
+ go_scan_value_decl(s, ch);
+ } else if (!h->has_error) {
+ (void)go_scan_decl(s, ch);
+ }
+}
+
+enum { GO_HEAD_FLAGS = 4 }; /* i, c, e and the terminator */
+
+/* The flags field of the P record: `-` when none is set. */
+static void go_head_flags(const go_head_t *h, char out[GO_HEAD_FLAGS]) {
+ size_t n = 0;
+ if (h->ignored) {
+ out[n++] = 'i';
+ }
+ if (h->constrained && !h->ignored) {
+ out[n++] = 'c';
+ }
+ if (h->has_error) {
+ out[n++] = 'e';
+ }
+ if (n == 0) {
+ out[n++] = '-';
+ }
+ out[n] = '\0';
+}
+
+const char *cbm_doclink_go_scan_scope(CBMExtractCtx *ctx) {
+ go_scan_t s = {.ctx = ctx, .tmp = go_scratch(ctx)};
+ go_head_t h = {.has_error = ts_node_has_error(ctx->root)};
+ go_kids_t k;
+ TSNode ch;
+ for (bool ok = go_kids_first(&k, ctx->root, &ch); ok; ok = go_kids_next(&k, &ch)) {
+ go_scan_top(&s, ch, &h);
+ }
+ if (h.has_error) {
+ go_scan_error_tree(&s, ctx->root);
+ }
+ if (h.pkg) {
+ char flags[GO_HEAD_FLAGS];
+ go_head_flags(&h, flags);
+ (void)go_push_rec(&s,
+ cbm_arena_sprintf(s.tmp, "P\t%.*s\t%s", (int)h.pkg_len, h.pkg, flags));
+ }
+ go_finish_claims(&s);
+ return go_blob(&s);
+}
+
+/* The module path of a go.mod file: `G path`. */
+const char *cbm_doclink_gomod_scan_scope(CBMExtractCtx *ctx) {
+ go_scan_t s = {.ctx = ctx, .tmp = go_scratch(ctx)};
+ TSNode directive = go_first_child_of_kind(ctx->root, "module_directive");
+ TSNode path = go_first_child_of_kind(directive, "module_path");
+ size_t len = 0;
+ const char *t = go_node_span(&s, path, &len);
+ if (len >= PAIR_LEN && (t[0] == '"' || t[0] == '`') && t[len - SKIP_ONE] == t[0]) {
+ t++;
+ len -= PAIR_LEN;
+ }
+ if (go_valid_import_path(t, len)) {
+ (void)go_push_rec(&s, cbm_arena_sprintf(s.tmp, "G\t%.*s", (int)len, t));
+ }
+ return go_blob(&s);
+}
+
+/* The persisted scope: the blob without its `g` lines (the only records that
+ * carry a line number, and the only ones no other file reads). */
+char *cbm_doclink_go_portable_scope(const char *scope) {
+ size_t n = strlen(scope);
+ char *out = (char *)cbm_alloc(CBM_MEM_CLASS_OTHER, n + SKIP_ONE);
+ if (!out) {
+ return NULL;
+ }
+ size_t w = 0;
+ for (const char *p = scope; *p;) {
+ const char *nl = strchr(p, '\n');
+ size_t len = nl ? (size_t)(nl - p) : strlen(p);
+ if (!(len >= PAIR_LEN && p[0] == 'g' && p[SKIP_ONE] == '\t')) {
+ if (w > 0) {
+ out[w++] = '\n';
+ }
+ memcpy(out + w, p, len);
+ w += len;
+ }
+ p = nl ? nl + SKIP_ONE : p + len;
+ }
+ out[w] = '\0';
+ return out;
+}
diff --git a/src/pipeline/doc_links.c b/src/pipeline/doc_links.c
index c5023658d..17e84eecb 100644
--- a/src/pipeline/doc_links.c
+++ b/src/pipeline/doc_links.c
@@ -46,7 +46,7 @@ const char *cbm_doclink_reason_name(int reason) {
* to this file. */
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_rst_resolver, &cbm_doclink_adoc_resolver, &cbm_doclink_go_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.h
index 77a5dfb67..13eaea13c 100644
--- a/src/pipeline/doc_links.h
+++ b/src/pipeline/doc_links.h
@@ -295,6 +295,7 @@ void cbm_doclink_cs_test_unit_memo(bool on);
* names but can move what those lines hold, so an incremental run
* re-resolves such documents with the edited file. */
bool cbm_doclinks_binds_lines(CBMLanguage lang);
+extern const cbm_doclink_resolver_t cbm_doclink_go_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_go.c b/src/pipeline/doc_links_go.c
new file mode 100644
index 000000000..047a7654e
--- /dev/null
+++ b/src/pipeline/doc_links_go.c
@@ -0,0 +1,1905 @@
+/*
+ * doc_links_go.c — Go doc-link resolution for doc_links.h.
+ *
+ * Extraction (internal/cbm/doclink_go.c) emits every bracketed text of a doc
+ * comment that go/doc/comment COULD take for a doc link. This file makes the
+ * rest of go/doc's decision, which needs the whole package, and then binds:
+ *
+ * [Name], [Recv.Name] the documented file's package. A name the
+ * package does not declare is plain text for
+ * go/doc: CBM_DOCLINK_LOCAL, neither edge nor row.
+ * So is the documented declaration's own type
+ * parameter. Recv.Name is a method declared with
+ * that receiver, a method of that interface, or
+ * a field of that struct (the field is a
+ * deliberate difference from go/doc: see
+ * go_bind_member).
+ * [pkg], [pkg.Name], pkg with a '/' is an import path. Otherwise, in
+ * [pkg.Recv.Name] order: the documented FILE's import of that
+ * name; the package's own name; a standard-library
+ * package with that one-element path. None of
+ * them: plain text (see go_lookup_qualifier for
+ * the one place this is stricter than go/doc).
+ * import path a module of the repository (every go.mod, the
+ * longest module path first) -> its directory's
+ * package; no package there: missing. No module:
+ * external. An import without a name is called by
+ * the real package name of an in-repo directory,
+ * else by go/doc's assumed name.
+ * member through an alias `type X = pkg.Y`: [p.X.Member] is looked up on Y.
+ *
+ * The members of a type are the methods declared with that receiver, the
+ * fields of its own struct declaration and the methods of its own interface
+ * declaration: nothing promoted through embedding.
+ *
+ * Binding. The graph keeps one node per qualified name, Go method nodes have
+ * a FLAT name (<dir>.<Method>), and <dir> is the directory, not the package
+ * clause: functions, methods of every receiver, types and values of one name,
+ * in every file of the directory, share one node, and the node is ONE of those
+ * declarations (cbm_gbuf_upsert_node keeps the smallest file path, then the
+ * last line). So a reference binds only when the node IS the entity it names:
+ * the node's file is a file of the named package, the declaration that keeps
+ * the name in that file (the w field of its scope record) is the named entity
+ * (its kind; for a method, its receiver), and the node has that kind's label.
+ * Every other declared entity is a graph_gap. A receiver-qualified method node
+ * (<dir>.<Recv>.<Method>) is tried first, so a graph that names methods that
+ * way binds them all. Only a node's qualified name, label and file_path are
+ * read: the proxy nodes of an incremental run carry no lines and no
+ * properties (the one exception is the SOURCE node, see go_source_owns_node).
+ *
+ * One name, several declarations. Files whose build constraints exclude each
+ * other declare variants of ONE entity, and any of them may hold the node. Two
+ * files built unconditionally that declare the same name are no package (a
+ * directory of stand-alone programs, test data): two entities share the name.
+ * Such a name binds only from a file that declares it itself, to that file's
+ * own declaration; from anywhere else it is ambiguous. A node kept by a test
+ * file is no target for product code.
+ *
+ * Reasons: external (standard library, module dependencies, vendored or
+ * not), missing (a repository package that does not declare the name; an
+ * import path inside a module without a package there), graph_gap (declared,
+ * but the node is another declaration's or absent: block variables, later
+ * names of a declaration, embedded fields, methods that lost the flat name;
+ * also an undeclared name in a package with a parse error), test_only_target
+ * (product code naming a declaration that only test files have), ambiguous
+ * (several modules or packages fit; a name declared as two kinds; a name two
+ * unconstrained files declare),
+ * unparseable (a reference longer than CBM_DOCLINK_GO_REF_MAX, an import path
+ * the scan could not record, an alias chain longer than GO_ALIAS_DEPTH).
+ */
+#include "pipeline/doc_links.h"
+
+#include "cbm.h"
+#include "doclink.h"
+#include "helpers.h" /* cbm_fqn_module_source_lang, cbm_is_test_file */
+#include "foundation/arena.h"
+#include "foundation/constants.h"
+#include "foundation/hash_table.h"
+#include "foundation/log.h"
+#include "foundation/mem_core.h"
+#include "graph_buffer/graph_buffer.h"
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+enum {
+ GO_KEY_BUF = 2304, /* id + type + name, or id + an import path */
+ GO_STACK_BUF = 1024, /* paths and qualified names shorter than this need no heap */
+ GO_MAX_FIELDS = 6, /* one more than the fields of the longest scope record */
+ GO_ALIAS_DEPTH = 8, /* alias-of-alias hops followed */
+ GO_KEY_SEP = 0x1F, /* between the parts of a composite key */
+ GO_NAME_MAX = CBM_DOCLINK_GO_REF_MAX,
+ GO_PATH_MAX = 1024, /* longest import or module path a scope records */
+ GO_VERSION_MIN = 2, /* "v" + at least one digit */
+ GO_GO_PREFIX = 3, /* strlen("go-") */
+ GO_ASCII_END = 0x80,
+ GO_KIND_FUNC = 1, /* what a name is in a package (go_sym_t) or a file (go_flat_t) */
+ GO_KIND_TYPE = 2,
+ GO_KIND_VALUE = 4,
+ GO_KIND_METHOD = 8, /* go_flat_t only: a method keeps the file's flat node name */
+ GO_MEM_METHOD = 1, /* what Type.Name is in a package (go_mem_t) or a file (go_fmem_t) */
+ GO_MEM_FIELD = 2,
+ GO_MEM_IFACE = 4,
+};
+
+/* ── Index data ──────────────────────────────────────────────────── */
+
+typedef struct {
+ const char *local; /* the qualifier this import gives the file */
+ const char *path; /* "?": the scan could not record it */
+ bool conflict; /* the file has two imports called `local` */
+} go_import_t;
+
+typedef struct {
+ uint32_t line; /* first line of the generic declaration */
+ uint32_t last; /* ... and its last */
+ const char *names; /* ','-joined type parameters */
+} go_generic_t;
+
+struct go_pkg;
+
+typedef struct go_dir {
+ int idx;
+ const char *path; /* "" for the repository root */
+ const char *qn; /* <project>.<path segments>: the prefix of its nodes */
+ struct go_pkg **pkgs;
+ int npkgs;
+ int pkgs_cap;
+ bool has_module; /* a go.mod sits here */
+ bool is_std; /* ... and it says `module std` */
+ const struct go_dir *module_root; /* the nearest directory at or above with a go.mod */
+} go_dir_t;
+
+typedef struct go_pkg {
+ int idx;
+ const go_dir_t *dir;
+ const char *name;
+ bool importable; /* has a file that is neither *_test.go nor build-ignored */
+ bool has_prod; /* has a file that is not test code */
+ bool incomplete; /* a file of it has a parse error: declarations may hide */
+} go_pkg_t;
+
+typedef struct {
+ int idx;
+ const char *rel_path; /* borrowed: valid until destroy */
+ const char *scope; /* borrowed: read while the index is built */
+ go_dir_t *dir;
+ go_pkg_t *pkg; /* NULL: no package clause, or a go.mod file */
+ bool is_test; /* test code by the indexer's rule: never a product target */
+ bool go_test; /* *_test.go: invisible to importers */
+ bool ignored; /* //go:build ignore: in no package */
+ bool constrained; /* built only under a constraint (a build line, or its name) */
+ go_import_t *imports;
+ int nimports;
+ int imports_cap;
+ go_generic_t *generics; /* fresh scopes only */
+ int ngenerics;
+ int generics_cap;
+} go_file_t;
+
+typedef struct {
+ const char *path;
+ const go_dir_t *dir;
+} go_module_t;
+
+/* A standard-library package of a `module std` tree in the repository. */
+typedef struct {
+ const go_dir_t *dir;
+ int count; /* trees that have it */
+} go_stdpkg_t;
+
+/* How many files that are built unconditionally declare one name. A package
+ * that compiles has at most one: two declarations of a name can only live in
+ * files whose build constraints exclude each other, and those are variants of
+ * ONE entity. Two unconstrained files that declare the same name are no
+ * package at all (a directory of stand-alone programs, test data): their
+ * declarations are different entities that share a name. */
+typedef struct {
+ const go_file_t *last; /* the unconstrained file counted last */
+ int files; /* 0, 1, or GO_TWINS for two and more */
+} go_free_t;
+
+enum { GO_TWINS = 2 };
+
+/* A package-level name. */
+typedef struct {
+ int kinds; /* GO_KIND_* of its declarations */
+ bool prod; /* declared by product code */
+ const char *alias; /* every declaration is `type X = alias`, else NULL */
+ const go_file_t *alias_file; /* the file whose imports name the alias target's package */
+ bool alias_mixed;
+ go_free_t free;
+} go_sym_t;
+
+/* Type.Name in a package. */
+typedef struct {
+ int kinds; /* GO_MEM_* */
+ bool prod;
+ go_free_t free;
+} go_mem_t;
+
+/* What ONE FILE declares under the flat node name <dir>.<name>, and which of
+ * its declarations keeps that name (the w field of its scope records): the
+ * file's last declaration of that name. */
+typedef struct {
+ int kinds; /* GO_KIND_* the file declares under that name */
+ int owner; /* the GO_KIND_* that keeps the name; 0: none */
+ const char *method_recv; /* owner GO_KIND_METHOD: that method's receiver */
+ bool contested; /* two declarations of that name start on the last line */
+} go_flat_t;
+
+/* What ONE FILE declares under <dir>.<type>.<name>. */
+typedef struct {
+ int kinds; /* GO_MEM_* it declares */
+ int node_kinds; /* ... and which of them get a node (not every field does) */
+} go_fmem_t;
+
+typedef struct {
+ CBMArena arena;
+ bool oom;
+ const char *project;
+ go_file_t *files;
+ int nfiles;
+ go_file_t **run_to_file;
+ int run_count;
+ go_dir_t **dirs;
+ int ndirs;
+ int dirs_cap;
+ int npkgs;
+ go_module_t *modules; /* sorted by (path, directory) */
+ int nmodules;
+ int modules_cap;
+ int nstd;
+ CBMHashTable *dir_by_path; /* path -> go_dir_t */
+ CBMHashTable *pkg_by_key; /* dir SEP name -> go_pkg_t */
+ CBMHashTable *file_by_path; /* rel_path -> go_file_t */
+ CBMHashTable *module_first; /* module path -> the first go_module_t of that path */
+ CBMHashTable *module_at; /* dir SEP module path -> go_module_t */
+ CBMHashTable *std_pkgs; /* path below a `module std` root -> go_stdpkg_t */
+ CBMHashTable *syms; /* pkg SEP name -> go_sym_t */
+ CBMHashTable *mems; /* pkg SEP type SEP name -> go_mem_t */
+ CBMHashTable *flat; /* file SEP name -> go_flat_t */
+ CBMHashTable *fmem; /* file SEP type SEP name -> go_fmem_t */
+} go_index_t;
+
+/* ── Small helpers ───────────────────────────────────────────────── */
+
+static void *ix_alloc(go_index_t *ix, size_t n) {
+ void *p = cbm_arena_alloc(&ix->arena, n ? n : SKIP_ONE);
+ ix->oom = ix->oom || !p;
+ return p;
+}
+
+static char *ix_strndup(go_index_t *ix, const char *s, size_t n) {
+ char *p = cbm_arena_strndup(&ix->arena, s, n);
+ ix->oom = ix->oom || !p;
+ return p;
+}
+
+/* Room for one more element of an index array; NULL when memory ran out. */
+static void *ix_grow(go_index_t *ix, void *items, int count, int *cap, size_t elem) {
+ if (count < *cap) {
+ return items;
+ }
+ int ncap = *cap ? *cap * PAIR_LEN : CBM_SZ_8;
+ void *grown = ix_alloc(ix, (size_t)ncap * elem);
+ if (!grown) {
+ return NULL;
+ }
+ if (count > 0) {
+ memcpy(grown, items, (size_t)count * elem);
+ }
+ *cap = ncap;
+ return grown;
+}
+
+/* A slice of text. */
+typedef struct {
+ const char *s;
+ size_t n;
+} go_str_t;
+
+static const go_str_t GO_NO_STR = {NULL, 0};
+
+static go_str_t go_str(const char *s) {
+ return (go_str_t){s, s ? strlen(s) : 0};
+}
+
+static bool go_str_eq(go_str_t a, const char *b) {
+ return strlen(b) == a.n && memcmp(a.s, b, a.n) == 0;
+}
+
+/* A text buffer that lives on the stack unless the text is long. */
+typedef struct {
+ char stack[GO_STACK_BUF];
+ char *heap;
+} go_buf_t;
+
+/* At least `need` bytes; NULL when memory ran out. Released with go_buf_free. */
+static char *go_buf_get(go_buf_t *b, size_t need) {
+ b->heap = NULL;
+ if (need <= sizeof(b->stack)) {
+ return b->stack;
+ }
+ b->heap = (char *)cbm_alloc(CBM_MEM_CLASS_OTHER, need);
+ return b->heap;
+}
+
+static void go_buf_free(go_buf_t *b) {
+ cbm_free(CBM_MEM_CLASS_OTHER, b->heap);
+ b->heap = NULL;
+}
+
+/* "<id> SEP a [SEP b]" into buf; false when it does not fit (the parts are
+ * names and paths a scope records, which are bounded). */
+static bool go_key(char *buf, size_t cap, int id, go_str_t a, go_str_t b) {
+ int n = snprintf(buf, cap, "%d%c", id, GO_KEY_SEP);
+ if (n < 0 || (size_t)n + a.n + b.n + PAIR_LEN >= cap) {
+ return false;
+ }
+ size_t w = (size_t)n;
+ memcpy(buf + w, a.s, a.n);
+ w += a.n;
+ if (b.s) {
+ buf[w++] = GO_KEY_SEP;
+ memcpy(buf + w, b.s, b.n);
+ w += b.n;
+ }
+ buf[w] = '\0';
+ return true;
+}
+
+/* The value stored under `key`, or a new zeroed one of `size` bytes. */
+static void *ix_entry(go_index_t *ix, CBMHashTable *ht, const char *key, size_t size) {
+ void *v = cbm_ht_get(ht, key);
+ if (v) {
+ return v;
+ }
+ v = ix_alloc(ix, size);
+ char *k = ix_strndup(ix, key, strlen(key));
+ if (!v || !k) {
+ return NULL;
+ }
+ memset(v, 0, size);
+ cbm_ht_set(ht, k, v);
+ return v;
+}
+
+/* The entry of a composite key, created when absent; NULL when the key does
+ * not fit or memory ran out. */
+static void *ix_keyed(go_index_t *ix, CBMHashTable *ht, int id, go_str_t a, go_str_t b,
+ size_t size) {
+ char key[GO_KEY_BUF];
+ return go_key(key, sizeof(key), id, a, b) ? ix_entry(ix, ht, key, size) : NULL;
+}
+
+static const void *go_lookup(const CBMHashTable *ht, int id, go_str_t a, go_str_t b) {
+ char key[GO_KEY_BUF];
+ return go_key(key, sizeof(key), id, a, b) ? cbm_ht_get(ht, key) : NULL;
+}
+
+/* The value stored under the text s[0..n). */
+static void *go_lookup_text(const CBMHashTable *ht, const char *s, size_t n) {
+ go_buf_t b;
+ char *key = go_buf_get(&b, n + SKIP_ONE);
+ if (!key) {
+ return NULL;
+ }
+ memcpy(key, s, n);
+ key[n] = '\0';
+ void *hit = cbm_ht_get(ht, key);
+ go_buf_free(&b);
+ return hit;
+}
+
+static bool go_has_suffix(const char *s, const char *suffix) {
+ size_t n = strlen(s);
+ size_t sl = strlen(suffix);
+ return n >= sl && memcmp(s + n - sl, suffix, sl) == 0;
+}
+
+static bool go_has_non_ascii(go_str_t s) {
+ for (size_t i = 0; i < s.n; i++) {
+ if ((unsigned char)s.s[i] >= GO_ASCII_END) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/* ── Directories and packages ────────────────────────────────────── */
+
+static go_dir_t *go_dir_find(const go_index_t *ix, const char *path, size_t len) {
+ return (go_dir_t *)go_lookup_text(ix->dir_by_path, path, len);
+}
+
+static go_dir_t *go_dir_get(go_index_t *ix, const char *path, size_t len, const char *rel_path) {
+ go_dir_t *d = go_dir_find(ix, path, len);
+ if (d) {
+ return d;
+ }
+ go_dir_t **grown =
+ (go_dir_t **)ix_grow(ix, ix->dirs, ix->ndirs, &ix->dirs_cap, sizeof(go_dir_t *));
+ d = (go_dir_t *)ix_alloc(ix, sizeof(*d));
+ char *own = ix_strndup(ix, path, len);
+ if (!grown || !d || !own) {
+ return NULL;
+ }
+ memset(d, 0, sizeof(*d));
+ d->idx = ix->ndirs;
+ d->path = own;
+ /* The same helper that names the directory's definitions. */
+ d->qn = cbm_fqn_module_source_lang(&ix->arena, ix->project, rel_path, CBM_LANG_GO);
+ ix->oom = ix->oom || !d->qn;
+ ix->dirs = grown;
+ ix->dirs[ix->ndirs++] = d;
+ cbm_ht_set(ix->dir_by_path, own, d);
+ return d;
+}
+
+static go_pkg_t *go_pkg_get(go_index_t *ix, go_dir_t *dir, go_str_t name) {
+ char key[GO_KEY_BUF];
+ if (!go_key(key, sizeof(key), dir->idx, name, GO_NO_STR)) {
+ return NULL;
+ }
+ go_pkg_t *p = (go_pkg_t *)cbm_ht_get(ix->pkg_by_key, key);
+ if (p) {
+ return p;
+ }
+ go_pkg_t **dir_pkgs =
+ (go_pkg_t **)ix_grow(ix, dir->pkgs, dir->npkgs, &dir->pkgs_cap, sizeof(go_pkg_t *));
+ p = (go_pkg_t *)ix_alloc(ix, sizeof(*p));
+ char *own_key = ix_strndup(ix, key, strlen(key));
+ char *own_name = ix_strndup(ix, name.s, name.n);
+ if (!dir_pkgs || !p || !own_key || !own_name) {
+ return NULL;
+ }
+ memset(p, 0, sizeof(*p));
+ p->idx = ix->npkgs++;
+ p->dir = dir;
+ p->name = own_name;
+ dir->pkgs = dir_pkgs;
+ dir->pkgs[dir->npkgs++] = p;
+ cbm_ht_set(ix->pkg_by_key, own_key, p);
+ return p;
+}
+
+/* ── Scope records ───────────────────────────────────────────────── */
+
+/* Split a scope line (a copy the caller owns) at its tabs. */
+static int go_fields(char *line, char **out, int max) {
+ int n = 0;
+ out[n++] = line;
+ for (char *p = line; *p && n < max; p++) {
+ if (*p == '\t') {
+ *p = '\0';
+ out[n++] = p + SKIP_ONE;
+ }
+ }
+ return n;
+}
+
+/* A name field as a scan writes it: not empty, not longer than a name. */
+static bool go_name_ok(const char *s) {
+ size_t n = strlen(s);
+ return n > 0 && n <= GO_NAME_MAX;
+}
+
+static bool go_path_ok(const char *s) {
+ size_t n = strlen(s);
+ return n > 0 && n <= GO_PATH_MAX;
+}
+
+typedef void (*go_record_fn)(go_index_t *ix, go_file_t *file, char **f, int nf);
+
+/* Calls `fn` for every record line of a scope blob (the tag line is skipped);
+ * each line is handed over split into its fields. False when memory ran out. */
+static bool go_each_record(go_index_t *ix, go_file_t *file, const char *blob, go_record_fn fn) {
+ const char *p = strchr(blob, '\n');
+ while (p && p[SKIP_ONE]) {
+ p++;
+ const char *nl = strchr(p, '\n');
+ size_t len = nl ? (size_t)(nl - p) : strlen(p);
+ go_buf_t b;
+ char *line = go_buf_get(&b, len + SKIP_ONE);
+ if (!line) {
+ ix->oom = true;
+ return false;
+ }
+ memcpy(line, p, len);
+ line[len] = '\0';
+ char *f[GO_MAX_FIELDS];
+ int nf = go_fields(line, f, GO_MAX_FIELDS);
+ if (f[0][0] && !f[0][SKIP_ONE]) {
+ fn(ix, file, f, nf);
+ }
+ go_buf_free(&b);
+ p = nl;
+ }
+ return !ix->oom;
+}
+
+static void go_add_module(go_index_t *ix, go_file_t *file, const char *path) {
+ file->dir->has_module = true;
+ if (strcmp(path, "std") == 0) {
+ /* the standard library's own module: its packages are imported by
+ * their bare directory path */
+ file->dir->is_std = true;
+ ix->nstd++;
+ return;
+ }
+ go_module_t *grown = (go_module_t *)ix_grow(ix, ix->modules, ix->nmodules, &ix->modules_cap,
+ sizeof(go_module_t));
+ char *own = ix_strndup(ix, path, strlen(path));
+ if (!grown || !own) {
+ return;
+ }
+ ix->modules = grown;
+ ix->modules[ix->nmodules++] = (go_module_t){.path = own, .dir = file->dir};
+}
+
+static void go_add_import(go_index_t *ix, go_file_t *f, const char *local, const char *path) {
+ go_import_t *grown =
+ (go_import_t *)ix_grow(ix, f->imports, f->nimports, &f->imports_cap, sizeof(go_import_t));
+ char *own_path = ix_strndup(ix, path, strlen(path));
+ /* "-": not renamed; the name is derived once every package is known */
+ char *own_local = strcmp(local, "-") == 0 ? NULL : ix_strndup(ix, local, strlen(local));
+ if (!grown || !own_path || ix->oom) {
+ return;
+ }
+ f->imports = grown;
+ f->imports[f->nimports++] = (go_import_t){.local = own_local, .path = own_path};
+}
+
+/* A line number field of a scope record; false when it is none. */
+static bool go_line_field(const char *s, uint32_t *out) {
+ char *end = NULL;
+ unsigned long long value = strtoull(s, &end, CBM_DECIMAL_BASE);
+ if (end == s || *end != '\0' || value > UINT32_MAX) {
+ return false;
+ }
+ *out = (uint32_t)value;
+ return true;
+}
+
+/* `g first last names`. */
+static void go_add_generic(go_index_t *ix, go_file_t *f, const char *first, const char *last,
+ const char *names) {
+ go_generic_t g = {.names = ix_strndup(ix, names, strlen(names))};
+ go_generic_t *grown = (go_generic_t *)ix_grow(ix, f->generics, f->ngenerics, &f->generics_cap,
+ sizeof(go_generic_t));
+ if (!grown || !g.names || !go_line_field(first, &g.line) || !go_line_field(last, &g.last)) {
+ return;
+ }
+ f->generics = grown;
+ f->generics[f->ngenerics++] = g;
+}
+
+static bool go_word_in(go_str_t word, const char *const *list, size_t count) {
+ for (size_t i = 0; i < count; i++) {
+ if (go_str_eq(word, list[i])) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/* go/build goodOSArchFile: a file named *_GOOS.go, *_GOARCH.go or
+ * *_GOOS_GOARCH.go (before an optional _test) is built only for that target.
+ * The two lists are the toolchain's own closed lists (go/build syslist); a
+ * name they do not know leaves the file unconstrained, which can only make
+ * this resolver more careful (see go_free_t). */
+static bool go_name_constrained(const char *rel_path) {
+ static const char *const known_os[] = {
+ "aix", "android", "darwin", "dragonfly", "freebsd", "hurd",
+ "illumos", "ios", "js", "linux", "nacl", "netbsd",
+ "openbsd", "plan9", "solaris", "wasip1", "windows", "zos",
+ };
+ static const char *const known_arch[] = {
+ "386", "amd64", "amd64p32", "arm", "armbe", "arm64",
+ "arm64be", "loong64", "mips", "mipsle", "mips64", "mips64le",
+ "mips64p32", "mips64p32le", "ppc", "ppc64", "ppc64le", "riscv",
+ "riscv64", "s390", "s390x", "sparc", "sparc64", "wasm",
+ };
+ static const char ext[] = ".go";
+ static const char test[] = "_test";
+ const char *slash = strrchr(rel_path, '/');
+ go_str_t base = go_str(slash ? slash + SKIP_ONE : rel_path);
+ if (base.n >= sizeof(ext) - SKIP_ONE && go_has_suffix(base.s, ext)) {
+ base.n -= sizeof(ext) - SKIP_ONE;
+ }
+ size_t tl = sizeof(test) - SKIP_ONE;
+ if (base.n >= tl && memcmp(base.s + base.n - tl, test, tl) == 0) {
+ base.n -= tl;
+ }
+ size_t last = base.n;
+ while (last > 0 && base.s[last - SKIP_ONE] != '_') {
+ last--;
+ }
+ if (last == 0) {
+ return false; /* no underscore: `linux.go` is an ordinary file */
+ }
+ go_str_t tag = {base.s + last, base.n - last};
+ return go_word_in(tag, known_os, sizeof(known_os) / sizeof(known_os[0])) ||
+ go_word_in(tag, known_arch, sizeof(known_arch) / sizeof(known_arch[0]));
+}
+
+static void go_set_package(go_index_t *ix, go_file_t *f, const char *name, const char *flags) {
+ if (f->pkg) {
+ return;
+ }
+ f->ignored = strchr(flags, 'i') != NULL;
+ f->constrained = strchr(flags, 'c') != NULL || go_name_constrained(f->rel_path);
+ f->pkg = go_pkg_get(ix, f->dir, go_str(name));
+ if (!f->pkg) {
+ ix->oom = true;
+ return;
+ }
+ go_pkg_t *p = f->pkg;
+ p->importable = p->importable || (!f->go_test && !f->ignored);
+ p->has_prod = p->has_prod || (!f->is_test && !f->ignored);
+ p->incomplete = p->incomplete || strchr(flags, 'e') != NULL;
+}
+
+/* First pass over a file's scope: package, module, imports, generics. */
+static void go_record_head(go_index_t *ix, go_file_t *file, char **f, int nf) {
+ enum { P_FIELDS = 3, I_FIELDS = 3, G_FIELDS = 2, GEN_FIELDS = 4, GEN_NAMES = 3 };
+ char kind = f[0][0];
+ if (kind == 'P' && nf == P_FIELDS && go_name_ok(f[SKIP_ONE])) {
+ go_set_package(ix, file, f[SKIP_ONE], f[PAIR_LEN]);
+ } else if (kind == 'G' && nf == G_FIELDS && go_path_ok(f[SKIP_ONE])) {
+ go_add_module(ix, file, f[SKIP_ONE]);
+ } else if (kind == 'I' && nf == I_FIELDS && go_name_ok(f[SKIP_ONE]) &&
+ go_path_ok(f[PAIR_LEN])) {
+ go_add_import(ix, file, f[SKIP_ONE], f[PAIR_LEN]);
+ } else if (kind == 'g' && nf == GEN_FIELDS) {
+ go_add_generic(ix, file, f[SKIP_ONE], f[PAIR_LEN], f[GEN_NAMES]);
+ }
+}
+
+/* ── Modules ─────────────────────────────────────────────────────── */
+
+static int go_module_cmp(const void *a, const void *b) {
+ const go_module_t *x = (const go_module_t *)a;
+ const go_module_t *y = (const go_module_t *)b;
+ int c = strcmp(x->path, y->path);
+ return c ? c : strcmp(x->dir->path, y->dir->path);
+}
+
+/* Sort the modules; index the first entry of every module path, and every
+ * (directory, module path) pair. */
+static void go_finish_modules(go_index_t *ix) {
+ if (ix->nmodules > SKIP_ONE) {
+ qsort(ix->modules, (size_t)ix->nmodules, sizeof(ix->modules[0]), go_module_cmp);
+ }
+ for (int i = 0; i < ix->nmodules; i++) {
+ go_module_t *m = &ix->modules[i];
+ if (i == 0 || strcmp(m->path, ix->modules[i - SKIP_ONE].path) != 0) {
+ cbm_ht_set(ix->module_first, m->path, m);
+ }
+ char key[GO_KEY_BUF];
+ char *own = go_key(key, sizeof(key), m->dir->idx, go_str(m->path), GO_NO_STR)
+ ? ix_strndup(ix, key, strlen(key))
+ : NULL;
+ if (own) {
+ cbm_ht_set(ix->module_at, own, m);
+ }
+ }
+}
+
+/* The nearest directory at or above `d` that holds a go.mod. */
+static const go_dir_t *go_module_root(const go_index_t *ix, const go_dir_t *d) {
+ size_t len = strlen(d->path);
+ for (;;) {
+ const go_dir_t *up = go_dir_find(ix, d->path, len);
+ if (up && up->has_module) {
+ return up;
+ }
+ if (len == 0) {
+ return NULL;
+ }
+ while (len > 0 && d->path[len - SKIP_ONE] != '/') {
+ len--;
+ }
+ if (len > 0) {
+ len--; /* the slash */
+ }
+ }
+}
+
+/* Give every directory its module root, and list the packages of the
+ * repository's `module std` trees under their bare import paths. */
+static void go_finish_dirs(go_index_t *ix) {
+ for (int i = 0; i < ix->ndirs; i++) {
+ go_dir_t *d = ix->dirs[i];
+ d->module_root = go_module_root(ix, d);
+ const go_dir_t *root = d->module_root;
+ if (!root || !root->is_std || root == d || d->npkgs == 0) {
+ continue;
+ }
+ size_t rl = strlen(root->path);
+ const char *rel = d->path + rl + (rl > 0 ? SKIP_ONE : 0);
+ go_stdpkg_t *sp = (go_stdpkg_t *)ix_entry(ix, ix->std_pkgs, rel, sizeof(go_stdpkg_t));
+ if (sp) {
+ sp->dir = sp->count == 0 ? d : sp->dir;
+ sp->count++;
+ }
+ }
+}
+
+/* ── Import paths ────────────────────────────────────────────────── */
+
+typedef enum {
+ GO_PATH_EXTERNAL = 0, /* no module of the repository holds it */
+ GO_PATH_PACKAGE, /* a directory of the repository with Go files */
+ GO_PATH_NO_PACKAGE, /* inside a module, but no Go package there */
+ GO_PATH_AMBIGUOUS, /* several modules of that path, none of them the file's own */
+ GO_PATH_UNKNOWN, /* not decidable: an import the scan could not record, no memory */
+} go_path_kind_t;
+
+/* `<root>/<rest>` when it is a directory of the repository with Go files that
+ * belongs to the module rooted at `root` (no nested go.mod on the way). */
+static go_path_kind_t go_module_pkg_dir(const go_index_t *ix, const go_dir_t *root, go_str_t rest,
+ const go_dir_t **dir_out) {
+ size_t rl = strlen(root->path);
+ go_buf_t b;
+ char *buf = go_buf_get(&b, rl + rest.n + PAIR_LEN);
+ if (!buf) {
+ return GO_PATH_UNKNOWN;
+ }
+ size_t w = rl;
+ memcpy(buf, root->path, rl);
+ if (rest.n > 0) {
+ if (w > 0) {
+ buf[w++] = '/';
+ }
+ memcpy(buf + w, rest.s, rest.n);
+ w += rest.n;
+ }
+ const go_dir_t *dir = go_dir_find(ix, buf, w);
+ go_buf_free(&b);
+ if (!dir || dir->npkgs == 0 || dir->module_root != root) {
+ return GO_PATH_NO_PACKAGE;
+ }
+ *dir_out = dir;
+ return GO_PATH_PACKAGE;
+}
+
+/* The module a module path means for file `src`: the only module of that
+ * path, else the one the file itself lives in. NULL: nothing picks one. */
+static const go_module_t *go_pick_module(const go_index_t *ix, const go_module_t *first,
+ const go_file_t *src) {
+ const go_module_t *next = first + SKIP_ONE;
+ if (next >= ix->modules + ix->nmodules || strcmp(next->path, first->path) != 0) {
+ return first;
+ }
+ const go_dir_t *own = src ? src->dir->module_root : NULL;
+ return own ? (const go_module_t *)go_lookup(ix->module_at, own->idx, go_str(first->path),
+ GO_NO_STR)
+ : NULL;
+}
+
+/* A path no module prefixes: a package of the repository's own standard
+ * library, when it has one. */
+static go_path_kind_t go_classify_std(const go_index_t *ix, const go_file_t *src, go_str_t path,
+ const go_dir_t **dir_out) {
+ if (ix->nstd == 0) {
+ return GO_PATH_EXTERNAL;
+ }
+ const go_stdpkg_t *sp = (const go_stdpkg_t *)go_lookup_text(ix->std_pkgs, path.s, path.n);
+ if (!sp) {
+ return GO_PATH_EXTERNAL;
+ }
+ if (sp->count == SKIP_ONE) {
+ *dir_out = sp->dir;
+ return GO_PATH_PACKAGE;
+ }
+ const go_dir_t *own = src ? src->dir->module_root : NULL;
+ if (own && own->is_std && go_module_pkg_dir(ix, own, path, dir_out) == GO_PATH_PACKAGE) {
+ return GO_PATH_PACKAGE;
+ }
+ return GO_PATH_AMBIGUOUS;
+}
+
+/* Where an import path leads: the longest module path of the repository that
+ * prefixes it decides. */
+static go_path_kind_t go_classify_path(const go_index_t *ix, const go_file_t *src, go_str_t path,
+ const go_dir_t **dir_out) {
+ if (path.n == 0 || go_str_eq(path, "?")) {
+ return GO_PATH_UNKNOWN;
+ }
+ go_buf_t b;
+ char *buf = go_buf_get(&b, path.n + SKIP_ONE);
+ if (!buf) {
+ return GO_PATH_UNKNOWN;
+ }
+ memcpy(buf, path.s, path.n);
+ buf[path.n] = '\0';
+ const go_module_t *first = NULL;
+ size_t cut = path.n;
+ for (; cut > 0 && !first; cut--) {
+ if (cut != path.n && buf[cut] != '/') {
+ continue;
+ }
+ char saved = buf[cut];
+ buf[cut] = '\0';
+ first = (const go_module_t *)cbm_ht_get(ix->module_first, buf);
+ buf[cut] = saved;
+ }
+ go_buf_free(&b);
+ if (!first) {
+ return go_classify_std(ix, src, path, dir_out);
+ }
+ const go_module_t *m = go_pick_module(ix, first, src);
+ if (!m) {
+ return GO_PATH_AMBIGUOUS;
+ }
+ size_t used = strlen(m->path);
+ go_str_t rest = {path.s + used, path.n - used};
+ if (rest.n > 0) {
+ rest.s++; /* the slash after the module path */
+ rest.n--;
+ }
+ return go_module_pkg_dir(ix, m->dir, rest, dir_out);
+}
+
+/* The package an import path means in `dir`: its only importable package. With
+ * several, the one called `hint` (the qualifier, or the path's last element).
+ * NULL for none; *ambiguous when several fit and nothing picks one. */
+static const go_pkg_t *go_dir_package(const go_dir_t *dir, go_str_t hint, bool *ambiguous) {
+ const go_pkg_t *only = NULL;
+ const go_pkg_t *named = NULL;
+ int count = 0;
+ for (int i = 0; i < dir->npkgs; i++) {
+ const go_pkg_t *p = dir->pkgs[i];
+ if (!p->importable) {
+ continue;
+ }
+ count++;
+ only = p;
+ if (hint.s && go_str_eq(hint, p->name)) {
+ named = p;
+ }
+ }
+ *ambiguous = count > SKIP_ONE && !named;
+ return count > SKIP_ONE ? named : only;
+}
+
+static bool go_name_byte(unsigned char c) {
+ return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '_' ||
+ c >= GO_ASCII_END;
+}
+
+/* The last element of a slash-separated path. */
+static go_str_t go_path_base(go_str_t path) {
+ size_t start = path.n;
+ while (start > 0 && path.s[start - SKIP_ONE] != '/') {
+ start--;
+ }
+ return (go_str_t){path.s + start, path.n - start};
+}
+
+/* go/doc assumedPackageName: the last path element; for a major-version
+ * element (`v2`) the one before it; without a `go-` prefix; cut at the first
+ * byte that cannot be in an identifier. */
+static go_str_t go_assumed_name(go_str_t path) {
+ go_str_t base = go_path_base(path);
+ bool version = base.n >= GO_VERSION_MIN && base.s[0] == 'v';
+ for (size_t i = SKIP_ONE; version && i < base.n; i++) {
+ version = base.s[i] >= '0' && base.s[i] <= '9';
+ }
+ if (version && base.n < path.n) {
+ base = go_path_base((go_str_t){path.s, path.n - base.n - SKIP_ONE});
+ }
+ if (base.n >= GO_GO_PREFIX && memcmp(base.s, "go-", GO_GO_PREFIX) == 0) {
+ base.s += GO_GO_PREFIX;
+ base.n -= GO_GO_PREFIX;
+ }
+ size_t n = 0;
+ while (n < base.n && go_name_byte((unsigned char)base.s[n])) {
+ n++;
+ }
+ return (go_str_t){base.s, n};
+}
+
+static int go_import_cmp(const void *a, const void *b) {
+ const go_import_t *x = (const go_import_t *)a;
+ const go_import_t *y = (const go_import_t *)b;
+ int c = strcmp(x->local, y->local);
+ return c ? c : strcmp(x->path, y->path);
+}
+
+static int go_generic_cmp(const void *a, const void *b) {
+ const go_generic_t *x = (const go_generic_t *)a;
+ const go_generic_t *y = (const go_generic_t *)b;
+ return (x->line > y->line) - (x->line < y->line);
+}
+
+/* The name an import without one is called by: the real package name of an
+ * in-repo directory, else go/doc's assumed name. */
+static go_str_t go_unnamed_import_name(const go_index_t *ix, const go_file_t *f,
+ const go_import_t *im) {
+ go_str_t path = go_str(im->path);
+ go_str_t name = go_assumed_name(path);
+ const go_dir_t *dir = NULL;
+ if (go_classify_path(ix, f, path, &dir) == GO_PATH_PACKAGE) {
+ bool ambiguous = false;
+ const go_pkg_t *pkg = go_dir_package(dir, name, &ambiguous);
+ if (pkg) {
+ return go_str(pkg->name);
+ }
+ }
+ return name;
+}
+
+/* Name the unnamed imports of a file, sort its imports by name and mark the
+ * names two different paths claim. Its type-parameter records are sorted by
+ * line on the way. */
+static void go_finish_file(go_index_t *ix, go_file_t *f) {
+ if (f->ngenerics > SKIP_ONE) {
+ qsort(f->generics, (size_t)f->ngenerics, sizeof(f->generics[0]), go_generic_cmp);
+ }
+ for (int i = 0; i < f->nimports; i++) {
+ go_import_t *im = &f->imports[i];
+ if (!im->local) {
+ go_str_t name = go_unnamed_import_name(ix, f, im);
+ im->local = ix_strndup(ix, name.s, name.n);
+ }
+ if (!im->local) {
+ f->nimports = 0;
+ return;
+ }
+ }
+ if (f->nimports > SKIP_ONE) {
+ qsort(f->imports, (size_t)f->nimports, sizeof(f->imports[0]), go_import_cmp);
+ }
+ int i = 0;
+ while (i < f->nimports) {
+ int end = i + SKIP_ONE; /* [i, end): the imports called alike, sorted by path */
+ while (end < f->nimports && strcmp(f->imports[end].local, f->imports[i].local) == 0) {
+ end++;
+ }
+ bool conflict = strcmp(f->imports[i].path, f->imports[end - SKIP_ONE].path) != 0;
+ for (int k = i; k < end; k++) {
+ f->imports[k].conflict = conflict;
+ }
+ i = end;
+ }
+}
+
+/* The file's import called `name`; NULL when it has none. */
+static const go_import_t *go_file_import(const go_file_t *f, go_str_t name) {
+ int lo = 0;
+ int hi = f->nimports - SKIP_ONE;
+ while (lo <= hi) {
+ int mid = lo + ((hi - lo) / PAIR_LEN);
+ const char *local = f->imports[mid].local;
+ size_t ll = strlen(local);
+ int c = memcmp(name.s, local, name.n < ll ? name.n : ll);
+ if (c == 0 && name.n != ll) {
+ c = name.n < ll ? -SKIP_ONE : SKIP_ONE;
+ }
+ if (c == 0) {
+ return &f->imports[mid];
+ }
+ if (c < 0) {
+ hi = mid - SKIP_ONE;
+ } else {
+ lo = mid + SKIP_ONE;
+ }
+ }
+ return NULL;
+}
+
+/* ── Declarations ────────────────────────────────────────────────── */
+
+/* Count file `f` as a declarer of one name when it is built unconditionally. A
+ * file's records are read in one run, so its declarations of one name arrive
+ * together. */
+static void go_count_free(go_free_t *fr, const go_file_t *f) {
+ if (f->constrained || fr->last == f) {
+ return;
+ }
+ fr->last = f;
+ if (fr->files < GO_TWINS) {
+ fr->files++;
+ }
+}
+
+static void go_add_sym(go_index_t *ix, go_file_t *f, int kind_bit, const char *name,
+ const char *alias) {
+ if (!f->pkg || f->ignored) {
+ return;
+ }
+ bool fresh = !go_lookup(ix->syms, f->pkg->idx, go_str(name), GO_NO_STR);
+ go_sym_t *s =
+ (go_sym_t *)ix_keyed(ix, ix->syms, f->pkg->idx, go_str(name), GO_NO_STR, sizeof(go_sym_t));
+ if (!s) {
+ return;
+ }
+ s->kinds |= kind_bit;
+ s->prod = s->prod || !f->is_test;
+ go_count_free(&s->free, f);
+ bool is_alias = alias && strcmp(alias, "-") != 0;
+ if (fresh && is_alias) {
+ s->alias = ix_strndup(ix, alias, strlen(alias));
+ s->alias_file = f;
+ } else if (!is_alias || !s->alias || strcmp(s->alias, alias) != 0) {
+ s->alias_mixed = true; /* declarations disagree: nothing to follow */
+ }
+}
+
+static void go_add_member(go_index_t *ix, go_file_t *f, int kind_bit, const char *type,
+ const char *name, bool has_node) {
+ go_fmem_t *fm =
+ (go_fmem_t *)ix_keyed(ix, ix->fmem, f->idx, go_str(type), go_str(name), sizeof(go_fmem_t));
+ if (fm) {
+ fm->kinds |= kind_bit;
+ fm->node_kinds |= has_node ? kind_bit : 0;
+ }
+ if (!f->pkg || f->ignored) {
+ return;
+ }
+ go_mem_t *m = (go_mem_t *)ix_keyed(ix, ix->mems, f->pkg->idx, go_str(type), go_str(name),
+ sizeof(go_mem_t));
+ if (m) {
+ m->kinds |= kind_bit;
+ m->prod = m->prod || !f->is_test;
+ go_count_free(&m->free, f);
+ }
+}
+
+/* Record that file `f` declares `name` as `kind`, and what the declaration's
+ * w field says: `1` it keeps the file's flat node name <dir>.<name>, `x` two
+ * declarations contest it, `0` a later one keeps it, `-` it has no node.
+ * `recv` is set for a method. */
+static void go_add_claim(go_index_t *ix, const go_file_t *f, int kind, const char *name,
+ const char *recv, const char *w) {
+ go_flat_t *fl =
+ (go_flat_t *)ix_keyed(ix, ix->flat, f->idx, go_str(name), GO_NO_STR, sizeof(go_flat_t));
+ if (!fl) {
+ return;
+ }
+ fl->kinds |= kind;
+ if (w[0] == 'x') {
+ fl->contested = true;
+ } else if (w[0] == '1') {
+ fl->owner = kind;
+ fl->method_recv = recv ? ix_strndup(ix, recv, strlen(recv)) : NULL;
+ }
+}
+
+/* Second pass over a file's scope: its declarations. */
+static void go_record_decl(go_index_t *ix, go_file_t *file, char **f, int nf) {
+ enum {
+ F_FIELDS = 3,
+ M_FIELDS = 4,
+ T_FIELDS = 5,
+ V_FIELDS = 3,
+ FIELD_FIELDS = 4,
+ IM_FIELDS = 3
+ };
+ enum { F_OWNER = 2, T_ALIAS = 3, T_OWNER = 4, V_OWNER = 2, M_OWNER = 3, FIELD_NODE = 3 };
+ char kind = f[0][0];
+ if (nf < IM_FIELDS || !go_name_ok(f[SKIP_ONE])) {
+ return;
+ }
+ if (kind == 'F' && nf == F_FIELDS) {
+ go_add_sym(ix, file, GO_KIND_FUNC, f[SKIP_ONE], NULL);
+ go_add_claim(ix, file, GO_KIND_FUNC, f[SKIP_ONE], NULL, f[F_OWNER]);
+ } else if (kind == 'T' && nf == T_FIELDS) {
+ go_add_sym(ix, file, GO_KIND_TYPE, f[SKIP_ONE], f[T_ALIAS]);
+ go_add_claim(ix, file, GO_KIND_TYPE, f[SKIP_ONE], NULL, f[T_OWNER]);
+ } else if (kind == 'V' && nf == V_FIELDS) {
+ go_add_sym(ix, file, GO_KIND_VALUE, f[SKIP_ONE], NULL);
+ go_add_claim(ix, file, GO_KIND_VALUE, f[SKIP_ONE], NULL, f[V_OWNER]);
+ } else if (kind == 'M' && nf == M_FIELDS && go_name_ok(f[PAIR_LEN])) {
+ if (strcmp(f[SKIP_ONE], "?") != 0) {
+ go_add_member(ix, file, GO_MEM_METHOD, f[SKIP_ONE], f[PAIR_LEN], true);
+ }
+ go_add_claim(ix, file, GO_KIND_METHOD, f[PAIR_LEN], f[SKIP_ONE], f[M_OWNER]);
+ } else if (kind == 'f' && nf == FIELD_FIELDS && go_name_ok(f[PAIR_LEN])) {
+ go_add_member(ix, file, GO_MEM_FIELD, f[SKIP_ONE], f[PAIR_LEN], f[FIELD_NODE][0] == '1');
+ } else if (kind == 'm' && nf == IM_FIELDS && go_name_ok(f[PAIR_LEN])) {
+ go_add_member(ix, file, GO_MEM_IFACE, f[SKIP_ONE], f[PAIR_LEN], true);
+ }
+}
+
+/* ── Index lifecycle ─────────────────────────────────────────────── */
+
+static void go_destroy(void *index) {
+ go_index_t *ix = (go_index_t *)index;
+ if (!ix) {
+ return;
+ }
+ cbm_ht_free(ix->dir_by_path);
+ cbm_ht_free(ix->pkg_by_key);
+ cbm_ht_free(ix->file_by_path);
+ cbm_ht_free(ix->module_first);
+ cbm_ht_free(ix->module_at);
+ cbm_ht_free(ix->std_pkgs);
+ cbm_ht_free(ix->syms);
+ cbm_ht_free(ix->mems);
+ cbm_ht_free(ix->flat);
+ cbm_ht_free(ix->fmem);
+ cbm_free(CBM_MEM_CLASS_OTHER, ix->run_to_file);
+ cbm_arena_destroy(&ix->arena);
+ cbm_free(CBM_MEM_CLASS_OTHER, ix);
+}
+
+static bool go_index_tables(go_index_t *ix, int file_count, int run_file_count) {
+ ix->dir_by_path = cbm_ht_create(CBM_SZ_1K);
+ ix->pkg_by_key = cbm_ht_create(CBM_SZ_1K);
+ ix->file_by_path = cbm_ht_create(CBM_SZ_4K);
+ ix->module_first = cbm_ht_create(CBM_SZ_64);
+ ix->module_at = cbm_ht_create(CBM_SZ_64);
+ ix->std_pkgs = cbm_ht_create(CBM_SZ_64);
+ ix->syms = cbm_ht_create(CBM_SZ_4K);
+ ix->mems = cbm_ht_create(CBM_SZ_4K);
+ ix->flat = cbm_ht_create(CBM_SZ_4K);
+ ix->fmem = cbm_ht_create(CBM_SZ_4K);
+ ix->nfiles = file_count;
+ ix->files =
+ (go_file_t *)ix_alloc(ix, (size_t)(file_count ? file_count : SKIP_ONE) * sizeof(go_file_t));
+ ix->run_count = run_file_count;
+ ix->run_to_file = (go_file_t **)cbm_calloc(
+ CBM_MEM_CLASS_OTHER,
+ (size_t)(run_file_count ? run_file_count : SKIP_ONE) * sizeof(go_file_t *));
+ return ix->dir_by_path && ix->pkg_by_key && ix->file_by_path && ix->module_first &&
+ ix->module_at && ix->std_pkgs && ix->syms && ix->mems && ix->flat && ix->fmem &&
+ ix->files && ix->run_to_file;
+}
+
+/* True for a file below a directory called `testdata`: the go tool ignores
+ * such directories, so what they hold is fixture data, never product code. */
+static bool go_in_testdata(const char *rel_path) {
+ static const char dir[] = "testdata";
+ const size_t dl = sizeof(dir) - SKIP_ONE;
+ for (const char *p = rel_path;;) {
+ const char *slash = strchr(p, '/');
+ if (!slash) {
+ return false; /* the last element is the file's name */
+ }
+ if ((size_t)(slash - p) == dl && memcmp(p, dir, dl) == 0) {
+ return true;
+ }
+ p = slash + SKIP_ONE;
+ }
+}
+
+/* File i of the index: its directory, its test flags, the head of its scope. */
+static bool go_index_file(go_index_t *ix, int i, const cbm_doclink_file_t *src) {
+ go_file_t *f = &ix->files[i];
+ memset(f, 0, sizeof(*f));
+ f->idx = i;
+ f->rel_path = src->rel_path;
+ f->scope = src->scope;
+ f->is_test = cbm_is_test_file(src->rel_path, CBM_LANG_GO) || go_in_testdata(src->rel_path);
+ f->go_test = go_has_suffix(src->rel_path, "_test.go");
+ const char *slash = strrchr(src->rel_path, '/');
+ f->dir =
+ go_dir_get(ix, src->rel_path, slash ? (size_t)(slash - src->rel_path) : 0, src->rel_path);
+ if (!f->dir) {
+ ix->oom = true;
+ return false;
+ }
+ cbm_ht_set(ix->file_by_path, f->rel_path, f);
+ if (src->run_file >= 0 && src->run_file < ix->run_count) {
+ ix->run_to_file[src->run_file] = f;
+ }
+ return !f->scope || go_each_record(ix, f, f->scope, go_record_head);
+}
+
+static void *go_build(const cbm_doclink_build_in_t *in) {
+ go_index_t *ix = (go_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;
+ bool ok = go_index_tables(ix, in->file_count, in->run_file_count);
+ for (int i = 0; ok && i < in->file_count; i++) {
+ ok = go_index_file(ix, i, &in->files[i]);
+ }
+ if (ok) {
+ go_finish_modules(ix);
+ go_finish_dirs(ix);
+ }
+ for (int i = 0; ok && i < ix->nfiles; i++) {
+ go_finish_file(ix, &ix->files[i]);
+ ok = !ix->oom;
+ }
+ for (int i = 0; ok && i < ix->nfiles; i++) {
+ go_file_t *f = &ix->files[i];
+ ok = !f->scope || go_each_record(ix, f, f->scope, go_record_decl);
+ f->scope = NULL; /* read: the index keeps no pointer into a blob */
+ }
+ if (!ok || ix->oom) {
+ cbm_log_error("doc_links.go.error", "step", "index", "reason", "alloc");
+ go_destroy(ix);
+ return NULL;
+ }
+ char b[CBM_SZ_4][CBM_SZ_32];
+ snprintf(b[0], sizeof(b[0]), "%d", ix->nfiles);
+ snprintf(b[SKIP_ONE], sizeof(b[SKIP_ONE]), "%d", ix->npkgs);
+ snprintf(b[PAIR_LEN], sizeof(b[PAIR_LEN]), "%d", ix->nmodules + ix->nstd);
+ snprintf(b[CBM_SZ_3], sizeof(b[CBM_SZ_3]), "%u", cbm_ht_count(ix->syms));
+ cbm_log_info("doc_links.go.index", "files", b[0], "packages", b[SKIP_ONE], "modules",
+ b[PAIR_LEN], "symbols", b[CBM_SZ_3]);
+ return ix;
+}
+
+/* ── Resolution ──────────────────────────────────────────────────── */
+
+typedef struct {
+ const go_index_t *ix;
+ const cbm_gbuf_t *g;
+ const go_file_t *src;
+ cbm_doclink_outcome_t *out;
+} go_ctx_t;
+
+static void go_row(const go_ctx_t *c, int reason) {
+ c->out->kind = CBM_DOCLINK_UNRESOLVED;
+ c->out->reason = reason;
+}
+
+/* Plain text for go/doc: neither an edge nor a row. */
+static void go_not_a_link(const go_ctx_t *c) {
+ c->out->kind = CBM_DOCLINK_LOCAL;
+}
+
+static void go_edge(const go_ctx_t *c, const cbm_gbuf_node_t *node, bool exact) {
+ if (!node) {
+ go_row(c, CBM_DOCLINK_REASON_GRAPH_GAP);
+ return;
+ }
+ c->out->kind = CBM_DOCLINK_EDGE;
+ c->out->target = node;
+ c->out->exact = exact;
+}
+
+/* A name the target package does not declare. Written bare it is plain text.
+ * Qualified it is a broken link; but in a package with a parse error the
+ * declaration may be hidden from the scan (a graph gap, not doc rot), and
+ * text with a non-ASCII byte may be no identifier at all, which this scan
+ * cannot tell (go/doc asks the Unicode letter classes): plain text. */
+static void go_undeclared(const go_ctx_t *c, const go_pkg_t *pkg, bool qualified, go_str_t recv,
+ go_str_t name) {
+ if (!qualified || go_has_non_ascii(recv) || go_has_non_ascii(name)) {
+ go_not_a_link(c);
+ } else {
+ go_row(c, pkg->incomplete ? CBM_DOCLINK_REASON_GRAPH_GAP : CBM_DOCLINK_REASON_MISSING);
+ }
+}
+
+/* The node <dir>.<a>[.<b>] of the package's directory, or NULL. */
+static const cbm_gbuf_node_t *go_find_node(const go_ctx_t *c, const go_pkg_t *pkg, go_str_t a,
+ go_str_t b) {
+ size_t ql = strlen(pkg->dir->qn);
+ go_buf_t buf;
+ char *qn = go_buf_get(&buf, ql + a.n + b.n + CBM_SZ_3);
+ if (!qn) {
+ return NULL;
+ }
+ size_t w = ql;
+ memcpy(qn, pkg->dir->qn, ql);
+ qn[w++] = '.';
+ memcpy(qn + w, a.s, a.n);
+ w += a.n;
+ if (b.s) {
+ qn[w++] = '.';
+ memcpy(qn + w, b.s, b.n);
+ w += b.n;
+ }
+ qn[w] = '\0';
+ const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(c->g, qn);
+ go_buf_free(&buf);
+ return n;
+}
+
+/* The file a node belongs to, when that is a file of package `pkg` whose
+ * declarations the reference may bind: not build-ignored, and no test code
+ * unless the reference itself is written in test code (a node kept by a test
+ * file's twin of a product declaration is no target for product code). */
+static const go_file_t *go_node_file(const go_ctx_t *c, const cbm_gbuf_node_t *n,
+ const go_pkg_t *pkg) {
+ if (!n || !n->file_path || !n->label) {
+ return NULL;
+ }
+ const go_file_t *f = (const go_file_t *)cbm_ht_get(c->ix->file_by_path, n->file_path);
+ if (!f || f->pkg != pkg || f->ignored || (f->is_test && !c->src->is_test)) {
+ return NULL;
+ }
+ return f;
+}
+
+static bool go_label_is(const cbm_gbuf_node_t *n, const char *label) {
+ return strcmp(n->label, label) == 0;
+}
+
+/* The declaration of the node's own file that keeps the flat name <dir>.<name>;
+ * NULL when the node is no file's of package `pkg`, or two declarations
+ * contest the name there. */
+static const go_flat_t *go_flat_owner(const go_ctx_t *c, const cbm_gbuf_node_t *n,
+ const go_pkg_t *pkg, go_str_t name) {
+ const go_file_t *f = go_node_file(c, n, pkg);
+ const go_flat_t *fl =
+ f ? (const go_flat_t *)go_lookup(c->ix->flat, f->idx, name, GO_NO_STR) : NULL;
+ return (fl && !fl->contested) ? fl : NULL;
+}
+
+/* The node of <dir>.<name> when it IS the package's function, type or value
+ * of that name: the node's file keeps the name for a declaration of that
+ * kind, and the node has its label. */
+static const cbm_gbuf_node_t *go_symbol_node(const go_ctx_t *c, const go_pkg_t *pkg, int kind,
+ go_str_t name) {
+ const cbm_gbuf_node_t *n = go_find_node(c, pkg, name, GO_NO_STR);
+ const go_flat_t *fl = go_flat_owner(c, n, pkg, name);
+ if (!fl || fl->owner != kind) {
+ return NULL;
+ }
+ bool label_ok = (kind == GO_KIND_FUNC && go_label_is(n, "Function")) ||
+ (kind == GO_KIND_TYPE && cbm_label_is_type_like(n->label)) ||
+ (kind == GO_KIND_VALUE && go_label_is(n, "Variable"));
+ return label_ok ? n : NULL;
+}
+
+/* The node of <dir>.<type>.<name> when it is that member of the package: a
+ * field or an interface method, or a method in a graph that names methods by
+ * their receiver. */
+static const cbm_gbuf_node_t *go_member_node(const go_ctx_t *c, const go_pkg_t *pkg, int kind,
+ go_str_t type, go_str_t name) {
+ const cbm_gbuf_node_t *n = go_find_node(c, pkg, type, name);
+ const go_file_t *f = go_node_file(c, n, pkg);
+ if (!f || !go_label_is(n, kind == GO_MEM_FIELD ? "Field" : "Method")) {
+ return NULL;
+ }
+ const go_fmem_t *fm = (const go_fmem_t *)go_lookup(c->ix->fmem, f->idx, type, name);
+ return (fm && (fm->node_kinds & kind)) ? n : NULL;
+}
+
+/* The node of the method `recv.name`: its receiver-qualified node, else the
+ * flat node <dir>.<name> when the method is the one that kept it (the last
+ * declaration of that name in the node's file). */
+static const cbm_gbuf_node_t *go_method_node(const go_ctx_t *c, const go_pkg_t *pkg, go_str_t recv,
+ go_str_t name) {
+ const cbm_gbuf_node_t *qualified = go_member_node(c, pkg, GO_MEM_METHOD, recv, name);
+ if (qualified) {
+ return qualified;
+ }
+ const cbm_gbuf_node_t *n = go_find_node(c, pkg, name, GO_NO_STR);
+ const go_flat_t *fl = go_flat_owner(c, n, pkg, name);
+ bool owns = fl && fl->owner == GO_KIND_METHOD && fl->method_recv &&
+ go_str_eq(recv, fl->method_recv) && go_label_is(n, "Method");
+ return owns ? n : NULL;
+}
+
+static bool go_one_bit(int bits) {
+ return bits != 0 && (bits & (bits - SKIP_ONE)) == 0;
+}
+
+/* Bind `n`, the node of a name declared once (build variants count as once).
+ * A name that two unconstrained files of the package declare (go_free_t) is
+ * two entities: written in a file that declares it itself (`declared_here`),
+ * the reference means that file's own declaration, which binds only when it
+ * is the one that has the node; written anywhere else, nothing picks one. */
+static void go_bind_node(const go_ctx_t *c, const cbm_gbuf_node_t *n, bool twins,
+ bool declared_here, bool exact) {
+ if (twins && !declared_here) {
+ go_row(c, CBM_DOCLINK_REASON_AMBIGUOUS);
+ return;
+ }
+ bool other_file = n && twins && strcmp(n->file_path, c->src->rel_path) != 0;
+ go_edge(c, other_file ? NULL : n, exact);
+}
+
+/* [Name] / [pkg.Name] in package `pkg`. */
+static void go_bind_symbol(const go_ctx_t *c, const go_pkg_t *pkg, go_str_t name, bool qualified) {
+ const go_sym_t *s = (const go_sym_t *)go_lookup(c->ix->syms, pkg->idx, name, GO_NO_STR);
+ if (!s) {
+ go_undeclared(c, pkg, qualified, GO_NO_STR, name);
+ } else if (!go_one_bit(s->kinds)) {
+ go_row(c, CBM_DOCLINK_REASON_AMBIGUOUS); /* a function here, a type there */
+ } else if (!s->prod && !c->src->is_test) {
+ go_row(c, CBM_DOCLINK_REASON_TEST_ONLY);
+ } else {
+ const go_flat_t *own =
+ pkg == c->src->pkg
+ ? (const go_flat_t *)go_lookup(c->ix->flat, c->src->idx, name, GO_NO_STR)
+ : NULL;
+ go_bind_node(c, go_symbol_node(c, pkg, s->kinds, name), s->free.files >= GO_TWINS,
+ own && (own->kinds & s->kinds), qualified);
+ }
+}
+
+/* The package a qualifier of file `file` names through its imports. */
+static go_path_kind_t go_import_package(const go_index_t *ix, const go_file_t *file,
+ go_str_t qualifier, const go_pkg_t **pkg_out) {
+ const go_import_t *im = go_file_import(file, qualifier);
+ if (!im || im->conflict) {
+ return GO_PATH_NO_PACKAGE;
+ }
+ const go_dir_t *dir = NULL;
+ go_path_kind_t kind = go_classify_path(ix, file, go_str(im->path), &dir);
+ if (kind != GO_PATH_PACKAGE) {
+ return kind;
+ }
+ bool ambiguous = false;
+ *pkg_out = go_dir_package(dir, qualifier, &ambiguous);
+ if (ambiguous) {
+ return GO_PATH_AMBIGUOUS;
+ }
+ return *pkg_out ? GO_PATH_PACKAGE : GO_PATH_NO_PACKAGE;
+}
+
+enum { GO_ALIAS_NONE = 0, GO_ALIAS_FOUND, GO_ALIAS_EXTERNAL, GO_ALIAS_TOO_DEEP };
+
+/* [X.Member] where X is `type X = Y` or `= pkg.Y`: follow the alias (and an
+ * alias of an alias) to the type that declares Member; *pkg and *recv then
+ * name that type. */
+static int go_follow_alias(const go_ctx_t *c, const go_pkg_t **pkg, go_str_t *recv, go_str_t name) {
+ for (int depth = 0; depth < GO_ALIAS_DEPTH; depth++) {
+ const go_sym_t *s = (const go_sym_t *)go_lookup(c->ix->syms, (*pkg)->idx, *recv, GO_NO_STR);
+ if (!s || !s->alias || s->alias_mixed || s->kinds != GO_KIND_TYPE) {
+ return GO_ALIAS_NONE;
+ }
+ const char *dot = strchr(s->alias, '.');
+ if (dot) {
+ go_str_t q = {s->alias, (size_t)(dot - s->alias)};
+ const go_pkg_t *next = NULL;
+ go_path_kind_t kind = go_import_package(c->ix, s->alias_file, q, &next);
+ if (kind == GO_PATH_EXTERNAL) {
+ return GO_ALIAS_EXTERNAL;
+ }
+ if (kind != GO_PATH_PACKAGE) {
+ return GO_ALIAS_NONE;
+ }
+ *pkg = next;
+ }
+ *recv = dot ? go_str(dot + SKIP_ONE) : go_str(s->alias);
+ if (go_lookup(c->ix->mems, (*pkg)->idx, *recv, name)) {
+ return GO_ALIAS_FOUND;
+ }
+ }
+ return GO_ALIAS_TOO_DEEP; /* never an answer taken from half the chain */
+}
+
+/* The member `recv.name` of package `*pkg`, looked up through an alias when
+ * the type does not declare it itself (*pkg and *recv then name the type that
+ * does). NULL with *row false: not declared. NULL with *row true: a row was
+ * set (the alias leads out of the repository, or too deep). */
+static const go_mem_t *go_find_member(const go_ctx_t *c, const go_pkg_t **pkg, go_str_t *recv,
+ go_str_t name, bool *row) {
+ *row = false;
+ const go_mem_t *m = (const go_mem_t *)go_lookup(c->ix->mems, (*pkg)->idx, *recv, name);
+ if (m) {
+ return m;
+ }
+ int followed = go_follow_alias(c, pkg, recv, name);
+ if (followed == GO_ALIAS_EXTERNAL || followed == GO_ALIAS_TOO_DEEP) {
+ go_row(c, followed == GO_ALIAS_EXTERNAL ? CBM_DOCLINK_REASON_EXTERNAL
+ : CBM_DOCLINK_REASON_UNPARSEABLE);
+ *row = true;
+ return NULL;
+ }
+ return followed == GO_ALIAS_FOUND
+ ? (const go_mem_t *)go_lookup(c->ix->mems, (*pkg)->idx, *recv, name)
+ : NULL;
+}
+
+/* [Recv.Name] / [pkg.Recv.Name] in package `pkg`.
+ *
+ * What binds: a member the named type declares ITSELF. That is a method
+ * declared with that receiver, a method of that interface type, or a field
+ * written in that type's own struct declaration; nothing promoted through an
+ * embedded type. A name the type does not declare is plain text when it is
+ * written without a package and a broken link (`missing`) when it is written
+ * with one. `type X = Y` is followed to the type that declares the member
+ * only for a reference written with a package.
+ *
+ * What go/doc does, as far as it is known here (no Go toolchain was at hand
+ * to check it; gopls sets its doc-comment parser up the same way): without a
+ * package, `Recv.Name` is a link only for a METHOD, so `[Type.Field]` inside
+ * its own package renders as plain text; with a package, go/doc links
+ * whatever follows it without looking.
+ *
+ * Binding the same-package field is a deliberate difference from go/doc. The
+ * brackets are doc-link syntax by the doc-comment specification ("[Name1.
+ * Name2] refers to exported identifiers in the current package"), and the
+ * field named is one declared entity, so nothing is guessed: its tier is
+ * `exact`. */
+static void go_bind_member(const go_ctx_t *c, const go_pkg_t *pkg, go_str_t recv, go_str_t name,
+ bool qualified) {
+ const go_pkg_t *named_pkg = pkg;
+ go_str_t named_recv = recv;
+ bool row = false;
+ const go_mem_t *m = qualified ? go_find_member(c, &pkg, &recv, name, &row)
+ : (const go_mem_t *)go_lookup(c->ix->mems, pkg->idx, recv, name);
+ if (row) {
+ return;
+ }
+ if (!m) {
+ go_undeclared(c, named_pkg, qualified, named_recv, name);
+ } else if (!go_one_bit(m->kinds)) {
+ go_row(c, CBM_DOCLINK_REASON_AMBIGUOUS); /* a method here, a field there */
+ } else if (!m->prod && !c->src->is_test) {
+ go_row(c, CBM_DOCLINK_REASON_TEST_ONLY);
+ } else {
+ /* the member of one type: twins of the TYPE split its members too */
+ const go_sym_t *ts = (const go_sym_t *)go_lookup(c->ix->syms, pkg->idx, recv, GO_NO_STR);
+ bool twins = m->free.files >= GO_TWINS || (ts && ts->free.files >= GO_TWINS);
+ const go_fmem_t *own =
+ pkg == c->src->pkg ? (const go_fmem_t *)go_lookup(c->ix->fmem, c->src->idx, recv, name)
+ : NULL;
+ const cbm_gbuf_node_t *n = m->kinds == GO_MEM_METHOD
+ ? go_method_node(c, pkg, recv, name)
+ : go_member_node(c, pkg, m->kinds, recv, name);
+ bool exact = qualified || m->kinds == GO_MEM_FIELD;
+ go_bind_node(c, n, twins, own && (own->kinds & m->kinds), exact);
+ }
+}
+
+/* [pkg]: the package's directory node. The graph has a Folder node per
+ * directory and no node per Go package; the repository root is the Project
+ * node, which is no package. */
+static void go_bind_package(const go_ctx_t *c, const go_pkg_t *pkg) {
+ if (!pkg->has_prod && !c->src->is_test) {
+ go_row(c, CBM_DOCLINK_REASON_TEST_ONLY);
+ return;
+ }
+ const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(c->g, pkg->dir->qn);
+ bool folder = n && n->label && strcmp(n->label, "Folder") == 0 && n->file_path &&
+ strcmp(n->file_path, pkg->dir->path) == 0;
+ go_edge(c, folder ? n : NULL, true);
+}
+
+/* Standard-library packages with a one-element import path (go/doc/comment
+ * stdPkgs): go/doc's own closed list, the only names it links without an
+ * import. A name of a later Go release that is missing here stays plain text;
+ * neither way is it an edge, unless the repository is the standard library
+ * itself (a `module std` tree), where the package is found by its path. */
+static bool go_is_std_single(go_str_t name) {
+ static const char *const std[] = {
+ "bufio", "bytes", "cmp", "context", "crypto", "embed", "encoding",
+ "errors", "expvar", "flag", "fmt", "hash", "html", "image",
+ "io", "iter", "log", "maps", "math", "mime", "net",
+ "os", "path", "plugin", "reflect", "regexp", "runtime", "slices",
+ "sort", "strconv", "strings", "structs", "sync", "syscall", "testing",
+ "time", "unicode", "unique", "unsafe", "uuid", "weak",
+ };
+ return go_word_in(name, std, sizeof(std) / sizeof(std[0]));
+}
+
+typedef enum {
+ GO_QUAL_NONE = 0, /* names no package: plain text */
+ GO_QUAL_SELF, /* the documented file's own package */
+ GO_QUAL_PATH, /* an import path */
+} go_qual_t;
+
+/* go/doc lookupPkg for a qualifier without a slash.
+ *
+ * go/doc itself knows only the UNION of the imports of all files of the
+ * package (one name with two paths is no name), then the package's own name,
+ * then its list of one-element standard-library paths. This resolver asks the
+ * documented FILE's own imports instead of the union: a strict subset of what
+ * go/doc links (a file can only disagree with the union by importing nothing
+ * under that name), so nothing is guessed, and a file's imports stay the
+ * file's own business -- with the union, every import edit would change its
+ * siblings' links and could not be repaired file by file. A qualifier that
+ * only a sibling file imports is therefore plain text here.
+ *
+ * A name two imports claim is no import name for go/doc, and it does not ask
+ * the package's own name then either: only the standard-library list is left. */
+static go_qual_t go_lookup_qualifier(const go_ctx_t *c, go_str_t q, go_str_t *path) {
+ const go_import_t *im = go_file_import(c->src, q);
+ if (im && !im->conflict) {
+ *path = go_str(im->path);
+ return GO_QUAL_PATH;
+ }
+ if (!im && go_str_eq(q, c->src->pkg->name)) {
+ return GO_QUAL_SELF;
+ }
+ if (go_is_std_single(q)) {
+ *path = q;
+ return GO_QUAL_PATH;
+ }
+ return GO_QUAL_NONE;
+}
+
+/* True when the bare name is a type parameter in scope of the documented
+ * declaration: its own, or that of the generic type it is declared in (a
+ * field, an interface method). Generic declarations are top-level and do not
+ * overlap, so the one that starts last at or before the line is the only
+ * candidate. */
+static bool go_own_type_param(const go_file_t *f, uint32_t def_line, go_str_t name) {
+ int lo = 0;
+ int hi = f->ngenerics - SKIP_ONE;
+ const go_generic_t *hit = NULL;
+ while (lo <= hi) {
+ int mid = lo + ((hi - lo) / PAIR_LEN);
+ if (f->generics[mid].line <= def_line) {
+ hit = &f->generics[mid];
+ lo = mid + SKIP_ONE;
+ } else {
+ hi = mid - SKIP_ONE;
+ }
+ }
+ if (hit && def_line > hit->last) {
+ hit = NULL;
+ }
+ for (const char *p = hit ? hit->names : ""; *p;) {
+ size_t n = strcspn(p, ",");
+ if (n == name.n && memcmp(p, name.s, n) == 0) {
+ return true;
+ }
+ p += n + (p[n] == ',');
+ }
+ return false;
+}
+
+/* The package an import path means for the documented file; a row or the
+ * plain-text outcome is set, and NULL returned, when it means none. */
+static const go_pkg_t *go_path_package(const go_ctx_t *c, go_str_t path, go_str_t hint) {
+ const go_dir_t *dir = NULL;
+ go_path_kind_t kind = go_classify_path(c->ix, c->src, path, &dir);
+ bool ambiguous = kind == GO_PATH_AMBIGUOUS;
+ const go_pkg_t *pkg = kind == GO_PATH_PACKAGE ? go_dir_package(dir, hint, &ambiguous) : NULL;
+ if (kind == GO_PATH_EXTERNAL) {
+ go_row(c, CBM_DOCLINK_REASON_EXTERNAL);
+ } else if (kind == GO_PATH_UNKNOWN) {
+ go_row(c, CBM_DOCLINK_REASON_UNPARSEABLE);
+ } else if (ambiguous) {
+ go_row(c, CBM_DOCLINK_REASON_AMBIGUOUS);
+ } else if (!pkg) {
+ go_row(c, CBM_DOCLINK_REASON_MISSING); /* a module path without a package there */
+ }
+ return ambiguous ? NULL : pkg;
+}
+
+/* A reference qualified by `pkg` (an import path, or a name to look up). */
+static void go_resolve_qualified(const go_ctx_t *c, const CBMDocLinkGoRef *ref) {
+ go_str_t q = {ref->pkg, ref->pkg_len};
+ go_str_t path = q;
+ go_str_t hint = q;
+ const go_pkg_t *pkg = c->src->pkg;
+ if (memchr(q.s, '/', q.n)) {
+ hint = go_path_base(q);
+ } else {
+ go_qual_t kind = go_lookup_qualifier(c, q, &path);
+ if (kind == GO_QUAL_NONE) {
+ go_not_a_link(c);
+ return;
+ }
+ if (kind == GO_QUAL_SELF) {
+ path.n = 0;
+ }
+ }
+ if (path.n > 0) {
+ pkg = go_path_package(c, path, hint);
+ if (!pkg) {
+ return;
+ }
+ }
+ go_str_t name = {ref->name, ref->name_len};
+ go_str_t recv = {ref->recv, ref->recv_len};
+ if (name.n == 0) {
+ go_bind_package(c, pkg);
+ } else if (recv.n == 0) {
+ go_bind_symbol(c, pkg, name, true);
+ } else {
+ go_bind_member(c, pkg, recv, name, true);
+ }
+}
+
+/* True when the node the core takes for the edge's source IS the documented
+ * declaration: it sits in the file being resolved, at the declaration's line.
+ * Go method nodes share a flat name, so without this the doc of a method that
+ * lost the name (or of a build-tag twin) would be attributed to another
+ * declaration's node, in another file or on another line. That node's lines
+ * are known here: the file is one this run extracted. */
+static bool go_source_owns_node(const go_ctx_t *c, const CBMDocLink *link) {
+ if ((link->flags & CBM_DOCLINK_FLAG_FILE) || !link->source_qn) {
+ return true; /* the file's own doc: its File node is the source */
+ }
+ const cbm_gbuf_node_t *src = cbm_gbuf_find_by_qn(c->g, link->source_qn);
+ if (!src) {
+ return true; /* no node at all: the core drops the reference */
+ }
+ return src->file_path && strcmp(src->file_path, c->src->rel_path) == 0 &&
+ src->start_line == (int)link->def_line;
+}
+
+/* A well-formed reference of a file that has a package: by its shape. */
+static void go_resolve_ref(const go_ctx_t *c, const CBMDocLink *link, const CBMDocLinkGoRef *ref) {
+ go_str_t name = {ref->name, ref->name_len};
+ go_str_t recv = {ref->recv, ref->recv_len};
+ bool of_declaration = !(link->flags & CBM_DOCLINK_FLAG_FILE);
+ if (ref->pkg_len > 0) {
+ go_resolve_qualified(c, ref);
+ } else if (recv.n > 0) {
+ go_bind_member(c, c->src->pkg, recv, name, false);
+ } else if (of_declaration && go_own_type_param(c->src, link->def_line, name)) {
+ go_not_a_link(c); /* the declaration's own type parameter */
+ } else {
+ go_bind_symbol(c, c->src->pkg, name, false);
+ }
+}
+
+static void go_resolve(const void *index, void *state, int run_file, const CBMDocLink *link,
+ const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {
+ (void)state; /* Go keeps no per-file working state */
+ const go_index_t *ix = (const go_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]) {
+ return;
+ }
+ go_ctx_t c = {.ix = ix, .g = graph, .src = ix->run_to_file[run_file], .out = out};
+ size_t raw_len = strlen(link->raw);
+ CBMDocLinkGoRef ref;
+ if (raw_len > CBM_DOCLINK_GO_REF_MAX) {
+ go_row(&c, CBM_DOCLINK_REASON_UNPARSEABLE); /* clipped at extraction: never resolved */
+ return;
+ }
+ if (!cbm_doclink_go_parse_ref(link->raw, raw_len, &ref)) {
+ go_not_a_link(&c); /* go/doc knows no malformed link, only text */
+ return;
+ }
+ if (!c.src->pkg) {
+ go_row(&c, CBM_DOCLINK_REASON_GRAPH_GAP); /* no package clause: nothing can be placed */
+ return;
+ }
+ go_resolve_ref(&c, link, &ref);
+ if (out->kind == CBM_DOCLINK_EDGE && !go_source_owns_node(&c, link)) {
+ go_row(&c, CBM_DOCLINK_REASON_GRAPH_GAP); /* the documented declaration has no node */
+ }
+}
+
+/* ── Incremental scope rules ─────────────────────────────────────── */
+
+/* The next record line of a blob; false at the end. */
+static bool go_delta_next(const char **cursor, go_str_t *line) {
+ const char *p = *cursor;
+ if (!p || !*p) {
+ return false;
+ }
+ const char *nl = strchr(p, '\n');
+ line->s = p;
+ line->n = nl ? (size_t)(nl - p) : strlen(p);
+ *cursor = nl ? nl + SKIP_ONE : p + line->n;
+ return true;
+}
+
+/* The first record line of a blob: what follows its tag line. */
+static const char *go_delta_start(const char *blob) {
+ const char *nl = strchr(blob, '\n');
+ return nl ? nl + SKIP_ONE : NULL;
+}
+
+static int go_line_cmp(go_str_t a, go_str_t b) {
+ int c = memcmp(a.s, b.s, a.n < b.n ? a.n : b.n);
+ if (c == 0 && a.n != b.n) {
+ c = a.n < b.n ? -SKIP_ONE : SKIP_ONE;
+ }
+ return c;
+}
+
+/* Field `want` (0-based) of a record line; GO_NO_STR when it has fewer. */
+static go_str_t go_record_field(go_str_t line, int want) {
+ size_t start = 0;
+ int field = 0;
+ for (size_t i = 0; i <= line.n; i++) {
+ if (i < line.n && line.s[i] != '\t') {
+ continue;
+ }
+ if (field == want) {
+ return (go_str_t){line.s + start, i - start};
+ }
+ field++;
+ start = i + SKIP_ONE;
+ }
+ return GO_NO_STR;
+}
+
+/* The name a record declares: field 1 of F and V, field 2 of M, f and m. */
+static go_str_t go_record_name(go_str_t line) {
+ return go_record_field(line, (line.s[0] == 'F' || line.s[0] == 'V') ? SKIP_ONE : PAIR_LEN);
+}
+
+/* `T name a pkg.Y w`: an alias whose target is read through the file's
+ * imports. */
+static bool go_is_qualified_alias(go_str_t line) {
+ enum { T_ALIAS_FIELD = 3 };
+ if (line.n == 0 || line.s[0] != 'T') {
+ return false;
+ }
+ go_str_t alias = go_record_field(line, T_ALIAS_FIELD);
+ return alias.s && memchr(alias.s, '.', alias.n) != NULL;
+}
+
+typedef struct {
+ cbm_doclink_name_fn removed;
+ void *ud;
+ bool imports_changed;
+ bool qualified_alias;
+ bool global;
+ bool failed;
+} go_delta_t;
+
+/* A record only one of the two scopes has. */
+static void go_delta_record(go_delta_t *d, go_str_t line, bool stored_only) {
+ char kind = line.s[0];
+ if (kind == 'I') {
+ d->imports_changed = true;
+ return;
+ }
+ if (kind == 'g') {
+ return; /* never persisted; a fresh blob may still carry them */
+ }
+ bool removable = kind == 'F' || kind == 'M' || kind == 'V' || kind == 'f' || kind == 'm';
+ if (!stored_only || !removable) {
+ d->global = true; /* a new or changed record, a package, type or module line */
+ return;
+ }
+ go_str_t name = go_record_name(line);
+ if (!name.s || name.n == 0 || !d->removed || !d->removed(d->ud, name.s, name.n)) {
+ d->failed = true;
+ }
+}
+
+/* One step of the merge of two sorted scopes: -1 a record only the stored
+ * scope has, 1 one only the fresh scope has, 0 the same record in both. */
+static int go_delta_step(go_delta_t *d, bool has_stored, go_str_t stored, bool has_fresh,
+ go_str_t fresh) {
+ int c = 0;
+ if (!has_stored) {
+ c = SKIP_ONE;
+ } else if (!has_fresh) {
+ c = -SKIP_ONE;
+ } else {
+ c = go_line_cmp(stored, fresh);
+ }
+ d->qualified_alias = d->qualified_alias || (c <= 0 && go_is_qualified_alias(stored)) ||
+ (c >= 0 && go_is_qualified_alias(fresh));
+ if (c < 0) {
+ go_delta_record(d, stored, true);
+ } else if (c > 0) {
+ go_delta_record(d, fresh, false);
+ }
+ return c;
+}
+
+/* Both scopes are sorted, so one merge finds what each has alone.
+ * LOCAL nothing differs; or only the file's imports differ (they scope
+ * the file itself, which is re-extracted anyway); or declarations
+ * only LEFT: a function, method, value, field or interface method.
+ * Their names are reported: files with an edge into the changed
+ * file are dependents anyway, and files whose unresolved rows name
+ * one re-resolve.
+ * GLOBAL anything that appeared or changed (a name appearing can turn
+ * another file's plain text into a link or a graph gap; a w field
+ * flipping hands a node to another declaration), the package
+ * clause, a type (an alias may be followed through it), a module
+ * path, and the imports of a file with a qualified alias (other
+ * files follow `type X = pkg.Y` through them). */
+static int go_scope_delta(const char *stored, const char *fresh, cbm_doclink_name_fn removed,
+ void *ud) {
+ go_delta_t d = {.removed = removed, .ud = ud};
+ const char *sp = go_delta_start(stored);
+ const char *fp = go_delta_start(fresh);
+ go_str_t sl = GO_NO_STR;
+ go_str_t fl = GO_NO_STR;
+ bool hs = go_delta_next(&sp, &sl);
+ bool hf = go_delta_next(&fp, &fl);
+ while ((hs || hf) && !d.global && !d.failed) {
+ int c = go_delta_step(&d, hs, sl, hf, fl);
+ if (c <= 0) {
+ hs = go_delta_next(&sp, &sl);
+ }
+ if (c >= 0) {
+ hf = go_delta_next(&fp, &fl);
+ }
+ }
+ if (d.failed) {
+ return CBM_NOT_FOUND;
+ }
+ bool global = d.global || (d.imports_changed && d.qualified_alias);
+ return global ? CBM_DOCLINK_DELTA_GLOBAL : CBM_DOCLINK_DELTA_LOCAL;
+}
+
+const cbm_doclink_resolver_t cbm_doclink_go_resolver = {
+ .langs = {CBM_LANG_GO, CBM_LANG_GOMOD},
+ .lang_count = 2,
+ .scope_tag = CBM_DOCLINK_GO_SCOPE_TAG,
+ .build = go_build,
+ .destroy = go_destroy,
+ .resolve = go_resolve,
+ .scope_delta = go_scope_delta,
+};
diff --git a/tests/test_doc_mentions_go.c b/tests/test_doc_mentions_go.c
new file mode 100644
index 000000000..f3d9b58b5
--- /dev/null
+++ b/tests/test_doc_mentions_go.c
@@ -0,0 +1,2112 @@
+/*
+ * test_doc_mentions_go.c — Go doc links ([Name], [pkg.Name], [Recv.Method])
+ * -> MENTIONS edges.
+ *
+ * Extraction (doclink_go.c: the go/doc/comment text model, the candidate
+ * tokens, the scope blob) and the resolver (doc_links_go.c) through real
+ * fixtures indexed with cbm_pipeline_run.
+ */
+#include "test_framework.h"
+#include "test_doc_mentions_helpers.h"
+
+/* ── helpers of this file ────────────────────────────────────────── */
+
+static CBMFileResult *go_extract(const char *src, const char *rel) {
+ return dm_extract(src, CBM_LANG_GO, rel);
+}
+
+/* The tokens of one doc comment put above `type T struct{}` in package p. */
+static CBMFileResult *go_doc(const char *comment) {
+ char src[8192];
+ snprintf(src, sizeof(src), "package p\n\n%stype T struct{}\n", comment);
+ return go_extract(src, "pkg/t.go");
+}
+
+/* True when the scope blob holds exactly this record line. */
+static bool go_has_rec(const char *scope, const char *rec) {
+ size_t n = strlen(rec);
+ for (const char *p = scope; p && *p;) {
+ const char *nl = strchr(p, '\n');
+ size_t len = nl ? (size_t)(nl - p) : strlen(p);
+ if (len == n && memcmp(p, rec, n) == 0) {
+ return true;
+ }
+ p = nl ? nl + 1 : NULL;
+ }
+ return false;
+}
+
+static void go_w(const char *repo, const char *rel, const char *content) {
+ th_write_file(TH_PATH(repo, rel), content);
+}
+
+/* Tier of the one MENTIONS edge src -> tgt (qualified-name suffixes): "exact"
+ * or "unique"; "" when there is no such edge; "many" for more than one. */
+static const char *go_tier(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 == 0) {
+ return "";
+ }
+ if (n != 1) {
+ return "many";
+ }
+ if (strstr(props, "\"syntax\":\"doc_link\"") == NULL) {
+ return "other-syntax";
+ }
+ return strstr(props, "\"tier\":\"exact\"") ? "exact" : "unique";
+}
+
+/* Reason of the unresolved row for `raw` in `rel`; "" when there is none. */
+static const char *go_reason(const char *db, const char *rel, const char *raw) {
+ static char reason[64];
+ dm_row(db, rel, raw, reason, sizeof(reason), NULL, 0);
+ return reason;
+}
+
+typedef struct {
+ const char *src;
+ const char *tgt;
+ const char *tier; /* "": there must be no edge */
+} go_want_edge_t;
+
+typedef struct {
+ const char *rel;
+ const char *raw;
+ const char *reason; /* "": there must be no row */
+} go_want_row_t;
+
+/* The number of edges that are not as wanted (each one printed). */
+static int go_bad_edges(const char *db, const go_want_edge_t *want, size_t n) {
+ int bad = 0;
+ for (size_t i = 0; i < n; i++) {
+ const char *tier = go_tier(db, want[i].src, want[i].tgt);
+ if (strcmp(tier, want[i].tier) != 0) {
+ printf(" edge %s -> %s: \"%s\", want \"%s\"\n", want[i].src, want[i].tgt, tier,
+ want[i].tier);
+ bad++;
+ }
+ }
+ return bad;
+}
+
+/* The number of rows that are not as wanted (each one printed). */
+static int go_bad_rows(const char *db, const go_want_row_t *want, size_t n) {
+ int bad = 0;
+ for (size_t i = 0; i < n; i++) {
+ const char *reason = go_reason(db, want[i].rel, want[i].raw);
+ if (strcmp(reason, want[i].reason) != 0) {
+ printf(" row %s [%s]: \"%s\", want \"%s\"\n", want[i].rel, want[i].raw, reason,
+ want[i].reason);
+ bad++;
+ }
+ }
+ return bad;
+}
+
+#define GO_COUNT(a) (sizeof(a) / sizeof((a)[0]))
+
+/* ── extraction: tokens ──────────────────────────────────────────── */
+
+TEST(doc_mentions_go_tokens) {
+ const char *src =
+ "package p\n" /* 1 */
+ "\n" /* 2 */
+ "// Widget does things. See [Thing], [*Star], [Thing.Run],\n" /* 3 */
+ "// [fmt.Println], [encoding/json.Marshal], [io] and [pkg.Recv.Name].\n" /* 4 */
+ "// Not links: map[string]Value, a[i], x[Mid]y, [not a link], [lower.case],\n" /* 5 */
+ "// [Plural]s and s[Sub].\n" /* 6 */
+ "//\n" /* 7 */
+ "//\tcode [InCode] here\n" /* 8 */
+ "//\n" /* 9 */
+ "// # Heading [InHeading]\n" /* 10 */
+ "//\n" /* 11 */
+ "// - item [InList] one\n" /* 12 */
+ "// - [RFC 7159] defined below\n" /* 13 */
+ "//\n" /* 14 */
+ "// [RFC 7159]: https://tools.ietf.org/html/rfc7159\n" /* 15 */
+ "type Widget struct{}\n"; /* 16 */
+ CBMFileResult *r = go_extract(src, "pkg/w.go");
+ ASSERT_NOT_NULL(r);
+ const CBMDocLink *thing = dm_find_token(r, "Thing");
+ ASSERT_NOT_NULL(thing);
+ ASSERT_EQ(thing->line, 3);
+ ASSERT_EQ(thing->syntax, CBM_DOCLINK_GO_DOC_LINK);
+ ASSERT_STR_EQ(thing->source_qn, "p.pkg.Widget");
+ ASSERT_EQ(thing->def_line, 16);
+ /* the star stays in the raw text; the resolver skips it */
+ ASSERT_NOT_NULL(dm_find_token(r, "*Star"));
+ ASSERT_NOT_NULL(dm_find_token(r, "Thing.Run"));
+ const CBMDocLink *println = dm_find_token(r, "fmt.Println");
+ ASSERT_NOT_NULL(println);
+ ASSERT_EQ(println->line, 4);
+ ASSERT_NOT_NULL(dm_find_token(r, "encoding/json.Marshal"));
+ ASSERT_NOT_NULL(dm_find_token(r, "io"));
+ ASSERT_NOT_NULL(dm_find_token(r, "pkg.Recv.Name"));
+ /* the border rule: a bracket pair touching a letter is an index or a
+ * type, never a link */
+ ASSERT_NULL(dm_find_token(r, "string"));
+ ASSERT_NULL(dm_find_token(r, "i"));
+ ASSERT_NULL(dm_find_token(r, "Mid"));
+ ASSERT_NULL(dm_find_token(r, "Plural"));
+ ASSERT_NULL(dm_find_token(r, "Sub"));
+ /* no doc-link shape */
+ ASSERT_NULL(dm_find_token(r, "not a link"));
+ ASSERT_NULL(dm_find_token(r, "lower.case"));
+ /* a code block and a heading hold no links; a list item does */
+ ASSERT_NULL(dm_find_token(r, "InCode"));
+ ASSERT_NULL(dm_find_token(r, "InHeading"));
+ const CBMDocLink *in_list = dm_find_token(r, "InList");
+ ASSERT_NOT_NULL(in_list);
+ ASSERT_EQ(in_list->line, 12);
+ /* a text with a link definition is a URL: one href token per use, none
+ * for the definition itself */
+ const CBMDocLink *href = dm_find_token(r, "https://tools.ietf.org/html/rfc7159");
+ ASSERT_NOT_NULL(href);
+ ASSERT_EQ(href->syntax, CBM_DOCLINK_HREF);
+ ASSERT_EQ(href->line, 13);
+ ASSERT_EQ(dm_count_tokens(r, "https://tools.ietf.org/html/rfc7159"), 1);
+ ASSERT_NULL(dm_find_token(r, "RFC 7159"));
+ ASSERT_EQ(r->doc_links.count, 9);
+ cbm_free_result(r);
+
+ /* the family and its name */
+ ASSERT_STR_EQ(cbm_doclink_syntax_name(CBM_DOCLINK_GO_DOC_LINK), "doc_link");
+ const CBMDocLinkFamily *f = cbm_doclink_family(CBM_DOCLINK_GO_DOC_LINK);
+ ASSERT_NOT_NULL(f);
+ ASSERT_EQ(f->lang, CBM_LANG_GO);
+ /* held in production until its held-out audit passes; the suite ships it */
+ cbm_doclink_test_reset_ships();
+ bool ships_in_production = cbm_doclink_syntax_ships(CBM_DOCLINK_GO_DOC_LINK);
+ dm_ship_held_families();
+ ASSERT_FALSE(ships_in_production);
+ ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_GO_DOC_LINK));
+ PASS();
+}
+
+/* Every documented kind of definition is a source. */
+TEST(doc_mentions_go_sources) {
+ const char *src = "package p\n"
+ "\n"
+ "// F doc [RefF].\n"
+ "func F() {}\n"
+ "\n"
+ "// S doc [RefS].\n"
+ "type S struct {\n"
+ "\t// Field doc [RefField].\n"
+ "\tField int\n"
+ "}\n"
+ "\n"
+ "// M doc [RefM].\n"
+ "func (s *S) M() {}\n"
+ "\n"
+ "// I doc [RefI].\n"
+ "type I interface {\n"
+ "\t// Do doc [RefDo].\n"
+ "\tDo()\n"
+ "}\n"
+ "\n"
+ "// C doc [RefC].\n"
+ "const C = 1\n"
+ "\n"
+ "const (\n"
+ "\t// K doc [RefK].\n"
+ "\tK = iota\n"
+ ")\n"
+ "\n"
+ "// V doc [RefV].\n"
+ "var V = 2\n"
+ "\n"
+ "// A doc [RefA].\n"
+ "type A = S\n";
+ CBMFileResult *r = go_extract(src, "pkg/s.go");
+ ASSERT_NOT_NULL(r);
+ static const struct {
+ const char *raw;
+ const char *source;
+ } want[] = {
+ {"RefF", "p.pkg.F"}, {"RefS", "p.pkg.S"}, {"RefField", "p.pkg.S.Field"},
+ {"RefM", "p.pkg.M"}, /* Go method nodes have a flat name */
+ {"RefI", "p.pkg.I"}, {"RefDo", "p.pkg.I.Do"}, {"RefC", "p.pkg.C"},
+ {"RefK", "p.pkg.K"}, {"RefV", "p.pkg.V"}, {"RefA", "p.pkg.A"},
+ };
+ for (size_t i = 0; i < GO_COUNT(want); i++) {
+ const CBMDocLink *t = dm_find_token(r, want[i].raw);
+ if (!t || strcmp(t->source_qn, want[i].source) != 0) {
+ printf(" %s: source %s, want %s\n", want[i].raw, t ? t->source_qn : "(no token)",
+ want[i].source);
+ FAIL("source of a doc link");
+ }
+ ASSERT_EQ(dm_count_tokens(r, want[i].raw), 1);
+ ASSERT_EQ(t->flags & CBM_DOCLINK_FLAG_FILE, 0);
+ }
+ cbm_free_result(r);
+ PASS();
+}
+
+/* The package comment is a source of its own (the File node), harvested once:
+ * no definition's docstring is the package comment. */
+TEST(doc_mentions_go_package_comment_tokens) {
+ static const struct {
+ const char *what;
+ const char *src;
+ int file_tokens; /* tokens [Ref] flagged as written in the file's doc */
+ int def_tokens; /* tokens [Ref] of a definition */
+ uint32_t line; /* line of the file-level token */
+ } cases[] = {
+ {"package comment, then a documented declaration",
+ "// Package p has a [Ref].\npackage p\n\n// F is.\nfunc F() {}\n", 1, 0, 1},
+ {"declaration without a doc right after the clause",
+ "// Package p has a [Ref].\npackage p\nfunc F() {}\ntype T struct{}\nvar V = 1\n", 1, 0,
+ 1},
+ {"block comment", "/*\nPackage p has a [Ref].\n*/\npackage p\n\nfunc F() {}\n", 1, 0, 2},
+ {"a header comment is no package comment",
+ "// Copyright [Ref].\n\npackage p\n\nfunc F() {}\n", 0, 0, 0},
+ {"header, then the package comment",
+ "// Copyright.\n\n// Package p has a [Ref].\npackage p\n\nfunc F() {}\n", 1, 0, 3},
+ {"build line, then the package comment",
+ "//go:build linux\n\n// Package p has a [Ref].\npackage p\n", 1, 0, 3},
+ {"the same link in the package comment and in a declaration's doc",
+ "// Package p has a [Ref].\npackage p\n\n// F has a [Ref].\nfunc F() {}\n", 1, 1, 1},
+ };
+ for (size_t i = 0; i < GO_COUNT(cases); i++) {
+ CBMFileResult *r = go_extract(cases[i].src, "pkg/doc.go");
+ ASSERT_NOT_NULL(r);
+ int file_tokens = 0;
+ int def_tokens = 0;
+ uint32_t line = 0;
+ for (int k = 0; k < r->doc_links.count; k++) {
+ const CBMDocLink *t = &r->doc_links.items[k];
+ if (strcmp(t->raw, "Ref") != 0) {
+ continue;
+ }
+ if (t->flags & CBM_DOCLINK_FLAG_FILE) {
+ file_tokens++;
+ line = t->line;
+ } else {
+ def_tokens++;
+ }
+ }
+ if (file_tokens != cases[i].file_tokens || def_tokens != cases[i].def_tokens ||
+ line != cases[i].line) {
+ printf(" %s: %d file tokens (line %u), %d definition tokens\n", cases[i].what,
+ file_tokens, line, def_tokens);
+ cbm_free_result(r);
+ FAIL("package comment harvested once, as the file's");
+ }
+ cbm_free_result(r);
+ }
+ PASS();
+}
+
+/* The go/doc/comment text model, case by case. */
+TEST(doc_mentions_go_text_model) {
+ static const struct {
+ const char *what;
+ const char *comment;
+ const char *present; /* '|'-separated raw texts that must be tokens */
+ const char *absent; /* '|'-separated raw texts that must not be */
+ } cases[] = {
+ {"block comment", "/*\nBlock [InBlock] text.\n\n\tcode [BlockCode]\n*/\n", "InBlock",
+ "BlockCode"},
+ {"block comment on one line", "/* One [OneLine] line. */\n", "OneLine", ""},
+ {"common indent is no code", "/*\n Indented [Para] text\n more text\n*/\n", "Para",
+ ""},
+ {"no space after the slashes", "//[Tight] text\n", "Tight", ""},
+ {"directive lines are no text", "// See [Kept].\n//go:generate echo [Gen]\n", "Kept",
+ "Gen"},
+ {"carriage returns", "// Line [Cr] one.\r\n// Line two.\r\n", "Cr", ""},
+ {"numbered list", "// Steps:\n// 1. first [NumOne]\n// 2) second [NumTwo]\n",
+ "NumOne|NumTwo", ""},
+ {"list item continuation", "// List:\n// - item starts\n// and [Continued] here\n",
+ "Continued", ""},
+ {"code after a paragraph without a blank line",
+ "// Text [BeforeCode] then\n//\tx := [NotThis]\n", "BeforeCode", "NotThis"},
+ {"brace line joins the code block",
+ "// func main() {\n//\tuse([InBody])\n// }\n// After [AfterBrace].\n", "AfterBrace",
+ "InBody"},
+ {"unindented list before its wrapped line",
+ "// - first [ListA]\n// - second\n// wrapped [ListB]\n", "ListA|ListB", ""},
+ {"heading needs blank lines only towards text",
+ "// Intro.\n//\n// # Title [InTitle]\n//\n// Body [InBody2].\n", "InBody2", "InTitle"},
+ {"hash line inside a paragraph is text", "// Intro\n// # not a heading [InPara]\n",
+ "InPara", ""},
+ {"a pair restarts at every opening bracket", "// See [[Inner]] and [a [Second]].\n",
+ "Inner|Second", "a [Second"},
+ {"brackets across a line break are no link", "// See [Split\n// Name] here.\n", "",
+ "Split\nName|Split Name"},
+ {"unicode punctuation borders",
+ "// See \xE2\x80\x9C[Quoted]\xE2\x80\x9D \xE2\x80\x94[Dashed]\xE2\x80\xA6\n",
+ "Quoted|Dashed", ""},
+ {"letters of any script are no border",
+ "// See \xC3\xA9[AfterLetter] and [BeforeLetter]\xD0\xB6.\n", "",
+ "AfterLetter|BeforeLetter"},
+ {"symbols are no punctuation", "// See `[Ticked]` =[Equals] +[Plus]+ $[Dollar].\n", "",
+ "Ticked|Equals|Plus|Dollar"},
+ {"punctuation on both sides", "// See ([Paren]), \"[Quote]\", [Comma], [Dot].\n",
+ "Paren|Quote|Comma|Dot", ""},
+ {"paragraph edges", "// [First] word and last [Last]\n", "First|Last", ""},
+ {"link definitions must fill their paragraph",
+ "// [Mixed]: https://example.com/a\n// and text [Other].\n", "Other|Mixed", ""},
+ {"unknown scheme defines nothing", "// Use [Odd].\n//\n// [Odd]: gopher2://example.com\n",
+ "Odd", ""},
+ /* go/doc looks a link text up from the FIRST opening bracket since the
+ * last closing one, without the brackets: `[a [Def]` asks for `a Def` */
+ {"nested opening brackets: the pair's own text is not the looked-up text",
+ "// See [a [Def] here.\n//\n// [Def]: https://example.com/def\n", "Def",
+ "https://example.com/def"},
+ {"nested opening brackets: the text since the first one is",
+ "// See [a [Def] here.\n//\n// [a Def]: https://example.com/adef\n",
+ "https://example.com/adef", "Def"},
+ {"name shapes", "// [x.Y] [x.Y.Z] [X.Y] [a/b] [a/b.C] [a/b.C.D] [*a/b.C]\n",
+ "x.Y|x.Y.Z|X.Y|a/b|a/b.C|a/b.C.D|*a/b.C", ""},
+ {"bad shapes",
+ "// [x.y.Z] [X.y] [1x] [X-Y] [a//b] [a/b/] [-a/b] [a/.b] [x.Y.Z.W] [**X] [] [*]\n", "",
+ "x.y.Z|X.y|X-Y|a//b|a/b/|-a/b|a/.b|x.Y.Z.W|**X|*"},
+ {"a quirk kept from go/doc: a leading dot", "// See [.Dotted].\n", ".Dotted", ""},
+ /* a Name starts with an upper-case letter of any script; the word
+ * before the dot is a package name whatever its letters */
+ {"capital letters beyond ASCII",
+ "// See [\xC3\x9C"
+ "ber], [\xC3\xBC"
+ "ber.Name] and [X.\xC3\xBC"
+ "ber].\n",
+ "\xC3\x9C"
+ "ber|\xC3\xBC"
+ "ber.Name",
+ "X.\xC3\xBC"
+ "ber"},
+ };
+ for (size_t i = 0; i < GO_COUNT(cases); i++) {
+ CBMFileResult *r = go_doc(cases[i].comment);
+ ASSERT_NOT_NULL(r);
+ for (int pass = 0; pass < 2; pass++) {
+ char list[512];
+ snprintf(list, sizeof(list), "%s", pass == 0 ? cases[i].present : cases[i].absent);
+ for (char *tok = list; tok && *tok;) {
+ char *bar = strchr(tok, '|');
+ if (bar) {
+ *bar = '\0';
+ }
+ bool found = dm_find_token(r, tok) != NULL;
+ if (found != (pass == 0)) {
+ printf(" %s: [%s] %s\n", cases[i].what, tok,
+ found ? "is a token" : "is no token");
+ cbm_free_result(r);
+ FAIL("go/doc text model");
+ }
+ tok = bar ? bar + 1 : NULL;
+ }
+ }
+ cbm_free_result(r);
+ }
+ PASS();
+}
+
+/* A reference to the documented function's own parameter is local. */
+TEST(doc_mentions_go_own_parameter) {
+ const char *src = "package p\n"
+ "\n"
+ "// Fetch reads from [url] with [Client] and reports to [Other].\n"
+ "func Fetch(url string, Client int) {}\n"
+ "\n"
+ "// Later mentions [url] and [Client], which are no parameters here.\n"
+ "func Later() {}\n";
+ CBMFileResult *r = go_extract(src, "pkg/f.go");
+ ASSERT_NOT_NULL(r);
+ ASSERT_NOT_NULL(dm_find_token(r, "Other"));
+ /* one token each: the one of Later */
+ ASSERT_EQ(dm_count_tokens(r, "url"), 1);
+ ASSERT_EQ(dm_count_tokens(r, "Client"), 1);
+ ASSERT_STR_EQ(dm_find_token(r, "url")->source_qn, "p.pkg.Later");
+ ASSERT_STR_EQ(dm_find_token(r, "Client")->source_qn, "p.pkg.Later");
+ cbm_free_result(r);
+ PASS();
+}
+
+/* ── extraction: hostile input ───────────────────────────────────── */
+
+TEST(doc_mentions_go_hostile_doc) {
+ /* an unterminated block comment, a bracket at the very end, a lone
+ * closing bracket, a bracket that never closes */
+ CBMFileResult *r = go_doc("// ] [ [Ok] [\n");
+ ASSERT_NOT_NULL(r);
+ ASSERT_EQ(r->doc_links.count, 1);
+ ASSERT_NOT_NULL(dm_find_token(r, "Ok"));
+ cbm_free_result(r);
+
+ /* invalid UTF-8 next to a bracket is no border: no token, no crash */
+ r = go_doc("// \xFF[Bad1] [Bad2]\xC3 [Bad3]\x80 \xE2\x80[Bad4] [Good].\n");
+ ASSERT_NOT_NULL(r);
+ ASSERT_NULL(dm_find_token(r, "Bad1"));
+ ASSERT_NULL(dm_find_token(r, "Bad2"));
+ ASSERT_NULL(dm_find_token(r, "Bad3"));
+ ASSERT_NULL(dm_find_token(r, "Bad4"));
+ ASSERT_NOT_NULL(dm_find_token(r, "Good"));
+ cbm_free_result(r);
+
+ /* an oversized reference is harvested clipped (one byte past the limit,
+ * so the resolver sees that it is too long and never resolves it); the
+ * next reference is read as usual */
+ enum { BIG = 1 << 20 };
+ char *src = malloc(BIG + 256);
+ ASSERT_NOT_NULL(src);
+ size_t w = (size_t)snprintf(src, 64, "package p\n\n// See [");
+ memset(src + w, 'A', BIG);
+ w += BIG;
+ w += (size_t)snprintf(src + w, 128, "] and [Small].\ntype T struct{}\n");
+ r = cbm_extract_file(src, (int)w, CBM_LANG_GO, "p", "pkg/big.go", 0, NULL, NULL);
+ ASSERT_NOT_NULL(r);
+ ASSERT_EQ(r->doc_links.count, 2);
+ ASSERT_NOT_NULL(dm_find_token(r, "Small"));
+ ASSERT_EQ(strlen(r->doc_links.items[0].raw), (size_t)CBM_DOCLINK_GO_REF_MAX + 1);
+ ASSERT_EQ(r->doc_links.items[0].syntax, CBM_DOCLINK_GO_DOC_LINK);
+ cbm_free_result(r);
+
+ /* oversized text that is no link (it has spaces) is no token at all */
+ w = (size_t)snprintf(src, 64, "package p\n\n// See [");
+ memset(src + w, 'A', BIG);
+ src[w + 100] = ' ';
+ w += BIG;
+ w += (size_t)snprintf(src + w, 128, "] and [Small].\ntype T struct{}\n");
+ r = cbm_extract_file(src, (int)w, CBM_LANG_GO, "p", "pkg/prose.go", 0, NULL, NULL);
+ ASSERT_NOT_NULL(r);
+ ASSERT_EQ(r->doc_links.count, 1);
+ ASSERT_NOT_NULL(dm_find_token(r, "Small"));
+ cbm_free_result(r);
+
+ /* a megabyte of opening brackets, then one pair: linear, one token */
+ w = (size_t)snprintf(src, 64, "package p\n\n// ");
+ memset(src + w, '[', BIG);
+ w += BIG;
+ w += (size_t)snprintf(src + w, 128, "Deep] end.\ntype T struct{}\n");
+ r = cbm_extract_file(src, (int)w, CBM_LANG_GO, "p", "pkg/deep.go", 0, NULL, NULL);
+ ASSERT_NOT_NULL(r);
+ ASSERT_EQ(r->doc_links.count, 1);
+ ASSERT_NOT_NULL(dm_find_token(r, "Deep"));
+ cbm_free_result(r);
+
+ /* thousands of link definitions and uses: every use resolves to its own
+ * definition (first definition wins), without a quadratic scan */
+ enum { DEFS = 4000 };
+ size_t cap = (size_t)DEFS * 96 + 256;
+ char *many = malloc(cap);
+ ASSERT_NOT_NULL(many);
+ w = (size_t)snprintf(many, cap, "package p\n\n");
+ for (int i = 0; i < DEFS; i++) {
+ w += (size_t)snprintf(many + w, cap - w, "// Use [t%d].\n", i);
+ }
+ w += (size_t)snprintf(many + w, cap - w, "//\n");
+ for (int i = 0; i < DEFS; i++) {
+ w += (size_t)snprintf(many + w, cap - w, "// [t%d]: https://example.com/%d\n", i, i);
+ }
+ w += (size_t)snprintf(many + w, cap - w,
+ "// [t7]: https://example.com/shadowed\n"
+ "type T struct{}\n");
+ r = cbm_extract_file(many, (int)w, CBM_LANG_GO, "p", "pkg/many.go", 0, NULL, NULL);
+ ASSERT_NOT_NULL(r);
+ ASSERT_EQ(r->doc_links.count, DEFS);
+ ASSERT_EQ(dm_count_tokens(r, "https://example.com/7"), 1);
+ ASSERT_NULL(dm_find_token(r, "https://example.com/shadowed"));
+ cbm_free_result(r);
+ free(many);
+
+ /* a NUL byte ends the comment text; what precedes it is still read */
+ static const char nul_src[] = "package p\n\n// See [Before]\0[After].\ntype T struct{}\n";
+ r = cbm_extract_file(nul_src, (int)sizeof(nul_src) - 1, CBM_LANG_GO, "p", "pkg/nul.go", 0, NULL,
+ NULL);
+ ASSERT_NOT_NULL(r);
+ ASSERT_NULL(dm_find_token(r, "After"));
+ cbm_free_result(r);
+ free(src);
+ PASS();
+}
+
+/* A fixed pseudo-random sequence: the same texts on every run and platform. */
+static uint32_t go_rand(uint32_t *state) {
+ *state = (*state * 1664525U) + 1013904223U;
+ return *state >> 8;
+}
+
+/* Append one of `count` pieces, chosen by the sequence. */
+static size_t go_rand_piece(char *buf, size_t len, size_t cap, uint32_t *state,
+ const char *const *pieces, size_t count) {
+ const char *p = pieces[go_rand(state) % count];
+ size_t pl = strlen(p);
+ if (len + pl >= cap) {
+ return len;
+ }
+ memcpy(buf + len, p, pl);
+ return len + pl;
+}
+
+/* Comment text made of the pieces the text model reacts to, in every order:
+ * the parser must stay inside its buffers (the runner has the sanitizers on)
+ * and every token must keep the shape the resolver relies on. */
+TEST(doc_mentions_go_random_docs) {
+ static const char *const pieces[] = {
+ "[",
+ "]",
+ "[",
+ "]",
+ "*",
+ ".",
+ "/",
+ "Name",
+ "pkg",
+ "a/b",
+ " ",
+ " ",
+ "\n// ",
+ "\n//\t",
+ "\n//",
+ "\n//\n// ",
+ "# ",
+ "- ",
+ "1. ",
+ ": ",
+ "https://x",
+ "\xC3\xA9",
+ "\xFF",
+ "\xE2\x80",
+ "\xE2\x80\x9C",
+ "{",
+ "}",
+ "\\",
+ "\r",
+ "\t",
+ "T",
+ "x",
+ "]: ",
+ "[Name]",
+ "[p.Name]",
+ "[a/b.Name.M]",
+ "\n//\n// [Name]: https://x/y\n//\n// ",
+ "/*",
+ "*/",
+ "_",
+ "9",
+ };
+ uint32_t state = 20261002U;
+ char src[4096];
+ int doc_links = 0;
+ int hrefs = 0;
+ for (int round = 0; round < 1500; round++) {
+ size_t len = (size_t)snprintf(src, sizeof(src), "package p\n\n// ");
+ int n = 1 + (int)(go_rand(&state) % 120);
+ for (int i = 0; i < n; i++) {
+ len = go_rand_piece(src, len, sizeof(src) - 64, &state, pieces, GO_COUNT(pieces));
+ }
+ len += (size_t)snprintf(src + len, sizeof(src) - len, "\nfunc F(Name int) {}\n");
+ CBMFileResult *r =
+ cbm_extract_file(src, (int)len, CBM_LANG_GO, "p", "pkg/r.go", 0, NULL, NULL);
+ ASSERT_NOT_NULL(r);
+ for (int k = 0; k < r->doc_links.count; k++) {
+ const CBMDocLink *t = &r->doc_links.items[k];
+ size_t raw_len = t->raw ? strlen(t->raw) : 0;
+ bool shape_ok = t->source_qn && raw_len > 0 && t->line >= 3 &&
+ (t->syntax == CBM_DOCLINK_GO_DOC_LINK || t->syntax == CBM_DOCLINK_HREF);
+ CBMDocLinkGoRef ref;
+ if (shape_ok && t->syntax == CBM_DOCLINK_GO_DOC_LINK) {
+ /* a doc-link token is what the resolver can read back */
+ shape_ok = raw_len <= CBM_DOCLINK_GO_REF_MAX &&
+ cbm_doclink_go_parse_ref(t->raw, raw_len, &ref) &&
+ memchr(t->raw, '\n', raw_len) == NULL;
+ }
+ if (!shape_ok) {
+ printf(" round %d: token [%s] syntax %d line %u\n", round, t->raw ? t->raw : "",
+ (int)t->syntax, t->line);
+ cbm_free_result(r);
+ FAIL("token shape");
+ }
+ doc_links += t->syntax == CBM_DOCLINK_GO_DOC_LINK;
+ hrefs += t->syntax == CBM_DOCLINK_HREF;
+ }
+ cbm_free_result(r);
+ }
+ /* the texts do hold links of both families: the checks above ran */
+ if (doc_links < 1000 || hrefs < 1) {
+ printf(" %d doc links, %d hrefs\n", doc_links, hrefs);
+ FAIL("random texts yield tokens");
+ }
+ PASS();
+}
+
+/* Declarations in every order and state of repair: the scope scan must stay
+ * inside its buffers and write only well-formed records. */
+TEST(doc_mentions_go_random_scopes) {
+ static const char *const pieces[] = {
+ "func ", "type ",
+ "var ", "const ",
+ "import ", "package q\n",
+ "struct ", "interface ",
+ "(", ")",
+ "{", "}",
+ "[", "]",
+ "\n", "\n",
+ "\t", " ",
+ "=", ",",
+ ".", "*",
+ "A", "Bee",
+ "c", "T",
+ "int", "\"a/b\"",
+ "`x`", "//go:build ignore\n",
+ "// c\n", "/* c */",
+ "1", ";",
+ "any", "func (r *T[K]) ",
+ "Bee int", "A, Bee string",
+ };
+ uint32_t state = 20261003U;
+ char src[4096];
+ for (int round = 0; round < 1500; round++) {
+ size_t len =
+ (size_t)snprintf(src, sizeof(src), "%s", (round % 4 == 0) ? "" : "package p\n\n");
+ int n = 1 + (int)(go_rand(&state) % 150);
+ for (int i = 0; i < n; i++) {
+ len = go_rand_piece(src, len, sizeof(src) - 8, &state, pieces, GO_COUNT(pieces));
+ }
+ src[len] = '\0';
+ CBMFileResult *r =
+ cbm_extract_file(src, (int)len, CBM_LANG_GO, "p", "pkg/r.go", 0, NULL, NULL);
+ ASSERT_NOT_NULL(r);
+ const char *s = r->doc_scope;
+ bool ok = s && strncmp(s, "go1", 3) == 0 && (s[3] == '\n' || s[3] == '\0');
+ for (const char *p = ok ? strchr(s, '\n') : NULL; ok && p && p[1];) {
+ const char *line = p + 1;
+ ok = strchr("PIFMTVfmg", line[0]) != NULL && line[1] == '\t' && line[2] != '\0' &&
+ line[2] != '\n';
+ p = strchr(line, '\n');
+ }
+ char *portable = ok ? cbm_doclink_portable_scope(s) : NULL;
+ ok = ok && portable && strstr(portable, "\ng\t") == NULL;
+ cbm_free(CBM_MEM_CLASS_OTHER, portable);
+ if (!ok) {
+ printf(" round %d: scope\n%s\nof\n%s\n", round, s ? s : "(null)", src);
+ cbm_free_result(r);
+ FAIL("scope records");
+ }
+ cbm_free_result(r);
+ }
+ PASS();
+}
+
+/* ── extraction: scope blob ──────────────────────────────────────── */
+
+TEST(doc_mentions_go_scope_blob) {
+ const char *src = "package alpha\n"
+ "\n"
+ "import (\n"
+ "\t\"fmt\"\n"
+ "\tal \"example.com/demo/pkg/alpha\"\n"
+ "\t. \"example.com/dot\"\n"
+ "\t_ \"example.com/blank\"\n"
+ "\tbad \"a\\tb\"\n"
+ ")\n"
+ "import \"io\"\n"
+ "\n"
+ "const Max = 10\n"
+ "const (\n"
+ "\tKindA, KindB = 1, 2\n"
+ ")\n"
+ "var Err = fmt.Errorf(\"x\")\n"
+ "var (\n"
+ "\tBlockVar = 1\n"
+ ")\n"
+ "var hidden = 1\n"
+ "\n"
+ "type Widget struct {\n"
+ "\tName, Size string\n"
+ "\tio.Reader\n"
+ "\t*Kind\n"
+ "\tsecret int\n"
+ "}\n"
+ "type Runner interface {\n"
+ "\tRun() error\n"
+ "\tstop()\n"
+ "\tio.Closer\n"
+ "}\n"
+ "type Kind int\n"
+ "type Alias = al.Widget\n"
+ "type Same = Kind\n"
+ "type List[T any, U comparable] struct{ items []T }\n"
+ "type lower struct{ Field int }\n"
+ "\n"
+ "func New() *Widget { return nil }\n"
+ "func (w *Widget) Run() error { return nil }\n"
+ "func (k Kind) Run() error { return nil }\n"
+ "func (l *List[A, B]) Push(v A) {}\n"
+ "func (x lower) Exported() {}\n"
+ "func Map[K comparable, V any](m map[K]V) {}\n"
+ "func helper() {}\n";
+ CBMFileResult *r = go_extract(src, "pkg/alpha/a.go");
+ ASSERT_NOT_NULL(r);
+ ASSERT_NOT_NULL(r->doc_scope);
+ const char *s = r->doc_scope;
+ ASSERT(strncmp(s, "go1\n", 4) == 0);
+ static const char *const want[] = {
+ "P\talpha\t-",
+ "I\t-\tfmt",
+ "I\t-\tio",
+ "I\tal\texample.com/demo/pkg/alpha",
+ "I\tbad\t?", /* a path this scan cannot record: the qualifier still exists */
+ /* values: the first name of a constant spec or of a parenthesis-free
+ * var has a node (and keeps it: w 1); the others have none (w -) */
+ "V\tMax\t1",
+ "V\tKindA\t1",
+ "V\tKindB\t-",
+ "V\tErr\t1",
+ "V\tBlockVar\t-",
+ /* types; fields (the first name of a declaration has a node, embedded
+ * fields and later names have none); interface methods */
+ "T\tWidget\ts\t-\t1",
+ "f\tWidget\tName\t1",
+ "f\tWidget\tSize\t0",
+ "f\tWidget\tReader\t0",
+ "f\tWidget\tKind\t0",
+ "T\tRunner\ti\t-\t1",
+ "m\tRunner\tRun",
+ "T\tKind\to\t-\t1",
+ "T\tAlias\ta\tal.Widget\t1",
+ "T\tSame\ta\tKind\t1",
+ "T\tList\ts\t-\t1",
+ /* functions and methods; two methods named Run compete for one node
+ * and the later one keeps it */
+ "F\tNew\t1",
+ "F\tMap\t1",
+ "M\tWidget\tRun\t0",
+ "M\tKind\tRun\t1",
+ "M\tList\tPush\t1",
+ "M\tlower\tExported\t1",
+ /* own type parameters, by the declaration's first and last line */
+ "g\t36\t36\tT,U",
+ "g\t42\t42\tA,B",
+ "g\t44\t44\tK,V",
+ };
+ for (size_t i = 0; i < GO_COUNT(want); i++) {
+ if (!go_has_rec(s, want[i])) {
+ printf(" no record \"%s\" in\n%s\n", want[i], s);
+ FAIL("scope record");
+ }
+ }
+ ASSERT_NULL(strstr(s, "example.com/dot")); /* a dot import is no qualifier */
+ ASSERT_NULL(strstr(s, "example.com/blank")); /* nor a blank one */
+ ASSERT_NULL(strstr(s, "hidden"));
+ ASSERT_NULL(strstr(s, "secret"));
+ ASSERT_NULL(strstr(s, "stop"));
+ ASSERT_NULL(strstr(s, "\tlower\tField")); /* unexported type: nothing to name */
+ ASSERT_NULL(strstr(s, "helper"));
+ /* records are sorted: the blob does not depend on declaration order */
+ for (const char *p = strchr(s, '\n'); p && p[1];) {
+ const char *next = strchr(p + 1, '\n');
+ if (next && next[1]) {
+ const char *after = strchr(next + 1, '\n');
+ size_t la = (size_t)(next - p - 1);
+ size_t lb = after ? (size_t)(after - next - 1) : strlen(next + 1);
+ int c = memcmp(p + 1, next + 1, la < lb ? la : lb);
+ ASSERT(c < 0 || (c == 0 && la < lb));
+ }
+ p = next;
+ }
+ /* the persisted scope has no line number: the g records are gone */
+ char *portable = cbm_doclink_portable_scope(s);
+ ASSERT_NOT_NULL(portable);
+ ASSERT_NULL(strstr(portable, "\ng\t"));
+ ASSERT_TRUE(go_has_rec(portable, "M\tKind\tRun\t1"));
+ ASSERT(strncmp(portable, "go1\n", 4) == 0);
+ cbm_free(CBM_MEM_CLASS_OTHER, portable);
+ cbm_free_result(r);
+
+ /* moving declarations changes nothing unless a node changes its owner */
+ const char *a = "package p\n\nfunc (a A) Run() {}\nfunc (b B) Run() {}\nfunc F() {}\n";
+ const char *moved = "package p\n\nfunc F() {}\n\n\nfunc (a A) Run() {}\nfunc (b B) Run() {}\n";
+ const char *swapped = "package p\n\nfunc (b B) Run() {}\nfunc (a A) Run() {}\nfunc F() {}\n";
+ CBMFileResult *ra = go_extract(a, "p/x.go");
+ CBMFileResult *rm = go_extract(moved, "p/x.go");
+ CBMFileResult *rs = go_extract(swapped, "p/x.go");
+ ASSERT_NOT_NULL(ra);
+ ASSERT_NOT_NULL(rm);
+ ASSERT_NOT_NULL(rs);
+ ASSERT_STR_EQ(ra->doc_scope, rm->doc_scope);
+ ASSERT(strcmp(ra->doc_scope, rs->doc_scope) != 0);
+ ASSERT_TRUE(go_has_rec(rs->doc_scope, "M\tA\tRun\t1"));
+ ASSERT_TRUE(go_has_rec(rs->doc_scope, "M\tB\tRun\t0"));
+ cbm_free_result(ra);
+ cbm_free_result(rm);
+ cbm_free_result(rs);
+
+ /* the node <dir>.<name> is one for a function, a type, a value and the
+ * methods of that name: the last declaration keeps it, whatever its kind,
+ * and two on one line contest it */
+ CBMFileResult *k1 = go_extract("package p\n\nfunc Open() {}\nfunc (t T) Open() {}\n", "p/k.go");
+ CBMFileResult *k2 = go_extract("package p\n\nfunc (t T) Open() {}\nfunc Open() {}\n", "p/k.go");
+ CBMFileResult *k3 = go_extract("package p\n\ntype Open int\nvar Open = 1\n"
+ "const Open = 2; func (t T) Open() {}\n",
+ "p/k.go");
+ ASSERT_NOT_NULL(k1);
+ ASSERT_NOT_NULL(k2);
+ ASSERT_NOT_NULL(k3);
+ ASSERT_TRUE(go_has_rec(k1->doc_scope, "F\tOpen\t0"));
+ ASSERT_TRUE(go_has_rec(k1->doc_scope, "M\tT\tOpen\t1"));
+ ASSERT_TRUE(go_has_rec(k2->doc_scope, "F\tOpen\t1"));
+ ASSERT_TRUE(go_has_rec(k2->doc_scope, "M\tT\tOpen\t0"));
+ ASSERT_TRUE(go_has_rec(k3->doc_scope, "T\tOpen\to\t-\t0"));
+ ASSERT_TRUE(go_has_rec(k3->doc_scope, "V\tOpen\t0"));
+ ASSERT_TRUE(go_has_rec(k3->doc_scope, "V\tOpen\tx"));
+ ASSERT_TRUE(go_has_rec(k3->doc_scope, "M\tT\tOpen\tx"));
+ cbm_free_result(k1);
+ cbm_free_result(k2);
+ cbm_free_result(k3);
+
+ /* a build-ignored file, a build-constrained file and a file with a parse
+ * error say so */
+ CBMFileResult *ig =
+ go_extract("//go:build ignore\n\npackage main\n\nfunc Gen() {}\n", "p/gen.go");
+ ASSERT_NOT_NULL(ig);
+ ASSERT_TRUE(go_has_rec(ig->doc_scope, "P\tmain\ti"));
+ cbm_free_result(ig);
+ static const char *const constrained[] = {
+ "//go:build linux && !cgo\n\npackage p\n",
+ "// Copyright.\n\n// +build windows\n\npackage p\n",
+ "//+build darwin\n\npackage p\n",
+ };
+ for (size_t i = 0; i < GO_COUNT(constrained); i++) {
+ CBMFileResult *cr = go_extract(constrained[i], "p/c.go");
+ ASSERT_NOT_NULL(cr);
+ ASSERT_STR_EQ(cr->doc_scope, "go1\nP\tp\tc");
+ cbm_free_result(cr);
+ }
+ static const char *const unconstrained[] = {
+ "package p\n\n//go:build linux\n", /* after the package clause: a comment */
+ "//go:buildx linux\n\npackage p\n", /* no build line */
+ "/* //go:build linux */\n\npackage p\n", /* inside a block comment */
+ };
+ for (size_t i = 0; i < GO_COUNT(unconstrained); i++) {
+ CBMFileResult *fr = go_extract(unconstrained[i], "p/f.go");
+ ASSERT_NOT_NULL(fr);
+ ASSERT_STR_EQ(fr->doc_scope, "go1\nP\tp\t-");
+ cbm_free_result(fr);
+ }
+ CBMFileResult *bad = go_extract("package q\n\nfunc Broken( {\n\tx := \n}\n\nfunc After() {}\n"
+ "type T struct{}\nfunc (t T) M() {}\n",
+ "q/broken.go");
+ ASSERT_NOT_NULL(bad);
+ ASSERT_TRUE(go_has_rec(bad->doc_scope, "P\tq\te"));
+ /* what the extractor still finds after the error, the scan finds too */
+ for (int i = 0; i < bad->defs.count; i++) {
+ const CBMDefinition *d = &bad->defs.items[i];
+ if (!d->name || d->name[0] < 'A' || d->name[0] > 'Z' || !d->label ||
+ strcmp(d->label, "Module") == 0) {
+ continue;
+ }
+ char needle[128];
+ snprintf(needle, sizeof(needle), "\t%s", d->name);
+ const char *hit = strstr(bad->doc_scope, needle);
+ char after = hit ? hit[strlen(needle)] : 'x';
+ if (after != '\t' && after != '\n' && after != '\0') {
+ printf(" %s %s has a definition but no scope record\n", d->label, d->name);
+ FAIL("scope of a file with a parse error");
+ }
+ }
+ cbm_free_result(bad);
+
+ /* go.mod: the module path */
+ const char *mod = "module example.com/demo\n\ngo 1.22\n\nrequire example.com/dep v1.0.0\n";
+ CBMFileResult *gm =
+ cbm_extract_file(mod, (int)strlen(mod), CBM_LANG_GOMOD, "p", "go.mod", 0, NULL, NULL);
+ ASSERT_NOT_NULL(gm);
+ ASSERT_NOT_NULL(gm->doc_scope);
+ ASSERT_STR_EQ(gm->doc_scope, "go1\nG\texample.com/demo");
+ cbm_free_result(gm);
+ PASS();
+}
+
+/* ── the resolver fixture ────────────────────────────────────────── */
+
+static const char GO_ALPHA_A[] =
+ "package alpha\n"
+ "\n"
+ "import (\n"
+ "\t\"fmt\"\n"
+ "\n"
+ "\t\"example.com/demo/alpha/testdata/fixture\"\n"
+ "\t\"example.com/demo/beta\"\n"
+ "\tgam \"example.com/demo/gamma\"\n"
+ "\t\"example.com/demo/realname\"\n"
+ "\t\"example.com/demo/sub/deep\"\n"
+ "\t\"example.com/dep/ext\"\n"
+ "\t\"example.com/other/pkg\"\n"
+ "\tbad \"a\\tb\"\n"
+ ")\n"
+ "\n"
+ "// Widget is the main type. See [New], [Widget.Run], [Runner.Run], [Max],\n"
+ "// [Default] and [Block].\n"
+ "type Widget struct {\n"
+ "\t// Name names it; its size is [Widget.Size].\n"
+ "\tName string\n"
+ "\tSize, Weight int\n"
+ "\tbeta.Embedded\n"
+ "}\n"
+ "\n"
+ "// New makes a [Widget] through [beta.Make] and [gam.Fn]; see [other.Real],\n"
+ "// [deep.Deep], [pkg.Far], [beta.Thing.Do], [beta.Thing.Field],\n"
+ "// [beta.Thing.Second], [beta.Doer.Act], [beta.Gr\xC3\xB6\xC3\x9F"
+ "e], [beta.\xC3\x9C"
+ "ber], [beta] and [bad.T].\n"
+ "func New() *Widget { return nil }\n"
+ "\n"
+ "// Run runs. Plain text: [Make], [Thing], [realname.Real], [gamma.Fn],\n"
+ "// [Widget.Promoted], [Widget.Depth], [Widget.Unknown], [nosuch.Name], [Nope], "
+ "[beta.Fehlt_\xC3\x9F].\n"
+ "// Rows: [beta.Nope], [beta.Thing.Nope], [beta.InBlock], [ext.Thing],\n"
+ "// [fmt.Println], [encoding/json.Marshal], [io], [example.com/demo/nodir.X]\n"
+ "// and [example.com/demo/nested/pkg.Far]. Fields: [Widget.Size], [Widget.Weight], "
+ "[Widget.Embedded].\n"
+ "func (w *Widget) Run() {}\n"
+ "\n"
+ "// Runner runs.\n"
+ "type Runner interface {\n"
+ "\t// Run runs; see [Widget].\n"
+ "\tRun() error\n"
+ "}\n"
+ "\n"
+ "// Max is the maximum.\n"
+ "const Max = 10\n"
+ "\n"
+ "// Default is the default; tests have [Helper].\n"
+ "var Default = New()\n"
+ "\n"
+ "var (\n"
+ "\t// Block is in a block.\n"
+ "\tBlock = 1\n"
+ ")\n"
+ "\n"
+ "// T is a package-level type.\n"
+ "type T struct{}\n"
+ "\n"
+ "// Map shadows: [T] is its own type parameter, [Widget] is not.\n"
+ "func Map[T any](x T) {}\n"
+ "\n"
+ "// Plain has no type parameter: [T] is the type.\n"
+ "func Plain() {}\n"
+ "\n"
+ "// Spec follows the [spec].\n"
+ "//\n"
+ "// [spec]: https://example.com/spec\n"
+ "func Spec() {}\n"
+ "\n"
+ "// Box holds a value.\n"
+ "type Box[T any] struct {\n"
+ "\t// Value is of type [T], the type parameter of Box; [Widget] is a type.\n"
+ "\tValue T\n"
+ "}\n"
+ "\n"
+ "// Fixture names [fixture.Data], which is test data.\n"
+ "func Fixture() {}\n";
+
+static const char GO_ALPHA_B[] =
+ "package alpha\n"
+ "\n"
+ "// Sibling imports nothing: [beta.Thing] and [gam.Fn] are plain text here,\n"
+ "// [Widget] is a link.\n"
+ "func Sibling() {}\n";
+
+static const char GO_ALPHA_C[] = "package alpha\n"
+ "\n"
+ "// A is a.\n"
+ "type A struct{}\n"
+ "\n"
+ "// B is b.\n"
+ "type B struct{}\n"
+ "\n"
+ "// Close closes A; see [Target].\n"
+ "func (A) Close() {}\n"
+ "\n"
+ "// Close closes B; see [Target].\n"
+ "func (B) Close() {}\n"
+ "\n"
+ "// Target is a target; see [A.Close] and [B.Close].\n"
+ "func Target() {}\n"
+ "\n"
+ "// Open is a type that loses its node name to the method below.\n"
+ "type Open struct{}\n"
+ "\n"
+ "// Open opens: a method named like the type.\n"
+ "func (B) Open() {}\n"
+ "\n"
+ "// UsesOpen names [Open] and [B.Open].\n"
+ "func UsesOpen() {}\n";
+
+static const char GO_ALPHA_D[] = "package alpha\n"
+ "\n"
+ "import \"example.com/demo/beta\"\n"
+ "\n"
+ "// Alias is beta's Thing.\n"
+ "type Alias = beta.Thing\n"
+ "\n"
+ "// Same is Alias again.\n"
+ "type Same = Alias\n"
+ "\n"
+ "// Bare names [Alias.Do]: plain text without a package.\n"
+ "func Bare() {}\n"
+ "\n"
+ "type L0 = L1\n"
+ "type L1 = L2\n"
+ "type L2 = L3\n"
+ "type L3 = L4\n"
+ "type L4 = L5\n"
+ "type L5 = L6\n"
+ "type L6 = L7\n"
+ "type L7 = L8\n"
+ "type L8 = L9\n"
+ "type L9 = Deep10\n"
+ "\n"
+ "// Deep10 ends the chain.\n"
+ "type Deep10 struct{}\n"
+ "\n"
+ "// End is its method.\n"
+ "func (Deep10) End() {}\n"
+ "\n"
+ "type CycA = CycB\n"
+ "type CycB = CycA\n";
+
+static const char GO_BETA[] = "package beta\n"
+ "\n"
+ "// Thing is a thing.\n"
+ "type Thing struct {\n"
+ "\t// Field is a field.\n"
+ "\tField int\n"
+ "\tFirst, Second int\n"
+ "}\n"
+ "\n"
+ "// Do does.\n"
+ "func (t Thing) Do() {}\n"
+ "\n"
+ "// Make makes.\n"
+ "func Make() Thing { return Thing{} }\n"
+ "\n"
+ "// Embedded is embedded elsewhere.\n"
+ "type Embedded struct {\n"
+ "\t// Depth is a field of Embedded, promoted where it is embedded.\n"
+ "\tDepth int\n"
+ "}\n"
+ "\n"
+ "// Promoted is promoted through embedding.\n"
+ "func (Embedded) Promoted() {}\n"
+ "\n"
+ "// Gr\xC3\xB6\xC3\x9F"
+ "e has letters beyond ASCII.\n"
+ "type Gr\xC3\xB6\xC3\x9F"
+ "e struct{}\n"
+ "\n"
+ "// \xC3\x9C"
+ "ber starts with a capital letter beyond ASCII: exported.\n"
+ "type \xC3\x9C"
+ "ber struct{}\n"
+ "\n"
+ "var (\n"
+ "\t// InBlock has no node.\n"
+ "\tInBlock = 1\n"
+ ")\n"
+ "\n"
+ "// Doer does.\n"
+ "type Doer interface {\n"
+ "\t// Act acts.\n"
+ "\tAct()\n"
+ "}\n";
+
+static const char GO_GAMMA_K[] =
+ "package gamma\n"
+ "\n"
+ "import \"example.com/demo/alpha\"\n"
+ "\n"
+ "// ViaAlias reaches [alpha.Alias.Do] and [alpha.Same.Field] through aliases;\n"
+ "// [alpha.Alias] is the alias itself, [alpha.Alias.Nope] is nothing,\n"
+ "// [alpha.Widget.Promoted] is promoted and not Widget's own,\n"
+ "// [alpha.Widget.Name] is a field, [alpha.Widget.Weight] a field without a\n"
+ "// node, [alpha.L3.End] is seven aliases away, [alpha.L0.End] ten and\n"
+ "// [alpha.CycA.End] never ends. [alpha.Helper] is test code.\n"
+ "func ViaAlias() {}\n";
+
+/* The module example.com/demo with a nested module of its own path
+ * (sub/), a nested module of another path (nested/) and the packages the
+ * lookup tests need. */
+static void go_write_lookup_fixture(const char *repo) {
+ go_w(repo, "go.mod", "module example.com/demo\n\ngo 1.22\n");
+ go_w(repo, "root.go",
+ "// Package demo is the root. See [alpha.Widget].\n"
+ "package demo\n"
+ "\n"
+ "import \"example.com/demo/alpha\"\n"
+ "\n"
+ "// Root names [example.com/demo], [alpha], [example.com/demo/mixed.F] and\n"
+ "// [example.com/demo/fmt.Println].\n"
+ "func Root() {}\n");
+ go_w(repo, "alpha/doc.go",
+ "// Package alpha is documented here. It builds a [Widget]; printing is\n"
+ "// [fmt.Println] and [nosuch.Thing] is nothing.\n"
+ "// [beta.Thing] is no link here: this file imports nothing, a.go imports beta.\n"
+ "package alpha\n");
+ go_w(repo, "alpha/a.go", GO_ALPHA_A);
+ go_w(repo, "alpha/b.go", GO_ALPHA_B);
+ go_w(repo, "alpha/c.go", GO_ALPHA_C);
+ go_w(repo, "alpha/d.go", GO_ALPHA_D);
+ go_w(repo, "alpha/a_test.go",
+ "package alpha\n"
+ "\n"
+ "// Helper exists only in tests.\n"
+ "type Helper struct{}\n"
+ "\n"
+ "// TestWidget uses [Helper] and [Widget].\n"
+ "func TestWidget() {}\n");
+ go_w(repo, "alpha/x_test.go",
+ "package alpha_test\n"
+ "\n"
+ "import \"example.com/demo/alpha\"\n"
+ "\n"
+ "// Example uses [alpha.Widget]; [Widget] alone is plain text in this package.\n"
+ "func Example() {}\n");
+ go_w(repo, "alpha/testdata/fixture/f.go",
+ "package fixture\n\n// Data is test data; it may name [Data] itself and [Twin].\n"
+ "var Data = 1\n\n// Twin is another value.\nvar Twin = 2\n");
+ go_w(repo, "beta/b.go", GO_BETA);
+ go_w(repo, "gamma/g.go", "package gamma\n\n// Fn is a function.\nfunc Fn() {}\n");
+ go_w(repo, "gamma/h.go",
+ "package gamma\n"
+ "\n"
+ "import \"example.com/demo/fmt\"\n"
+ "\n"
+ "// Local names the repository's own [fmt.Println].\n"
+ "func Local() {}\n");
+ go_w(repo, "gamma/k.go", GO_GAMMA_K);
+ go_w(repo, "realname/r.go", "package other\n\n// Real is real.\nfunc Real() {}\n");
+ go_w(repo, "fmt/f.go",
+ "package fmt\n\n// Println is the repository's own, not the standard library's.\n"
+ "func Println() {}\n");
+ go_w(repo, "log/l.go",
+ "package log\n"
+ "\n"
+ "// Printf prints.\n"
+ "func Printf() {}\n"
+ "\n"
+ "// Use names its own package's [log.Printf], not the standard library's.\n"
+ "func Use() {}\n");
+ go_w(repo, "strings/s.go",
+ "package strings\n"
+ "\n"
+ "import \"strings\"\n"
+ "\n"
+ "// Join joins.\n"
+ "func Join() {}\n"
+ "\n"
+ "// Use imports the standard library's strings: [strings.Join] is that one.\n"
+ "func Use() {}\n");
+ go_w(repo, "sub/go.mod", "module example.com/demo/sub\n");
+ go_w(repo, "sub/deep/d.go", "package deep\n\n// Deep is deep.\nfunc Deep() {}\n");
+ go_w(repo, "nested/go.mod", "module example.com/other\n");
+ go_w(repo, "nested/pkg/p.go", "package pkg\n\n// Far is far.\nfunc Far() {}\n");
+ /* one import name, two packages: each file's own import decides */
+ go_w(repo, "same/a.go",
+ "package same\n\nimport x \"example.com/demo/beta\"\n\n// A names [x.Thing].\nfunc A() "
+ "{}\n");
+ go_w(
+ repo, "same/b.go",
+ "package same\n\nimport x \"example.com/demo/gamma\"\n\n// B names [x.Fn].\nfunc B() {}\n");
+ go_w(repo, "same/doc.go",
+ "// Package same: [x.Thing] is no link in a file without imports.\npackage same\n");
+ go_w(repo, "mixed/a.go", "package p1\n\n// F is p1's.\nfunc F() {}\n");
+ go_w(repo, "mixed/b.go", "package p2\n\n// F is p2's.\nfunc F() {}\n");
+ /* stand-alone programs in one directory: no package */
+ go_w(repo, "progs/one.go",
+ "package main\n\n// Config is one program's.\ntype Config struct{}\n\n"
+ "// Load loads a [Config].\nfunc Load() {}\n");
+ go_w(repo, "progs/two.go",
+ "package main\n\n// Config is another program's.\ntype Config struct{}\n\n"
+ "// Save saves a [Config].\nfunc Save() {}\n");
+ go_w(repo, "progs/three.go",
+ "package main\n\n// Print prints a [Config], whichever.\nfunc Print() {}\n");
+ /* build variants of one function */
+ go_w(repo, "plat/impl_linux.go", "package plat\n\n// Open opens on Linux.\nfunc Open() {}\n");
+ go_w(repo, "plat/impl_windows.go",
+ "package plat\n\n// Open opens on Windows.\nfunc Open() {}\n\n"
+ "// Helper calls [Open].\nfunc Helper() {}\n");
+ go_w(repo, "plat/tagged_a.go",
+ "//go:build a\n\npackage plat\n\n// Tagged is one variant.\nfunc Tagged() {}\n");
+ go_w(repo, "plat/tagged_b.go",
+ "//go:build !a\n\npackage plat\n\n// Tagged is the other variant.\nfunc Tagged() {}\n");
+ go_w(repo, "plat/use.go", "package plat\n\n// Use calls [Open] and [Tagged].\nfunc Use() {}\n");
+ /* a test file's variant keeps the node */
+ go_w(repo, "tw/aa_test.go",
+ "//go:build integration\n\npackage tw\n\n// Shared is the test double.\n"
+ "func Shared() {}\n");
+ go_w(repo, "tw/zz.go",
+ "package tw\n\n// Shared is the product one.\nfunc Shared() {}\n\n"
+ "// Caller calls [Shared].\nfunc Caller() {}\n");
+ /* one name, two kinds */
+ go_w(repo, "amb/x.go", "package amb\n\n// Dual is a function here.\nfunc Dual() {}\n");
+ go_w(repo, "amb/y.go",
+ "//go:build other\n\npackage amb\n\n// Dual is a type there.\ntype Dual struct{}\n");
+ go_w(repo, "amb/z.go", "package amb\n\n// Z names [Dual].\nfunc Z() {}\n");
+ /* a reference longer than a reference can be */
+ char *big = malloc(2048);
+ size_t w = (size_t)snprintf(big, 2048, "package long\n\n// L names [");
+ memset(big + w, 'A', CBM_DOCLINK_GO_REF_MAX + 88);
+ w += CBM_DOCLINK_GO_REF_MAX + 88;
+ snprintf(big + w, 2048 - w,
+ "] and [Other].\nfunc L() {}\n\n// Other is other.\nfunc Other() {}\n");
+ go_w(repo, "long/l.go", big);
+ free(big);
+}
+
+/* Write the lookup fixture below `tmp` and index it into `db`. */
+static int go_index_lookup(char *tmp, size_t tmp_cap, char *db, size_t db_cap) {
+ snprintf(tmp, tmp_cap, "/tmp/cbm_dm_go_XXXXXX");
+ if (!cbm_mkdtemp(tmp)) {
+ return -1;
+ }
+ char repo[400];
+ snprintf(repo, sizeof(repo), "%s/repo", tmp);
+ go_write_lookup_fixture(repo);
+ snprintf(db, db_cap, "%s/go.db", tmp);
+ return dm_index(repo, db, NULL);
+}
+
+/* ── resolver: every reference form, in its first lookup level ───── */
+
+TEST(doc_mentions_go_forms) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ static const go_want_edge_t edges[] = {
+ /* [Name], [Recv.Method], an interface's method, a constant, a variable */
+ {"alpha.Widget", "alpha.New", "unique"},
+ {"alpha.Widget", "alpha.Run", "unique"},
+ {"alpha.Widget", "alpha.Runner.Run", "unique"},
+ {"alpha.Widget", "alpha.Max", "unique"},
+ {"alpha.Widget", "alpha.Default", "unique"},
+ {"alpha.New", "alpha.Widget", "unique"},
+ /* an interface method and a field are sources */
+ {"alpha.Runner.Run", "alpha.Widget", "unique"},
+ /* [pkg.Name]: the file's import, its renamed import, the real package
+ * name of an import whose directory is called otherwise, a nested
+ * module, a module with another path */
+ {"alpha.New", "beta.Make", "exact"},
+ {"alpha.New", "gamma.Fn", "exact"},
+ {"alpha.New", "realname.Real", "exact"},
+ {"alpha.New", "sub.deep.Deep", "exact"},
+ {"alpha.New", "nested.pkg.Far", "exact"},
+ /* [pkg.Recv.Name]: a method, a field, an interface method */
+ {"alpha.New", "beta.Do", "exact"},
+ {"alpha.New", "beta.Thing.Field", "exact"},
+ {"alpha.New", "beta.Doer.Act", "exact"},
+ /* an identifier with letters beyond ASCII */
+ {"alpha.New",
+ "beta.Gr\xC3\xB6\xC3\x9F"
+ "e",
+ "exact"},
+ {"alpha.New",
+ "beta.\xC3\x9C"
+ "ber",
+ "exact"},
+ /* [pkg]: the package's directory node */
+ {"alpha.New", "beta", "exact"},
+ /* an import path */
+ {"Root", "fmt.Println", "exact"},
+ {"Root", "alpha", "exact"},
+ /* test code may name test code; an external test package imports */
+ {"alpha.TestWidget", "alpha.Helper", "unique"},
+ {"alpha.TestWidget", "alpha.Widget", "unique"},
+ {"alpha.Example", "alpha.Widget", "exact"},
+ {"fixture.Data", "fixture.Twin", "unique"}, /* inside a testdata directory */
+ };
+ ASSERT_EQ(go_bad_edges(db, edges, GO_COUNT(edges)), 0);
+ /* the edge's properties, in full */
+ char props[512];
+ int n = 0;
+ dm_edge(db, "alpha.New", "beta.Make", props, sizeof(props), &n);
+ ASSERT_EQ(n, 1);
+ ASSERT_STR_EQ(props, "{\"via\":\"doc_comment\",\"syntax\":\"doc_link\",\"tier\":\"exact\","
+ "\"line\":25,\"count\":1}");
+ /* 12 targets; [bad.T] and [beta.Thing.Second] are rows */
+ ASSERT_EQ(dm_mentions_from(db, "alpha.New"), 12);
+ /* a [Text] with a link definition is the href family: a row, never an edge */
+ char reason[64];
+ char syntax[64];
+ dm_row(db, "alpha/a.go", "https://example.com/spec", reason, sizeof(reason), syntax,
+ sizeof(syntax));
+ ASSERT_STR_EQ(reason, "external");
+ ASSERT_STR_EQ(syntax, "href");
+ ASSERT_EQ(dm_mentions_from(db, "alpha.Spec"), 0);
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: text go/doc renders as text is neither edge nor row ── */
+
+TEST(doc_mentions_go_plain_text) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ const char *a = "alpha/a.go";
+ static const go_want_row_t rows[] = {
+ /* a name the package does not declare, although an imported package
+ * or a sibling directory does */
+ {"alpha/a.go", "Make", ""},
+ {"alpha/a.go", "Thing", ""},
+ {"alpha/a.go", "Nope", ""},
+ /* a qualifier that is no import name of the file: the directory name
+ * of a package called otherwise, the path element of a renamed
+ * import, a word */
+ {"alpha/a.go", "realname.Real", ""},
+ {"alpha/a.go", "gamma.Fn", ""},
+ {"alpha/a.go", "nosuch.Name", ""},
+ /* members the type does not declare itself: a method and a field
+ * promoted through an embedded type, a name nobody declares */
+ {"alpha/a.go", "Widget.Promoted", ""},
+ {"alpha/a.go", "Widget.Depth", ""},
+ {"alpha/a.go", "Widget.Unknown", ""},
+ /* a qualified name with a byte this scan cannot classify */
+ {"alpha/a.go", "beta.Fehlt_\xC3\x9F", ""},
+ /* the file's own imports only: a sibling's import is no qualifier */
+ {"alpha/b.go", "beta.Thing", ""},
+ {"alpha/b.go", "gam.Fn", ""},
+ /* a member through an alias, without a package */
+ {"alpha/d.go", "Alias.Do", ""},
+ /* another package clause in the same directory is another package */
+ {"alpha/x_test.go", "Widget", ""},
+ {"alpha/doc.go", "nosuch.Thing", ""},
+ };
+ ASSERT_EQ(go_bad_rows(db, rows, GO_COUNT(rows)), 0);
+ /* and none of them is an edge: Run's doc holds rows, plain text and one
+ * link, to the field Widget.Size */
+ ASSERT_EQ(dm_mentions_from(db, "alpha.Run"), 1);
+ ASSERT_EQ(dm_mentions_from(db, "alpha.Bare"), 0);
+ static const go_want_edge_t edges[] = {
+ {"alpha.Sibling", "alpha.Widget", "unique"},
+ {"alpha.Sibling", "beta.Thing", ""},
+ {"alpha.Sibling", "gamma.Fn", ""},
+ {"alpha.Example", "alpha.Widget", "exact"},
+ };
+ ASSERT_EQ(go_bad_edges(db, edges, GO_COUNT(edges)), 0);
+ ASSERT_EQ(dm_mentions_from(db, "alpha.Sibling"), 1);
+ ASSERT_STR_EQ(go_reason(db, a, "beta.Nope"), "missing"); /* the fixture is the one meant */
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: struct fields ─────────────────────────────────────── */
+
+/* [Type.Field] binds the field written in that type's own struct declaration,
+ * with or without a package. (Without one, go/doc itself is believed to
+ * render it as plain text: a deliberate difference.) Nothing promoted, and
+ * nothing for a name the type does not declare. */
+TEST(doc_mentions_go_struct_fields) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ static const go_want_edge_t edges[] = {
+ /* the same package: a field named from a method's doc and from a
+ * sibling field's doc */
+ {"alpha.Run", "alpha.Widget.Size", "exact"},
+ {"alpha.Widget.Name", "alpha.Widget.Size", "exact"},
+ /* another package, by its import */
+ {"alpha.New", "beta.Thing.Field", "exact"},
+ {"gamma.ViaAlias", "alpha.Widget.Name", "exact"},
+ /* Depth is a field of beta.Embedded, which Widget embeds: it is no
+ * field of Widget */
+ {"alpha.Run", "beta.Embedded.Depth", ""},
+ };
+ ASSERT_EQ(go_bad_edges(db, edges, GO_COUNT(edges)), 0);
+ /* the promoted field exists as a node: the test above is not vacuous */
+ ASSERT_EQ(dm_count(db,
+ "SELECT COUNT(*) FROM nodes WHERE label = 'Field' AND qualified_name LIKE "
+ "'%.beta.Embedded.Depth'"),
+ 1);
+ static const go_want_row_t rows[] = {
+ {"alpha/a.go", "Widget.Size", ""}, /* an edge, no row */
+ {"alpha/a.go", "Widget.Depth", ""}, /* promoted: plain text */
+ {"alpha/a.go", "Widget.Promoted", ""}, /* a promoted method: plain text */
+ {"alpha/a.go", "Widget.Unknown", ""}, /* nobody's: plain text */
+ /* a field the graph has no node for is a gap, not plain text: the
+ * second name of one declaration, and the embedded field itself */
+ {"alpha/a.go", "Widget.Weight", "graph_gap"},
+ {"alpha/a.go", "Widget.Embedded", "graph_gap"},
+ {"gamma/k.go", "alpha.Widget.Promoted", "missing"}, /* with a package: a broken link */
+ };
+ ASSERT_EQ(go_bad_rows(db, rows, GO_COUNT(rows)), 0);
+ ASSERT_EQ(dm_mentions_from(db, "alpha.Widget.Name"), 1);
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: the package of a qualifier is the FILE's import ───── */
+
+/* The limit of this resolver against go/doc: a qualifier is looked up in the
+ * imports of the documented file only, not in the union of the imports of
+ * the package's files. A package comment in a file without imports (the
+ * usual doc.go) therefore cannot name what only a sibling file imports: no
+ * edge and no row. The other side of the same rule: where two files import
+ * different packages under one name, go/doc links neither, and here each
+ * file's links go through its own import. */
+TEST(doc_mentions_go_file_only_package_lookup) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ static const go_want_row_t rows[] = {
+ {"alpha/doc.go", "beta.Thing", ""}, /* a.go imports beta, doc.go nothing */
+ {"same/doc.go", "x.Thing", ""},
+ {"alpha/b.go", "beta.Thing", ""},
+ {"alpha/b.go", "gam.Fn", ""},
+ };
+ ASSERT_EQ(go_bad_rows(db, rows, GO_COUNT(rows)), 0);
+ static const go_want_edge_t edges[] = {
+ {"alpha.doc.go.__file__", "beta.Thing", ""},
+ {"same.doc.go.__file__", "beta.Thing", ""},
+ {"alpha.Sibling", "beta.Thing", ""},
+ /* the file that does import it links it */
+ {"alpha.New", "beta.Make", "exact"},
+ /* one name, two packages: the file's own import decides */
+ {"same.A", "beta.Thing", "exact"},
+ {"same.B", "gamma.Fn", "exact"},
+ {"same.A", "gamma.Fn", ""},
+ {"same.B", "beta.Thing", ""},
+ };
+ ASSERT_EQ(go_bad_edges(db, edges, GO_COUNT(edges)), 0);
+ /* the package comment's one link is the one to its own package's type */
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "
+ "WHERE e.type = 'MENTIONS' AND s.label = 'File' "
+ "AND s.file_path IN ('alpha/doc.go', 'same/doc.go')"),
+ 1);
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: the local rules ───────────────────────────────────── */
+
+TEST(doc_mentions_go_local_rules) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ static const go_want_edge_t edges[] = {
+ /* the function's own type parameter shadows the package's type T */
+ {"alpha.Map", "alpha.T", ""},
+ {"alpha.Map", "alpha.Widget", "unique"},
+ /* a function without that type parameter means the type */
+ {"alpha.Plain", "alpha.T", "unique"},
+ /* a generic type's parameter is in scope of its fields' docs too */
+ {"alpha.Box.Value", "alpha.T", ""},
+ {"alpha.Box.Value", "alpha.Widget", "unique"},
+ };
+ ASSERT_EQ(go_bad_edges(db, edges, GO_COUNT(edges)), 0);
+ ASSERT_STR_EQ(go_reason(db, "alpha/a.go", "T"), "");
+ ASSERT_EQ(dm_mentions_from(db, "alpha.Map"), 1);
+ ASSERT_EQ(dm_mentions_from(db, "alpha.Box.Value"), 1);
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: one test per level boundary of the package lookup ─── */
+
+TEST(doc_mentions_go_lookup_order) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ /* 1. the file's import beats the package's own name: package strings
+ * imports the standard library's strings */
+ ASSERT_STR_EQ(go_reason(db, "strings/s.go", "strings.Join"), "external");
+ ASSERT_STR_EQ(go_tier(db, "strings.Use", "strings.Join"), "");
+ /* 2. the package's own name beats the standard-library list: package log
+ * without an import of log */
+ ASSERT_STR_EQ(go_tier(db, "log.Use", "log.Printf"), "exact");
+ ASSERT_STR_EQ(go_reason(db, "log/l.go", "log.Printf"), "");
+ /* 3. the standard-library list is the last level: [io] without an import */
+ ASSERT_STR_EQ(go_reason(db, "alpha/a.go", "io"), "external");
+ /* 4. an import decides by its PATH: fmt is the standard library's in a
+ * file that imports "fmt", the repository's own in a file that imports
+ * example.com/demo/fmt */
+ ASSERT_STR_EQ(go_reason(db, "alpha/a.go", "fmt.Println"), "external");
+ ASSERT_STR_EQ(go_tier(db, "alpha.Run", "fmt.Println"), "");
+ ASSERT_STR_EQ(go_tier(db, "gamma.Local", "fmt.Println"), "exact");
+ /* 5. the longest module path decides: a directory inside the root module
+ * that belongs to a nested module of another path is not reachable through
+ * the root module's path */
+ ASSERT_STR_EQ(go_reason(db, "alpha/a.go", "example.com/demo/nested/pkg.Far"), "missing");
+ ASSERT_STR_EQ(go_tier(db, "alpha.New", "nested.pkg.Far"), "exact");
+ ASSERT_STR_EQ(go_tier(db, "alpha.New", "sub.deep.Deep"), "exact");
+ /* 6. the bare name stops at the package: beta.Make is imported and still
+ * no [Make] */
+ ASSERT_STR_EQ(go_tier(db, "alpha.Run", "beta.Make"), "");
+ /* 7. members stop at the type: nothing promoted through embedding */
+ ASSERT_STR_EQ(go_reason(db, "gamma/k.go", "alpha.Widget.Promoted"), "missing");
+ ASSERT_STR_EQ(go_tier(db, "gamma.ViaAlias", "beta.Promoted"), "");
+ /* 8. an alias is followed for a member written with its package, to the
+ * type that declares the member */
+ static const go_want_edge_t alias[] = {
+ {"gamma.ViaAlias", "beta.Do", "exact"},
+ {"gamma.ViaAlias", "beta.Thing.Field", "exact"},
+ {"gamma.ViaAlias", "alpha.Alias", "exact"},
+ {"gamma.ViaAlias", "alpha.End", "exact"}, /* seven aliases away */
+ {"gamma.ViaAlias", "alpha.Widget.Name", "exact"},
+ };
+ ASSERT_EQ(go_bad_edges(db, alias, GO_COUNT(alias)), 0);
+ ASSERT_STR_EQ(go_reason(db, "gamma/k.go", "alpha.Alias.Nope"), "missing");
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: one test per reason ───────────────────────────────── */
+
+TEST(doc_mentions_go_reasons) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ char long_raw[CBM_DOCLINK_GO_REF_MAX + 2];
+ memset(long_raw, 'A', CBM_DOCLINK_GO_REF_MAX + 1);
+ long_raw[CBM_DOCLINK_GO_REF_MAX + 1] = '\0';
+ const go_want_row_t rows[] = {
+ /* external: the standard library by import, a dependency by import,
+ * the standard library by path */
+ {"alpha/a.go", "fmt.Println", "external"},
+ {"alpha/a.go", "ext.Thing", "external"},
+ {"alpha/a.go", "encoding/json.Marshal", "external"},
+ /* missing: a repository package that does not declare the name or the
+ * member; a path inside a module with no package there */
+ {"alpha/a.go", "beta.Nope", "missing"},
+ {"alpha/a.go", "beta.Thing.Nope", "missing"},
+ {"alpha/a.go", "example.com/demo/nodir.X", "missing"},
+ /* graph_gap: declared, but without a node of its own: a variable of a
+ * var block, a later name of a field declaration, the root package
+ * (the Project node is no package node) */
+ {"alpha/a.go", "Block", "graph_gap"},
+ {"alpha/a.go", "beta.InBlock", "graph_gap"},
+ {"alpha/a.go", "beta.Thing.Second", "graph_gap"},
+ {"gamma/k.go", "alpha.Widget.Weight", "graph_gap"},
+ {"root.go", "example.com/demo", "graph_gap"},
+ /* test_only_target: product code naming what only test files declare,
+ * or what a testdata directory holds */
+ {"alpha/a.go", "Helper", "test_only_target"},
+ {"gamma/k.go", "alpha.Helper", "test_only_target"},
+ {"alpha/a.go", "fixture.Data", "test_only_target"},
+ /* ambiguous: one name, a function here and a type there; one
+ * directory, two packages, and nothing that picks one */
+ {"amb/z.go", "Dual", "ambiguous"},
+ {"root.go", "example.com/demo/mixed.F", "ambiguous"},
+ /* unparseable: an import path the scan could not record, an alias
+ * chain that is too long or never ends, a reference that is too long
+ * (never resolved by a prefix) */
+ {"alpha/a.go", "bad.T", "unparseable"},
+ {"gamma/k.go", "alpha.L0.End", "unparseable"},
+ {"gamma/k.go", "alpha.CycA.End", "unparseable"},
+ {"long/l.go", long_raw, "unparseable"},
+ };
+ ASSERT_EQ(go_bad_rows(db, rows, GO_COUNT(rows)), 0);
+ ASSERT_STR_EQ(go_tier(db, "long.L", "long.Other"), "unique");
+ ASSERT_EQ(dm_mentions_from(db, "long.L"), 1);
+ /* every row of the fixture is a Go doc link or a URL */
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM doc_link_unresolved WHERE syntax NOT IN "
+ "('doc_link','href')"),
+ 0);
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: one node name, several declarations ───────────────── */
+
+TEST(doc_mentions_go_node_owner) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ /* Go method nodes have a flat name: A.Close and B.Close share
+ * alpha.Close, and the later declaration keeps it */
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM nodes WHERE qualified_name LIKE '%.alpha.Close'"),
+ 1);
+ ASSERT_STR_EQ(go_tier(db, "alpha.Target", "alpha.Close"), "unique");
+ ASSERT_STR_EQ(go_reason(db, "alpha/c.go", "A.Close"), "graph_gap");
+ ASSERT_STR_EQ(go_reason(db, "alpha/c.go", "B.Close"), "");
+ /* the doc of the method that lost the name is not attributed to the one
+ * that kept it: B.Close's [Target] is the edge, A.Close's a row */
+ char props[512];
+ int n = 0;
+ dm_edge(db, "alpha.Close", "alpha.Target", props, sizeof(props), &n);
+ ASSERT_EQ(n, 1);
+ ASSERT_NOT_NULL(strstr(props, "\"line\":12,\"count\":1"));
+ ASSERT_EQ(dm_count(db, "SELECT line FROM doc_link_unresolved WHERE rel_path = 'alpha/c.go' "
+ "AND raw = 'Target'"),
+ 9);
+ /* a type that lost its name to a method of that name is no target, the
+ * method is */
+ ASSERT_STR_EQ(go_reason(db, "alpha/c.go", "Open"), "graph_gap");
+ ASSERT_STR_EQ(go_tier(db, "alpha.UsesOpen", "alpha.Open"), "unique");
+ ASSERT_EQ(dm_mentions_from(db, "alpha.UsesOpen"), 1);
+
+ /* build variants are one entity: whichever file holds the node */
+ static const go_want_edge_t variants[] = {
+ {"plat.Use", "plat.Open", "unique"},
+ {"plat.Use", "plat.Tagged", "unique"},
+ {"plat.Helper", "plat.Open", "unique"},
+ };
+ ASSERT_EQ(go_bad_edges(db, variants, GO_COUNT(variants)), 0);
+
+ /* two unconstrained files that declare one name are no package: the name
+ * means the file's own declaration, and nothing from elsewhere */
+ ASSERT_STR_EQ(go_tier(db, "progs.Load", "progs.Config"), "unique");
+ ASSERT_STR_EQ(go_reason(db, "progs/two.go", "Config"), "graph_gap");
+ ASSERT_STR_EQ(go_tier(db, "progs.Save", "progs.Config"), "");
+ ASSERT_STR_EQ(go_reason(db, "progs/three.go", "Config"), "ambiguous");
+ ASSERT_STR_EQ(go_tier(db, "progs.Print", "progs.Config"), "");
+
+ /* a node kept by a test file's variant is no target for product code */
+ ASSERT_STR_EQ(go_reason(db, "tw/zz.go", "Shared"), "graph_gap");
+ ASSERT_STR_EQ(go_tier(db, "tw.Caller", "tw.Shared"), "");
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: the package comment, from the File node ───────────── */
+
+TEST(doc_mentions_go_package_comment) {
+ char tmp[256];
+ char db[512];
+ ASSERT_EQ(go_index_lookup(tmp, sizeof(tmp), db, sizeof(db)), 0);
+ /* a reference of the package comment is an edge from the File node */
+ char props[512];
+ int n = 0;
+ dm_edge(db, "alpha.doc.go.__file__", "alpha.Widget", props, sizeof(props), &n);
+ ASSERT_EQ(n, 1);
+ ASSERT_STR_EQ(props, "{\"via\":\"doc_comment\",\"syntax\":\"doc_link\",\"tier\":\"unique\","
+ "\"line\":1,\"count\":1}");
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "
+ "WHERE e.type = 'MENTIONS' AND s.label = 'File' "
+ "AND s.file_path = 'alpha/doc.go'"),
+ 1);
+ /* ... or a row with the file's path and the reference's line */
+ ASSERT_STR_EQ(go_reason(db, "alpha/doc.go", "fmt.Println"), "external");
+ ASSERT_EQ(dm_count(db, "SELECT line FROM doc_link_unresolved WHERE rel_path = 'alpha/doc.go' "
+ "AND raw = 'fmt.Println'"),
+ 2);
+ /* a file with imports: its package comment reads them */
+ ASSERT_STR_EQ(go_tier(db, "root.go.__file__", "alpha.Widget"), "exact");
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── resolver: the repository's own standard library ─────────────── */
+
+TEST(doc_mentions_go_std_module) {
+ char tmp[256];
+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dm_gostd_XXXXXX");
+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+ char repo[400];
+ snprintf(repo, sizeof(repo), "%s/repo", tmp);
+ go_w(repo, "src/go.mod", "module std\n\ngo 1.22\n");
+ go_w(repo, "src/fmt/print.go", "package fmt\n\n// Println prints.\nfunc Println() {}\n");
+ go_w(repo, "src/os/exec/exec.go", "package exec\n\n// Cmd is a command.\ntype Cmd struct{}\n");
+ go_w(repo, "src/log/doc.go",
+ "// Package log links [os/exec.Cmd] by its path and [fmt.Println] by the\n"
+ "// standard library's own name.\n"
+ "package log\n");
+ go_w(repo, "src/log/log.go",
+ "package log\n"
+ "\n"
+ "import (\n"
+ "\t\"fmt\"\n"
+ "\t\"os/exec\"\n"
+ ")\n"
+ "\n"
+ "// Print uses [fmt.Println], [exec.Cmd] and [fmt.Missing].\n"
+ "func Print() {}\n");
+ char db[512];
+ snprintf(db, sizeof(db), "%s/std.db", tmp);
+ ASSERT_EQ(dm_index(repo, db, NULL), 0);
+ /* a package of `module std` is imported by its bare directory path */
+ static const go_want_edge_t edges[] = {
+ {"log.Print", "fmt.Println", "exact"},
+ {"log.Print", "exec.Cmd", "exact"},
+ {"log.doc.go.__file__", "exec.Cmd", "exact"},
+ {"log.doc.go.__file__", "fmt.Println", "exact"},
+ };
+ ASSERT_EQ(go_bad_edges(db, edges, GO_COUNT(edges)), 0);
+ ASSERT_STR_EQ(go_reason(db, "src/log/log.go", "fmt.Missing"), "missing");
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── the ship gate ───────────────────────────────────────────────── */
+
+TEST(doc_mentions_go_ship_gate) {
+ char tmp[256];
+ char db[512];
+ cbm_doclink_test_set_ships(CBM_DOCLINK_GO_DOC_LINK, false);
+ int rc = go_index_lookup(tmp, sizeof(tmp), db, sizeof(db));
+ dm_ship_held_families();
+ ASSERT_EQ(rc, 0);
+ /* a resolved doc link is a row with the gate's reason and no edge */
+ ASSERT_STR_EQ(go_tier(db, "alpha.New", "beta.Make"), "");
+ ASSERT_STR_EQ(go_reason(db, "alpha/a.go", "beta.Make"), "below_bar_tier");
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges WHERE type = 'MENTIONS'"), 0);
+ /* one that does not resolve keeps its own reason; plain text stays nothing */
+ ASSERT_STR_EQ(go_reason(db, "alpha/a.go", "beta.Nope"), "missing");
+ ASSERT_STR_EQ(go_reason(db, "alpha/a.go", "Make"), "");
+ dm_unlink_db(db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── incremental == full ─────────────────────────────────────────── */
+
+#define GO_INC_A_HEAD "package a\n\nimport \"example.com/inc/b\"\n\n"
+#define GO_INC_A_LOCAL "// Local is local.\nfunc Local() {}\n"
+static const char GO_INC_A[] = GO_INC_A_HEAD
+ "// Use names [b.Target], [b.Gone], [b.T.M], [b.W.Name], [b.V.Name] and [Local].\n"
+ "func Use() {}\n\n" GO_INC_A_LOCAL;
+static const char GO_INC_A_DOC_EDIT[] =
+ GO_INC_A_HEAD "// Use names [b.Target], [b.Gone], [b.T.M], [b.W.Name], [b.V.Name], [Local]\n"
+ "// and now [b.T].\n"
+ "func Use() {}\n\n" GO_INC_A_LOCAL;
+static const char GO_INC_OTHER[] = "package a\n\n// Other names [b.Target].\nfunc Other() {}\n";
+static const char GO_INC_OTHER_IMPORT[] =
+ "package a\n\nimport \"example.com/inc/b\"\n\n// Other names [b.Target].\nfunc Other() {}\n";
+static const char GO_INC_DOC[] = "// Package a is documented. See [Local].\npackage a\n";
+static const char GO_INC_DOC_EDIT[] =
+ "// Package a is documented. See [Local] and [Use].\npackage a\n";
+
+#define GO_INC_B_TARGET "// Target is the target.\nfunc Target() {}\n\n"
+#define GO_INC_B_TARGET_BODY "// Target is the target.\nfunc Target() {\n\t_ = 1\n}\n\n"
+#define GO_INC_B_RENAMED "// Renamed was the target.\nfunc Renamed() {}\n\n"
+#define GO_INC_B_GONE "// Gone will go.\nfunc Gone() {}\n\n"
+#define GO_INC_B_T "// T is a type.\ntype T struct{}\n\n"
+#define GO_INC_B_TM "// M is a method of T.\nfunc (T) M() {}\n"
+static const char GO_INC_B[] = "package b\n\n" GO_INC_B_TARGET GO_INC_B_GONE GO_INC_B_T GO_INC_B_TM;
+static const char GO_INC_B_BODY[] =
+ "package b\n\n" GO_INC_B_TARGET_BODY GO_INC_B_GONE GO_INC_B_T GO_INC_B_TM;
+static const char GO_INC_B_NO_GONE[] = "package b\n\n" GO_INC_B_TARGET_BODY GO_INC_B_T GO_INC_B_TM;
+static const char GO_INC_B_NO_M[] = "package b\n\n" GO_INC_B_TARGET_BODY GO_INC_B_T;
+static const char GO_INC_B_RENAME[] = "package b\n\n" GO_INC_B_RENAMED GO_INC_B_T;
+static const char GO_INC_C[] = "package b\n\n// U is another type.\ntype U struct{}\n\n"
+ "// M is U's method; see [Target].\nfunc (U) M() {}\n";
+#define GO_INC_D_HEAD "package b\n\n// V is v.\ntype V struct{}\n\n// W is w.\ntype W struct{}\n\n"
+#define GO_INC_D_V "// Name of V.\nfunc (V) Name() {}\n\n"
+#define GO_INC_D_W "// Name of W.\nfunc (W) Name() {}\n\n"
+static const char GO_INC_D[] = GO_INC_D_HEAD GO_INC_D_V GO_INC_D_W;
+static const char GO_INC_D_SWAPPED[] = GO_INC_D_HEAD GO_INC_D_W GO_INC_D_V;
+
+TEST(doc_mentions_go_incremental_equals_full) {
+ char tmp[256];
+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dm_goinc_XXXXXX");
+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+ char repo[400];
+ snprintf(repo, sizeof(repo), "%s/repo", tmp);
+ go_w(repo, "go.mod", "module example.com/inc\n\ngo 1.22\n");
+ go_w(repo, "a/a.go", GO_INC_A);
+ go_w(repo, "a/doc.go", GO_INC_DOC);
+ go_w(repo, "a/other.go", GO_INC_OTHER);
+ go_w(repo, "b/b.go", GO_INC_B);
+ go_w(repo, "b/c.go", GO_INC_C);
+ go_w(repo, "b/d.go", GO_INC_D);
+ char inc_db[512];
+ char full_db[512];
+ snprintf(inc_db, sizeof(inc_db), "%s/inc.db", tmp);
+ snprintf(full_db, sizeof(full_db), "%s/full.db", tmp);
+ ASSERT_EQ(dm_index(repo, inc_db, NULL), 0);
+ /* the preconditions the steps below move away from */
+ static const go_want_edge_t before[] = {
+ {"a.Use", "b.Target", "exact"}, {"a.Use", "b.Gone", "exact"},
+ {"a.Use", "b.M", "exact"}, /* T.M, in the first file of the directory, keeps b.M */
+ {"a.Use", "b.Name", "exact"}, /* W.Name, the later declaration, keeps b.Name */
+ {"a.Use", "a.Local", "unique"}, {"a.doc.go.__file__", "a.Local", "unique"},
+ {"a.Other", "b.Target", ""}, /* other.go does not import b */
+ };
+ ASSERT_EQ(go_bad_edges(inc_db, before, GO_COUNT(before)), 0);
+ ASSERT_STR_EQ(go_reason(inc_db, "a/a.go", "b.V.Name"), "graph_gap");
+ ASSERT_STR_EQ(go_reason(inc_db, "b/c.go", "Target"), "graph_gap"); /* U.M has no node */
+
+ /* a doc-comment edit re-extracts the file alone */
+ go_w(repo, "a/a.go", GO_INC_A_DOC_EDIT);
+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "doc edit", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);
+ ASSERT_STR_EQ(go_tier(inc_db, "a.Use", "b.T"), "exact");
+
+ /* a body edit in a file other files' references point into: its scope is
+ * unchanged, and the edges into it stand */
+ go_w(repo, "b/b.go", GO_INC_B_BODY);
+ ASSERT_EQ(
+ dm_step(repo, inc_db, full_db, "target body edit", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR),
+ 0);
+ ASSERT_STR_EQ(go_tier(inc_db, "a.Use", "b.Target"), "exact");
+
+ /* a file's imports are its own business: an import edit repairs the file */
+ go_w(repo, "a/other.go", GO_INC_OTHER_IMPORT);
+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "import added", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR),
+ 0);
+ ASSERT_STR_EQ(go_tier(inc_db, "a.Other", "b.Target"), "exact");
+
+ /* a reference added to the package comment: an edge from the File node */
+ go_w(repo, "a/doc.go", GO_INC_DOC_EDIT);
+ ASSERT_EQ(
+ dm_step(repo, inc_db, full_db, "package comment", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);
+ ASSERT_STR_EQ(go_tier(inc_db, "a.doc.go.__file__", "a.Use"), "unique");
+ ASSERT_STR_EQ(go_tier(inc_db, "a.doc.go.__file__", "a.Local"), "unique");
+
+ /* a removed function: the files with an edge into the changed file
+ * re-resolve */
+ go_w(repo, "b/b.go", GO_INC_B_NO_GONE);
+ ASSERT_EQ(
+ dm_step(repo, inc_db, full_db, "function removed", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR),
+ 0);
+ ASSERT_STR_EQ(go_reason(inc_db, "a/a.go", "b.Gone"), "missing");
+
+ /* the method that kept a shared node name goes: the other file's method of
+ * that name takes the node over, and its doc becomes a source */
+ go_w(repo, "b/b.go", GO_INC_B_NO_M);
+ ASSERT_EQ(
+ dm_step(repo, inc_db, full_db, "name keeper removed", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR),
+ 0);
+ ASSERT_STR_EQ(go_reason(inc_db, "a/a.go", "b.T.M"), "missing");
+ ASSERT_STR_EQ(go_tier(inc_db, "b.M", "b.Target"), "unique");
+ ASSERT_STR_EQ(go_reason(inc_db, "b/c.go", "Target"), "");
+
+ /* declaration order decides which declaration keeps a shared name:
+ * swapping two methods moves the node, for files with no edge into it too */
+ go_w(repo, "b/d.go", GO_INC_D_SWAPPED);
+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "methods swapped", CBM_INCREMENTAL_ROUTE_FORCED_FULL),
+ 0);
+ ASSERT_STR_EQ(go_reason(inc_db, "a/a.go", "b.W.Name"), "graph_gap");
+ ASSERT_STR_EQ(go_reason(inc_db, "a/a.go", "b.V.Name"), "");
+
+ /* renaming a target */
+ go_w(repo, "b/b.go", GO_INC_B_RENAME);
+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "rename", CBM_INCREMENTAL_ROUTE_FORCED_FULL), 0);
+ ASSERT_STR_EQ(go_reason(inc_db, "a/a.go", "b.Target"), "missing");
+ ASSERT_STR_EQ(go_reason(inc_db, "a/other.go", "b.Target"), "missing");
+
+ /* a deleted file takes its declarations along */
+ ASSERT_EQ(unlink(TH_PATH(repo, "b/d.go")), 0);
+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "delete file", CBM_INCREMENTAL_ROUTE_FORCED_FULL), 0);
+ ASSERT_STR_EQ(go_reason(inc_db, "a/a.go", "b.V.Name"), "missing");
+
+ /* the module path names every package of the repository */
+ go_w(repo, "go.mod", "module example.com/moved\n\ngo 1.22\n");
+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "module path", CBM_INCREMENTAL_ROUTE_FORCED_FULL), 0);
+ ASSERT_STR_EQ(go_reason(inc_db, "a/a.go", "b.T"), "external");
+
+ dm_unlink_db(inc_db);
+ dm_unlink_db(full_db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+/* ── which scope changes are repairable file by file ─────────────── */
+
+#define GO_DELTA_HEAD "package p\n\nimport \"example.com/m/q\"\n\n"
+#define GO_DELTA_F "// F is.\nfunc F() {}\n\n"
+#define GO_DELTA_G "// G is.\nfunc G() {}\n\n"
+#define GO_DELTA_T "type T struct {\n\tA int\n\tB int\n}\n\n"
+#define GO_DELTA_T_NO_B "type T struct {\n\tA int\n}\n\n"
+#define GO_DELTA_M "func (T) M() {}\n\n"
+#define GO_DELTA_I "type I interface {\n\tDo()\n\tUndo()\n}\n\n"
+#define GO_DELTA_I_NO_UNDO "type I interface {\n\tDo()\n}\n\n"
+#define GO_DELTA_C "const C = 1\n"
+#define GO_DELTA_V "var V = 2\n"
+#define GO_DELTA_REST GO_DELTA_T GO_DELTA_M GO_DELTA_I GO_DELTA_C GO_DELTA_V
+
+TEST(doc_mentions_go_scope_delta_rules) {
+ const char *base = GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_REST;
+ const char *twins = "package p\n\nfunc Open() {}\nfunc (T) Open() {}\n";
+ const char *alias = "package p\n\nimport \"example.com/m/q\"\n\ntype X = q.Y\n";
+ const struct {
+ const char *what;
+ const char *before;
+ const char *after;
+ int want;
+ const char *names;
+ } cases[] = {
+ {"unchanged", base, base, CBM_DOCLINK_DELTA_LOCAL, ""},
+ /* nothing of the persisted scope carries a line number or a body */
+ {"lines moved", base, "// moved\n\n\n" GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_LOCAL, ""},
+ {"body and doc edited", base,
+ GO_DELTA_HEAD "// F is [G].\nfunc F() {\n\t_ = 1\n}\n\n" GO_DELTA_G GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_LOCAL, ""},
+ {"declarations reordered", base, GO_DELTA_HEAD GO_DELTA_G GO_DELTA_F GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_LOCAL, ""},
+ {"unexported declaration added", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G "func helper() {}\n\n" GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_LOCAL, ""},
+ /* the file's imports scope the file itself */
+ {"import added", base,
+ "package p\n\nimport (\n\t\"example.com/m/q\"\n\t\"example.com/m/r\"\n)\n\n" GO_DELTA_F
+ GO_DELTA_G GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_LOCAL, ""},
+ {"import removed", base, "package p\n\n" GO_DELTA_F GO_DELTA_G GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_LOCAL, ""},
+ {"import renamed", base,
+ "package p\n\nimport qq \"example.com/m/q\"\n\n" GO_DELTA_F GO_DELTA_G GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_LOCAL, ""},
+ /* a declaration that only LEFT: its name is reported */
+ {"function removed", base, GO_DELTA_HEAD GO_DELTA_F GO_DELTA_REST, CBM_DOCLINK_DELTA_LOCAL,
+ "G"},
+ {"method removed", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_T GO_DELTA_I GO_DELTA_C GO_DELTA_V,
+ CBM_DOCLINK_DELTA_LOCAL, "M"},
+ {"field removed", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_T_NO_B GO_DELTA_M GO_DELTA_I GO_DELTA_C
+ GO_DELTA_V,
+ CBM_DOCLINK_DELTA_LOCAL, "B"},
+ {"interface method removed", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_T GO_DELTA_M GO_DELTA_I_NO_UNDO GO_DELTA_C
+ GO_DELTA_V,
+ CBM_DOCLINK_DELTA_LOCAL, "Undo"},
+ {"constant removed", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_T GO_DELTA_M GO_DELTA_I GO_DELTA_V,
+ CBM_DOCLINK_DELTA_LOCAL, "C"},
+ /* anything that appears or changes can re-route references in files
+ * with no edge into this one */
+ {"function added", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G "func H() {}\n\n" GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ {"type removed", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_T GO_DELTA_M GO_DELTA_C GO_DELTA_V,
+ CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ {"type changes its kind", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_T GO_DELTA_M
+ "type I struct {\n\tDo int\n\tUndo int\n}\n\n" GO_DELTA_C GO_DELTA_V,
+ CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ {"package clause renamed", base,
+ "package other\n\nimport \"example.com/m/q\"\n\n" GO_DELTA_F GO_DELTA_G GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ {"build constraint added", base,
+ "//go:build linux\n\n" GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_REST,
+ CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ {"variable moved into a block (it loses its node)", base,
+ GO_DELTA_HEAD GO_DELTA_F GO_DELTA_G GO_DELTA_T GO_DELTA_M GO_DELTA_I GO_DELTA_C
+ "var (\n\tV = 2\n)\n",
+ CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ /* the declaration that keeps a shared node name changes */
+ {"same-named declarations swapped", twins,
+ "package p\n\nfunc (T) Open() {}\nfunc Open() {}\n", CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ {"one of two same-named declarations removed", twins, "package p\n\nfunc Open() {}\n",
+ CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ /* other files follow `type X = q.Y` through this file's imports */
+ {"import changed under a qualified alias", alias,
+ "package p\n\nimport q \"example.com/m/other\"\n\ntype X = q.Y\n",
+ CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ /* a file that appears or goes */
+ {"file deleted", base, NULL, CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ {"file added", NULL, base, CBM_DOCLINK_DELTA_GLOBAL, NULL},
+ };
+ for (size_t i = 0; i < GO_COUNT(cases); i++) {
+ char names[256];
+ int got = dm_scope_delta(CBM_LANG_GO, "p/x.go", cases[i].before, cases[i].after, names,
+ sizeof(names));
+ bool names_ok = !cases[i].names || strcmp(names, cases[i].names) == 0;
+ if (got != cases[i].want || !names_ok) {
+ printf(" %s: delta %d names \"%s\", want %d \"%s\"\n", cases[i].what, got, names,
+ cases[i].want, cases[i].names ? cases[i].names : "(any)");
+ FAIL("scope delta");
+ }
+ }
+ /* go.mod: the module path is everybody's scope; the rest of the file is not */
+ char names[256];
+ ASSERT_EQ(dm_scope_delta(CBM_LANG_GOMOD, "go.mod", "module example.com/a\n",
+ "module example.com/b\n", names, sizeof(names)),
+ CBM_DOCLINK_DELTA_GLOBAL);
+ ASSERT_EQ(dm_scope_delta(CBM_LANG_GOMOD, "go.mod", "module example.com/a\n\ngo 1.21\n",
+ "module example.com/a\n\ngo 1.22\n\nrequire example.com/x v1.0.0\n",
+ names, sizeof(names)),
+ CBM_DOCLINK_DELTA_LOCAL);
+ PASS();
+}
+
+/* ── one worker == several workers ───────────────────────────────── */
+
+TEST(doc_mentions_go_workers_agree) {
+ char tmp[256];
+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dm_gopar_XXXXXX");
+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+ char repo[400];
+ snprintf(repo, sizeof(repo), "%s/repo", tmp);
+ go_w(repo, "go.mod", "module example.com/par\n\ngo 1.22\n");
+ enum { PKGS = 12, FILES = 6 }; /* 72 files: past the parallel threshold */
+ for (int p = 0; p < PKGS; p++) {
+ for (int f = 0; f < FILES; f++) {
+ char rel[64];
+ char src[2048];
+ int next = (p + 1) % PKGS;
+ snprintf(rel, sizeof(rel), "p%02d/f%d.go", p, f);
+ snprintf(src, sizeof(src),
+ "package p%02d\n"
+ "\n"
+ "import \"example.com/par/p%02d\"\n"
+ "\n"
+ "// T%d is a type; see [F%d], [T%d.Close], [p%02d.T%d], [p%02d.T%d.Close],\n"
+ "// [p%02d.Gone], [fmt.Println], [Shared] and [Nothing].\n"
+ "type T%d struct{}\n"
+ "\n"
+ "// Close closes T%d; see [T%d].\n"
+ "func (T%d) Close() {}\n"
+ "\n"
+ "// F%d is a function; see [p%02d].\n"
+ "func F%d() {}\n"
+ "\n"
+ "// Shared is declared by every file of the package.\n"
+ "func Shared() {}\n",
+ p, next, f, (f + 1) % FILES, (f + 2) % FILES, next, f, next, (f + 3) % FILES,
+ next, f, f, f, f, f, next, f);
+ go_w(repo, rel, src);
+ }
+ }
+ char par_db[512];
+ char seq_db[512];
+ snprintf(par_db, sizeof(par_db), "%s/par.db", tmp);
+ snprintf(seq_db, sizeof(seq_db), "%s/seq.db", tmp);
+ ASSERT_EQ(dm_workers_agree(repo, par_db, seq_db), 0);
+ /* and the fixture exercises what it should: edges, and rows of more than
+ * one reason */
+ ASSERT_STR_EQ(go_tier(par_db, "p00.T0", "p00.F1"), "unique");
+ ASSERT_STR_EQ(go_tier(par_db, "p00.T0", "p01.T0"), "exact");
+ ASSERT_STR_EQ(go_reason(par_db, "p00/f0.go", "p01.Gone"), "missing");
+ ASSERT_STR_EQ(go_reason(par_db, "p00/f0.go", "fmt.Println"), "external");
+ ASSERT_STR_EQ(go_reason(par_db, "p00/f0.go", "p01.T3.Close"), "graph_gap");
+ ASSERT_STR_EQ(go_reason(par_db, "p00/f3.go", "Shared"), "graph_gap");
+ ASSERT_TRUE(dm_count(par_db, "SELECT COUNT(*) FROM edges WHERE type = 'MENTIONS'") > 100);
+ dm_unlink_db(par_db);
+ dm_unlink_db(seq_db);
+ th_rmtree(tmp);
+ PASS();
+}
+
+SUITE(doc_mentions_go) {
+ dm_ship_held_families();
+ RUN_TEST(doc_mentions_go_tokens);
+ RUN_TEST(doc_mentions_go_sources);
+ RUN_TEST(doc_mentions_go_package_comment_tokens);
+ RUN_TEST(doc_mentions_go_text_model);
+ RUN_TEST(doc_mentions_go_own_parameter);
+ RUN_TEST(doc_mentions_go_hostile_doc);
+ RUN_TEST(doc_mentions_go_random_docs);
+ RUN_TEST(doc_mentions_go_random_scopes);
+ RUN_TEST(doc_mentions_go_scope_blob);
+ RUN_TEST(doc_mentions_go_forms);
+ RUN_TEST(doc_mentions_go_plain_text);
+ RUN_TEST(doc_mentions_go_struct_fields);
+ RUN_TEST(doc_mentions_go_file_only_package_lookup);
+ RUN_TEST(doc_mentions_go_local_rules);
+ RUN_TEST(doc_mentions_go_lookup_order);
+ RUN_TEST(doc_mentions_go_reasons);
+ RUN_TEST(doc_mentions_go_node_owner);
+ RUN_TEST(doc_mentions_go_package_comment);
+ RUN_TEST(doc_mentions_go_std_module);
+ RUN_TEST(doc_mentions_go_ship_gate);
+ RUN_TEST(doc_mentions_go_incremental_equals_full);
+ RUN_TEST(doc_mentions_go_scope_delta_rules);
+ RUN_TEST(doc_mentions_go_workers_agree);
+}
diff --git a/tests/test_doc_mentions_helpers.h b/tests/test_doc_mentions_helpers.h
index 19714fad6..7756b4947 100644
--- a/tests/test_doc_mentions_helpers.h
+++ b/tests/test_doc_mentions_helpers.h
@@ -432,7 +432,7 @@ static inline int dm_reason_lines(const char *db, const char *block) {
static const int DM_HELD_FAMILIES[] = {
CBM_DOCLINK_MD_BARE_PATH, CBM_DOCLINK_MD_SUPERSEDES_PROSE, CBM_DOCLINK_RST_INCLUDE,
CBM_DOCLINK_RST_KERNEL_DOC, CBM_DOCLINK_ADOC_ATTRIBUTE, CBM_DOCLINK_ADOC_CODE_PATH,
- CBM_DOCLINK_ADOC_CODE_NAME,
+ CBM_DOCLINK_ADOC_CODE_NAME, CBM_DOCLINK_GO_DOC_LINK,
};
static inline void dm_ship_held_families(void) {
diff --git a/tests/test_main.c b/tests/test_main.c
index 145e96ef6..d465ba98d 100644
--- a/tests/test_main.c
+++ b/tests/test_main.c
@@ -1825,6 +1825,7 @@ extern void suite_doc_links_md(void);
extern void suite_doc_links_pdf(void);
extern void suite_doc_links_rst(void);
extern void suite_doc_links_adoc(void);
+extern void suite_doc_mentions_go(void);
extern void suite_infrascan(void);
extern void suite_cli(void);
extern void suite_agent_clients(void);
@@ -2296,6 +2297,7 @@ int main(int argc, char **argv) {
RUN_SELECTED_SUITE(doc_links_pdf);
RUN_SELECTED_SUITE(doc_links_rst);
RUN_SELECTED_SUITE(doc_links_adoc);
+ RUN_SELECTED_SUITE(doc_mentions_go);
/* Infrastructure scanning */
RUN_SELECTED_SUITE(infrascan);