Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
doc-links(go): Go doc links become MENTIONS edges, held until their audit
Martin Vogel0c7ca3441904
diff --git a/Makefile.cbm b/Makefile.cbmindex 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.cTEST_WATCHER_SRCS = tests/test_watcher.cdiff --git a/internal/cbm/doclink.c b/internal/cbm/doclink.cindex 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.hindex 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.cnew file mode 100644index 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.cindex 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.hindex 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.cnew file mode 100644index 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.cnew file mode 100644index 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.hindex 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.cindex 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);