Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

doc-links(md): link Markdown sections to the code files and definitions they name

Martin Vogelafedff517624
diff --git a/Makefile.cbm b/Makefile.cbm
index 120746a79..4e365971b 100644
--- a/Makefile.cbm
+++ b/Makefile.cbm
@@ -375,6 +375,7 @@ EXTRACTION_SRCS = \
$(CBM_DIR)/extract_dbt.c \
$(CBM_DIR)/doclink.c \
$(CBM_DIR)/doclink_cs.c \
+ $(CBM_DIR)/doclink_md.c \
$(CBM_DIR)/sql_values.c \
$(CBM_DIR)/helpers.c \
$(CBM_DIR)/cpp_branch_views.c \
@@ -497,6 +498,7 @@ PIPELINE_SRCS = \
src/pipeline/pass_doclinks.c \
src/pipeline/doc_links.c \
src/pipeline/doc_links_cs.c \
+ src/pipeline/doc_links_md.c \
src/pipeline/doc_links_msbuild.c \
src/pipeline/pass_route_nodes.c \
src/pipeline/pass_enrichment.c \
@@ -759,7 +761,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_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_infrascan.c tests/test_worker_pool.c tests/test_parallel.c tests/test_index_resilience.c tests/test_index_format.c tests/test_call_reference_contract.c tests/repro/repro_call_scope_usages.c tests/repro/repro_call_argument_usages.c tests/repro/repro_reference_precision.c tests/repro/repro_lexical_binding_precision.c tests/repro/repro_call_argument_matrix_a.c tests/repro/repro_call_argument_matrix_b.c tests/repro/repro_call_node_behaviors.c tests/repro/repro_language_registry.c tests/repro/repro_call_node_manifest.c tests/repro/repro_lsp_ordered_signatures.c tests/repro/repro_lsp_ordered_local.c tests/repro/repro_ts_overload_return_chains.c tests/repro/repro_harness_cleanup.c tests/repro/repro_runner_filter.c
TEST_WATCHER_SRCS = tests/test_watcher.c
diff --git a/internal/cbm/doclink.c b/internal/cbm/doclink.c
index d7d9b8b41..bf7f695f6 100644
--- a/internal/cbm/doclink.c
+++ b/internal/cbm/doclink.c
@@ -143,6 +143,9 @@ typedef struct {
* the same doc): only the first label carries the doc's references. */
const char *twin_label;
const char *twin_of;
+ /* A document language: the whole file is the documentation, so one scan
+ * of its bytes replaces parse_doc, the file-level doc and the scope. */
+ void (*scan_file)(CBMExtractCtx *ctx);
} doclink_lang_t;
static const doclink_lang_t DOCLINK_LANGS[] = {
@@ -159,6 +162,7 @@ static const doclink_lang_t DOCLINK_LANGS[] = {
.scan_scope = cbm_doclink_cs_project_scan_scope,
.scope_tag = CBM_DOCLINK_CS_SCOPE_TAG,
.portable_scope = cbm_doclink_cs_portable_scope},
+ {.lang = CBM_LANG_MARKDOWN, .scan_file = cbm_doclink_md_scan_file},
};
static const doclink_lang_t *doclink_lang(CBMLanguage lang) {
@@ -388,6 +392,10 @@ void cbm_doclinks_extract(CBMExtractCtx *ctx) {
if (!L) {
return;
}
+ if (L->scan_file) {
+ L->scan_file(ctx);
+ return;
+ }
int twin_count = 0;
doclink_twin_key_t *twins = L->twin_label ? twin_keys(ctx, L->twin_of, &twin_count) : NULL;
CBMDefArray *defs = &ctx->result->defs;
diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.h
index 7b85ad45a..6e5bb035f 100644
--- a/internal/cbm/doclink.h
+++ b/internal/cbm/doclink.h
@@ -22,6 +22,10 @@
* identical on full and incremental runs. Optional.
* scope_tag, the blob's tag line and its persisted form (line
* portable_scope numbers dropped). Optional.
+ * scan_file instead of parse_doc, for a DOCUMENT language whose
+ * text is the documentation (Markdown): one pass over
+ * the file's bytes pushes every reference, with the
+ * section it is written in as its source. Optional.
* State a language's hooks need between their calls for one file lives in
* ctx->doclink_state (cbm.h), never in a static or thread-local.
* A language without a row produces no tokens and no scope. The resolving
@@ -61,6 +65,11 @@
X(CBM_DOCLINK_CS_SEEALSO, CBM_LANG_CSHARP, "seealso", false, true) \
X(CBM_DOCLINK_CS_EXCEPTION, CBM_LANG_CSHARP, "exception", false, true) \
X(CBM_DOCLINK_CS_INHERITDOC, CBM_LANG_CSHARP, "inheritdoc", false, true) \
+ /* markdown (doclink_md.c): what a document's text names explicitly */ \
+ X(CBM_DOCLINK_MD_LINK, CBM_LANG_MARKDOWN, "link", false, true) \
+ X(CBM_DOCLINK_MD_PATH, CBM_LANG_MARKDOWN, "path", false, true) \
+ X(CBM_DOCLINK_MD_CODE_PATH, CBM_LANG_MARKDOWN, "code_path", false, true) \
+ X(CBM_DOCLINK_MD_CODE_NAME, CBM_LANG_MARKDOWN, "code_name", false, true) \
/* any language (CBM_LANG_COUNT): a URL is never an edge */ \
X(CBM_DOCLINK_HREF, CBM_LANG_COUNT, "href", true, false)
@@ -79,7 +88,8 @@ enum {
* edge source is the file's File node, which the resolving half looks up
* from the file it is resolving; `source_qn` is not the source then. Set
* by the driver (cbm_doclinks_extract) on what a parser pushes for the
- * file-level doc -- a parser never sets it. */
+ * file-level doc -- a parser never sets it. A scan_file hook sets it on a
+ * reference written before the document's first section. */
CBM_DOCLINK_FLAG_FILE = 1,
};
@@ -221,4 +231,45 @@ size_t cbm_doclink_cs_norm_type(const char *in, size_t len, char *out, size_t ca
/* The C# scope blob starts with this tag line. */
#define CBM_DOCLINK_CS_SCOPE_TAG "cs1"
+/* ── Markdown (doclink_md.c) ───────────────────────────────────────── */
+
+/* The scan_file hook: every explicit reference of a Markdown or MDX file (a
+ * link destination, a bare path, a path or a qualified name in a code span),
+ * each with the Section definition it is written under as its source. */
+void cbm_doclink_md_scan_file(CBMExtractCtx *ctx);
+
+/* What a code span's text names. */
+typedef enum {
+ CBM_DOCLINK_MD_NONE = 0, /* nothing linkable (a bare name, a command, a snippet, ...) */
+ CBM_DOCLINK_MD_FILE, /* a path with a directory part, or a dot file */
+ CBM_DOCLINK_MD_FILENAME, /* a file name alone: it names a file of the document's
+ * own directory, never one found elsewhere */
+ CBM_DOCLINK_MD_DIR, /* a directory */
+ CBM_DOCLINK_MD_QUALIFIED, /* a qualified name of two or more identifiers
+ * (`a.b`, `a::b`, `A#b`, `A\B`, `mod:attr`) */
+} CBMDocLinkMdShape;
+
+typedef struct {
+ CBMDocLinkMdShape shape;
+ const char *path; /* NUL-terminated, in the caller's buffer; for QUALIFIED the
+ * identifiers joined by '.' */
+ const char *member; /* the text after a `path::`, NUL-terminated in the same
+ * buffer: the member the path's file declares; NULL: none */
+ uint32_t first_line; /* a line range written with the path (`#L3-L9`, `:3-9`, `:3`); */
+ uint32_t last_line; /* 0 and 0 when there is none */
+ bool instance; /* QUALIFIED: written through an instance (`self.x`, `this.x`):
+ * the qualifier is no type, so it never names a field */
+ bool colon; /* QUALIFIED: written `module:attr` (Python's entry-point form) */
+} CBMDocLinkMdPath;
+
+/* Classify the text of a code span. Returns false, with shape NONE, when it
+ * names no path and no qualified name, or when `buf` (cap bytes) cannot hold
+ * it: a name is never cut. Pure: the same text always gives the same answer. */
+bool cbm_doclink_md_classify_span(const char *text, size_t len, char *buf, size_t cap,
+ CBMDocLinkMdPath *out);
+
+/* Parse a `#L3`, `#L3-L9` or `#L3C2-L9C5` fragment (without the `#`): true
+ * and the lines, or false. */
+bool cbm_doclink_md_line_fragment(const char *frag, uint32_t *first, uint32_t *last);
+
#endif /* CBM_DOCLINK_H */
diff --git a/internal/cbm/doclink_md.c b/internal/cbm/doclink_md.c
new file mode 100644
index 000000000..0cd2d350f
--- /dev/null
+++ b/internal/cbm/doclink_md.c
@@ -0,0 +1,1788 @@
+/*
+ * doclink_md.c — Markdown references to code: the extraction half.
+ *
+ * In a Markdown document the text IS the documentation, so its references are
+ * not taken from a definition's doc comment: one pass over the file's bytes
+ * finds the explicit ones and gives each to the section it is written in --
+ * the Section definition (a heading) at or above its line, or the file itself
+ * for text before the first heading (CBM_DOCLINK_FLAG_FILE). Families
+ * (doclink.h):
+ *
+ * link the destination of an inline link `[text](dest)` or of a link
+ * reference definition `[label]: dest`, when it is no URL, no
+ * in-page anchor and no image
+ * path a bare path in prose: a slash and a file extension
+ * code_path a code span, or an HTML <code> span, whose text is a path, a
+ * file name or a directory, with an optional line range
+ * (`#L3-L9`, `:3-9`) or member (`path::Name`)
+ *
+ * Never scanned: YAML front matter, fenced code blocks, HTML comments, the
+ * import/export lines of MDX. Never a reference here: a URL, an in-page
+ * anchor, an image, a name without a path (a bare name is at most a
+ * suggestion, never an edge).
+ *
+ * Cost. Each scan of a line is linear in the line, or n log n where it sorts.
+ * The searches that could otherwise rescan a stretch of the line for every
+ * candidate (the end of a link destination, the closing parenthesis, the
+ * closing backticks of a code span) are answered from position lists of the
+ * few bytes they look for, by binary search. The lists grow with the number
+ * of those bytes, not with the line, and are released at the end of the
+ * file. A list that cannot grow marks the file's doc links failed, so the
+ * resolving half fails the layer instead of publishing a graph that silently
+ * misses references.
+ *
+ * The rules are those the documentation field tests measured (H0): explicit
+ * paths and links bind EXACTLY, at 99 % precision on 53 repositories.
+ */
+#include "doclink.h"
+
+#include "arena.h"
+#include "foundation/constants.h"
+#include "foundation/mem_core.h"
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define MD_SLEN(s) (sizeof(s) - SKIP_ONE)
+
+enum {
+ MD_MASK = 0x01, /* a byte the later scans of the line must not see */
+ MD_FENCE_MIN = 3, /* ``` or ~~~ */
+ MD_INDENT_MAX = 3, /* a link reference definition may be indented this far */
+ MD_SPAN_MAX = 150, /* longer code-span text is a snippet, not a name */
+ MD_EXT_MAX = 12, /* a file extension: a letter and at most 11 more */
+ MD_TAG_MAX = 200, /* an HTML tag inside a <code> span is at most this long */
+ MD_CALL_ARGS = 60, /* `name(args)`: the argument text of a call form */
+ MD_CALL_ARGS_WIDE = 80, /* the same with spaces or commas in the arguments */
+ MD_TINY_DOTFILE = 3, /* `.a` is no file name, `.ab` is */
+ MD_LIST_INIT = 16, /* first capacity of a position list */
+ MD_NUM_DIGITS = 9, /* a line number has at most this many digits */
+ MD_PAIR = 2, /* ints per pair entry */
+ MD_URL_SCHEMES = 3, /* http, https, ftp */
+};
+
+/* UTF-8 well-formedness (RFC 3629, table 3-7 of the Unicode standard). */
+enum {
+ UTF8_CTRL_END = 0x20,
+ UTF8_DEL = 0x7f,
+ UTF8_ASCII_END = 0x80,
+ UTF8_CONT_MIN = 0x80,
+ UTF8_CONT_MAX = 0xBF,
+ UTF8_LEAD2_MIN = 0xC2,
+ UTF8_LEAD2_MAX = 0xDF,
+ UTF8_LEAD3_MIN = 0xE0,
+ UTF8_LEAD3_MAX = 0xEF,
+ UTF8_E0_SECOND_MIN = 0xA0,
+ UTF8_SURROGATE_LEAD = 0xED,
+ UTF8_ED_SECOND_MAX = 0x9F,
+ UTF8_LEAD4_MIN = 0xF0,
+ UTF8_LEAD4_MAX = 0xF4,
+ UTF8_F0_SECOND_MIN = 0x90,
+ UTF8_F4_SECOND_MAX = 0x8F,
+};
+
+/* ── Small character classes (ASCII; bytes >= 0x80 are word bytes) ── */
+
+static bool md_blank(unsigned char c) {
+ return c == ' ' || c == '\t' || c == '\r' || c == '\n' || c == '\f' || c == '\v';
+}
+
+static bool md_sp_tab(unsigned char c) {
+ return c == ' ' || c == '\t';
+}
+
+static bool md_alpha(unsigned char c) {
+ return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+}
+
+static bool md_digit(unsigned char c) {
+ return c >= '0' && c <= '9';
+}
+
+static bool md_alnum(unsigned char c) {
+ return md_alpha(c) || md_digit(c);
+}
+
+/* Python's \w on text: letters, digits, '_' and any non-ASCII byte. */
+static bool md_word(unsigned char c) {
+ return md_alnum(c) || c == '_' || c >= 0x80;
+}
+
+static unsigned char md_lower(unsigned char c) {
+ return (c >= 'A' && c <= 'Z') ? (unsigned char)(c - 'A' + 'a') : c;
+}
+
+static bool md_has(const char *s, size_t n, char c) {
+ return n > 0 && memchr(s, c, n) != NULL;
+}
+
+static bool md_eq_ci(const char *s, size_t n, const char *word) {
+ size_t w = strlen(word);
+ if (n != w) {
+ return false;
+ }
+ for (size_t i = 0; i < n; i++) {
+ if (md_lower((unsigned char)s[i]) != (unsigned char)word[i]) {
+ return false;
+ }
+ }
+ return true;
+}
+
+static bool md_in_list(const char *s, size_t n, const char *const *list, bool ci) {
+ for (size_t i = 0; list[i]; i++) {
+ if (ci ? md_eq_ci(s, n, list[i]) : (strlen(list[i]) == n && memcmp(s, list[i], n) == 0)) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/* File extensions that make a dotted token a FILE NAME. Strict: none of them
+ * is a common member name (`.log`, `.get` and `.map` are not here). */
+static const char *const MD_FILE_EXT[] = {
+ "py", "pyi", "js", "jsx", "mjs", "cjs", "ts",
+ "tsx", "mts", "cts", "go", "rs", "c", "h",
+ "cc", "cpp", "cxx", "hpp", "hh", "java", "kt",
+ "kts", "scala", "groovy", "cs", "php", "rb", "sh",
+ "bash", "zsh", "ps1", "md", "mdx", "rst", "adoc",
+ "txt", "json", "jsonc", "yaml", "yml", "toml", "ini",
+ "cfg", "xml", "html", "htm", "css", "scss", "sass",
+ "less", "vue", "svelte", "proto", "sql", "lock", "gradle",
+ "csproj", "sln", "fsproj", "props", "targets", "cmake", "mk",
+ "tf", "tfvars", "hcl", "png", "jpg", "jpeg", "gif",
+ "svg", "pdf", "ipynb", "dockerfile", "swift", "dart", "lua",
+ "pl", "pm", "ex", "exs", "erl", "clj", "hs",
+ "ml", "zig", "sol", "graphql", "gql", "bzl", "nix",
+ "plist", "env", "conf", "properties", "editorconfig", "gitignore", "npmrc",
+ "nvmrc", "j2", "jinja", "tmpl", "tpl", "erb", "hbs",
+ "mustache", "patch", "diff", "whl", "jar", "zip", "gz",
+ "tgz", "so", "dll", "dylib", "wasm", "service", "socket",
+ "timer", "mod", "sum", NULL};
+
+/* File names that are files without an extension. */
+static const char *const MD_SPECIAL_FILES[] = {
+ "Makefile", "Dockerfile", "Containerfile", "Jenkinsfile", "Vagrantfile", "Gemfile", "Rakefile",
+ "Procfile", "Kconfig", "CODEOWNERS", "MAINTAINERS", "LICENSE", "NOTICE", "go.mod",
+ "go.sum", "Cargo.lock", "Justfile", "BUILD", "WORKSPACE", NULL};
+
+/* Host names written as code: a site, not a file. */
+static const char *const MD_DOMAINS[] = {"docs.rs", "crates.io", "pkg.go.dev",
+ "npmjs.com", "pypi.org", "github.com",
+ "gitlab.com", "readthedocs.io", "rubygems.org",
+ "nuget.org", "go.dev", "golang.org",
+ "godoc.org", "packagist.org", "hex.pm",
+ "mvnrepository.com", "docs.python.org", NULL};
+
+/* `.ext`, a letter and up to 11 of [A-Za-z0-9_+-], at the end of `s`. */
+static bool md_ext_ok(const char *s, size_t n) {
+ const char *dot = NULL;
+ for (size_t i = n; i > 0; i--) {
+ if (s[i - SKIP_ONE] == '.') {
+ dot = s + i - SKIP_ONE;
+ break;
+ }
+ }
+ if (!dot) {
+ return false;
+ }
+ size_t ext_len = n - (size_t)(dot - s) - SKIP_ONE;
+ if (ext_len == 0 || ext_len > MD_EXT_MAX || !md_alpha((unsigned char)dot[SKIP_ONE])) {
+ return false;
+ }
+ for (size_t i = 2; i <= ext_len; i++) {
+ unsigned char c = (unsigned char)dot[i];
+ if (!md_alnum(c) && c != '_' && c != '+' && c != '-') {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* `^[A-Za-z][A-Za-z0-9+.-]*://`, `mailto:` or `www.`. */
+static bool md_is_url(const char *s, size_t n) {
+ if (n >= MD_SLEN("mailto:") && md_eq_ci(s, MD_SLEN("mailto:"), "mailto:")) {
+ return true;
+ }
+ if (n >= MD_SLEN("www.") && md_eq_ci(s, MD_SLEN("www."), "www.")) {
+ return true;
+ }
+ if (n == 0 || !md_alpha((unsigned char)s[0])) {
+ return false;
+ }
+ size_t i = SKIP_ONE;
+ while (i < n && (md_alnum((unsigned char)s[i]) || s[i] == '+' || s[i] == '.' || s[i] == '-')) {
+ i++;
+ }
+ return i + MD_SLEN("://") <= n && memcmp(s + i, "://", MD_SLEN("://")) == 0;
+}
+
+/* `^[A-Za-z_$][\w$]*$` */
+static bool md_ident(const char *s, size_t n) {
+ if (n == 0) {
+ return false;
+ }
+ unsigned char c0 = (unsigned char)s[0];
+ if (!(md_alpha(c0) || c0 == '_' || c0 == '$' || c0 >= 0x80)) {
+ return false;
+ }
+ for (size_t i = SKIP_ONE; i < n; i++) {
+ if (!md_word((unsigned char)s[i]) && s[i] != '$') {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* Every byte of s[0..n) is a word byte or one of `extra`. */
+static bool md_all_of(const char *s, size_t n, const char *extra) {
+ if (n == 0) {
+ return false;
+ }
+ for (size_t i = 0; i < n; i++) {
+ if (!md_word((unsigned char)s[i]) && !strchr(extra, s[i])) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* ── Line numbers written with a path ────────────────────────────── */
+
+/* The decimal number s[0..n): false when it is empty, not all digits or too
+ * long to be a line. */
+static bool md_number(const char *s, size_t n, uint32_t *out) {
+ if (n == 0 || n > MD_NUM_DIGITS) {
+ return false;
+ }
+ uint32_t v = 0;
+ for (size_t i = 0; i < n; i++) {
+ if (!md_digit((unsigned char)s[i])) {
+ return false;
+ }
+ v = (v * CBM_DECIMAL_BASE) + (uint32_t)(s[i] - '0');
+ }
+ *out = v;
+ return v > 0;
+}
+
+/* Digits ending at s[end): their start. */
+static size_t md_digits_back(const char *s, size_t end) {
+ size_t i = end;
+ while (i > 0 && md_digit((unsigned char)s[i - SKIP_ONE])) {
+ i--;
+ }
+ return i;
+}
+
+bool cbm_doclink_md_line_fragment(const char *frag, uint32_t *first, uint32_t *last) {
+ /* L<a>[C<c>][-[L]<b>[C<c>]] */
+ if (!frag || frag[0] != 'L') {
+ return false;
+ }
+ const char *p = frag + SKIP_ONE;
+ const char *q = p;
+ while (md_digit((unsigned char)*q)) {
+ q++;
+ }
+ uint32_t a = 0;
+ if (!md_number(p, (size_t)(q - p), &a)) {
+ return false;
+ }
+ if (*q == 'C') {
+ q++;
+ while (md_digit((unsigned char)*q)) {
+ q++;
+ }
+ }
+ uint32_t b = a;
+ if (*q == '-') {
+ q++;
+ if (*q == 'L') {
+ q++;
+ }
+ p = q;
+ while (md_digit((unsigned char)*q)) {
+ q++;
+ }
+ if (!md_number(p, (size_t)(q - p), &b)) {
+ return false;
+ }
+ if (*q == 'C') {
+ q++;
+ while (md_digit((unsigned char)*q)) {
+ q++;
+ }
+ }
+ }
+ if (*q != '\0') {
+ return false;
+ }
+ *first = a;
+ *last = b < a ? a : b;
+ return true;
+}
+
+/* A line range at the end of p[0..*n): `#L<a>[-[L]<b>]`, `:<a>`, `:<a>-<b>`
+ * or `:<a>:<b>`. On a match the range is cut off (*n shrinks). */
+static bool md_line_suffix(const char *p, size_t *n, uint32_t *first, uint32_t *last) {
+ size_t len = *n;
+ /* `#L` form: the last '#' */
+ for (size_t i = len; i > 0; i--) {
+ if (p[i - SKIP_ONE] != '#') {
+ continue;
+ }
+ size_t h = i - SKIP_ONE;
+ if (h + SKIP_ONE < len && p[h + SKIP_ONE] == 'L') {
+ size_t a0 = h + PAIR_LEN;
+ size_t a1 = a0;
+ while (a1 < len && md_digit((unsigned char)p[a1])) {
+ a1++;
+ }
+ uint32_t a = 0;
+ if (md_number(p + a0, a1 - a0, &a)) {
+ uint32_t b = a;
+ size_t k = a1;
+ bool ok = k == len;
+ if (!ok && p[k] == '-') {
+ k++;
+ if (k < len && p[k] == 'L') {
+ k++;
+ }
+ ok = md_number(p + k, len - k, &b);
+ }
+ if (ok) {
+ *first = a;
+ *last = b < a ? a : b;
+ *n = h;
+ return true;
+ }
+ }
+ }
+ break;
+ }
+ /* `:` form: digits at the end */
+ size_t d2 = md_digits_back(p, len);
+ uint32_t b = 0;
+ if (d2 == len || d2 == 0 || !md_number(p + d2, len - d2, &b)) {
+ return false;
+ }
+ char sep = p[d2 - SKIP_ONE];
+ if (sep == '-' || sep == ':') {
+ size_t d1 = md_digits_back(p, d2 - SKIP_ONE);
+ uint32_t a = 0;
+ if (d1 > 0 && d1 < d2 - SKIP_ONE && p[d1 - SKIP_ONE] == ':' &&
+ md_number(p + d1, d2 - SKIP_ONE - d1, &a)) {
+ *first = a;
+ *last = b < a ? a : b;
+ *n = d1 - SKIP_ONE;
+ return true;
+ }
+ }
+ if (sep == ':') {
+ *first = b;
+ *last = b;
+ *n = d2 - SKIP_ONE;
+ return true;
+ }
+ return false;
+}
+
+/* ── Code-span classification ────────────────────────────────────── */
+
+/* Drop one trailing balanced `<...>` or `[...]` (type arguments). */
+static size_t md_strip_generics(const char *s, size_t n) {
+ static const char pairs[][PAIR_LEN] = {{'<', '>'}, {'[', ']'}};
+ for (size_t p = 0; p < sizeof(pairs) / sizeof(pairs[0]); p++) {
+ char o = pairs[p][0];
+ char c = pairs[p][SKIP_ONE];
+ if (n == 0 || s[n - SKIP_ONE] != c || !md_has(s, n, o)) {
+ continue;
+ }
+ int depth = 0;
+ for (size_t k = n; k > 0; k--) {
+ char ch = s[k - SKIP_ONE];
+ if (ch == c) {
+ depth++;
+ } else if (ch == o) {
+ depth--;
+ if (depth == 0) {
+ if (k - SKIP_ONE > 0) {
+ return k - SKIP_ONE;
+ }
+ break;
+ }
+ }
+ }
+ return n;
+ }
+ return n;
+}
+
+/* `name(args)` with a short argument list that holds no parenthesis: the
+ * callee's length, or 0. `wide` is the first form of the field test (args
+ * with a space or comma, up to 80 bytes, callee [\w$.:#\\]); otherwise the
+ * second (args up to 60 bytes, callee [\w$.:#\\<>\[\]!~&*-]). */
+static size_t md_callee(const char *s, size_t n, bool wide) {
+ if (n < PAIR_LEN || s[n - SKIP_ONE] != ')') {
+ return 0;
+ }
+ size_t open = n;
+ for (size_t i = n - SKIP_ONE; i > 0; i--) {
+ char c = s[i - SKIP_ONE];
+ if (c == ')') {
+ return 0;
+ }
+ if (c == '(') {
+ open = i - SKIP_ONE;
+ break;
+ }
+ }
+ if (open == n || open == 0) {
+ return 0;
+ }
+ size_t args = n - open - PAIR_LEN;
+ if (args > (wide ? (size_t)MD_CALL_ARGS_WIDE : (size_t)MD_CALL_ARGS)) {
+ return 0;
+ }
+ if (wide && !md_has(s + open + SKIP_ONE, args, ' ') &&
+ !md_has(s + open + SKIP_ONE, args, ',')) {
+ return 0;
+ }
+ return md_all_of(s, open, wide ? "$.:#\\" : "$.:#\\<>[]!~&*-") ? open : 0;
+}
+
+static void md_shape(CBMDocLinkMdPath *out, CBMDocLinkMdShape shape, const char *path,
+ const char *member, uint32_t first, uint32_t last) {
+ out->shape = shape;
+ out->path = path;
+ out->member = member;
+ out->first_line = first;
+ out->last_line = last;
+ out->instance = false;
+ out->colon = false;
+}
+
+/* The path branch: `s` has a slash (or a Windows path with an extension). */
+static bool md_classify_path(char *s, size_t n, CBMDocLinkMdPath *out) {
+ for (size_t i = 0; i < n; i++) {
+ if (s[i] == '\\') {
+ s[i] = '/';
+ }
+ }
+ if (n >= PAIR_LEN && s[0] == '/' && s[SKIP_ONE] == '/') {
+ return false;
+ }
+ uint32_t first = 0;
+ uint32_t last = 0;
+ (void)md_line_suffix(s, &n, &first, &last);
+ s[n] = '\0';
+ const char *member = NULL;
+ char *sep = strstr(s, "::");
+ if (sep) {
+ *sep = '\0';
+ member = sep + PAIR_LEN;
+ n = (size_t)(sep - s);
+ if (!member[0]) {
+ member = NULL;
+ }
+ }
+ if (n == 0) {
+ return false;
+ }
+ /* an import path (`github.com/x/y`, `k8s.io/client-go`): a host-like first
+ * segment -- dot-separated word groups -- and a last segment (as written,
+ * a trailing slash leaves it empty) without a file extension */
+ size_t host = 0;
+ while (host < n && s[host] != '/') {
+ host++;
+ }
+ bool hostlike = host > 0 && host < n && md_has(s, host, '.') && md_all_of(s, host, ".-") &&
+ s[0] != '.' && s[host - SKIP_ONE] != '.';
+ for (size_t i = 0; hostlike && i + SKIP_ONE < host; i++) {
+ hostlike = !(s[i] == '.' && s[i + SKIP_ONE] == '.');
+ }
+ size_t tail = n;
+ while (tail > 0 && s[tail - SKIP_ONE] != '/') {
+ tail--;
+ }
+ if (hostlike && !md_ext_ok(s + tail, n - tail)) {
+ return false;
+ }
+ /* the base name, after any trailing slashes */
+ size_t end = n;
+ while (end > 0 && s[end - SKIP_ONE] == '/') {
+ end--;
+ }
+ size_t base = end;
+ while (base > 0 && s[base - SKIP_ONE] != '/') {
+ base--;
+ }
+ const char *last_seg = s + base;
+ size_t last_len = end - base;
+ if (!md_all_of(s, n, "./@+~-")) {
+ return false;
+ }
+ if (s[n - SKIP_ONE] == '/') {
+ md_shape(out, CBM_DOCLINK_MD_DIR, s, NULL, 0, 0);
+ return true;
+ }
+ const char *dot = last_len > 0 ? memchr(last_seg, '.', last_len) : NULL;
+ if (dot && last_seg[0] != '.') {
+ const char *ext = strrchr(last_seg, '.') + SKIP_ONE;
+ size_t ext_len = (size_t)(last_seg + last_len - ext);
+ if (ext_len > 0 && ext[0] >= 'A' && ext[0] <= 'Z' && md_ident(ext, ext_len) &&
+ !md_in_list(ext, ext_len, MD_FILE_EXT, true)) {
+ return false; /* `pkg/Type.Member`: a name, not a file (a later rung) */
+ }
+ if (md_ext_ok(last_seg, last_len)) {
+ md_shape(out, CBM_DOCLINK_MD_FILE, s, member, first, last);
+ return true;
+ }
+ }
+ if (last_len > SKIP_ONE && last_seg[0] == '.') {
+ md_shape(out, CBM_DOCLINK_MD_FILE, s, NULL, first, last);
+ return true;
+ }
+ md_shape(out, CBM_DOCLINK_MD_DIR, s, NULL, 0, 0);
+ return true;
+}
+
+static const char *const MD_RUST_ROOTS[] = {"crate", "self", "super", "Self", NULL};
+static const char *const MD_INSTANCE_ROOTS[] = {"self", "this", "cls", "$this", NULL};
+
+/* Split s[0..n) at every `sep`, check that each piece is an identifier (type
+ * arguments dropped), and join the pieces with '.' in place. A first piece in
+ * `skip_first` (Rust's `crate`, an instance's `self`) is dropped and *skipped
+ * says so. False when a piece is no identifier or fewer than two remain. */
+static bool md_join(char *s, size_t n, const char *sep, const char *const *skip_first,
+ bool *skipped, CBMDocLinkMdPath *out) {
+ size_t sl = strlen(sep);
+ size_t pieces = 0;
+ size_t w = 0;
+ size_t i = 0;
+ *skipped = false;
+ for (;;) {
+ size_t e = i;
+ while (e + sl <= n && memcmp(s + e, sep, sl) != 0) {
+ e++;
+ }
+ bool last_piece = e + sl > n;
+ if (last_piece) {
+ e = n;
+ }
+ size_t len = md_strip_generics(s + i, e - i);
+ if (pieces == 0 && !*skipped && skip_first && !last_piece &&
+ md_in_list(s + i, len, skip_first, false)) {
+ *skipped = true;
+ } else {
+ if (!md_ident(s + i, len)) {
+ return false;
+ }
+ if (w > 0) {
+ s[w++] = '.';
+ }
+ memmove(s + w, s + i, len);
+ w += len;
+ pieces++;
+ }
+ if (last_piece) {
+ break;
+ }
+ i = e + sl;
+ }
+ s[w] = '\0';
+ if (pieces < PAIR_LEN) {
+ return false;
+ }
+ md_shape(out, CBM_DOCLINK_MD_QUALIFIED, s, NULL, 0, 0);
+ return true;
+}
+
+/* `main.rs::run`: a file name with a member (an identifier). */
+static bool md_filename_member(char *s, char *sep, uint32_t first, uint32_t last,
+ CBMDocLinkMdPath *out) {
+ const char *head = s;
+ size_t head_len = (size_t)(sep - s);
+ const char *tail = sep + PAIR_LEN;
+ const char *tail_last = tail;
+ for (const char *t = strstr(tail, "::"); t; t = strstr(t + PAIR_LEN, "::")) {
+ tail_last = t + PAIR_LEN;
+ }
+ const char *hd = head_len ? memchr(head, '.', head_len) : NULL;
+ if (!hd || !md_ident(tail_last, strlen(tail_last)) || !md_all_of(head, head_len, "./\\-")) {
+ return false;
+ }
+ const char *ext = head;
+ for (size_t i = head_len; i > 0; i--) {
+ if (head[i - SKIP_ONE] == '.') {
+ ext = head + i;
+ break;
+ }
+ }
+ size_t ext_len = head_len - (size_t)(ext - head);
+ for (size_t i = 0; i < ext_len; i++) {
+ if (ext[i] < 'a' || ext[i] > 'z') {
+ return false;
+ }
+ }
+ if (ext_len == 0) {
+ return false;
+ }
+ *sep = '\0';
+ md_shape(out, CBM_DOCLINK_MD_FILENAME, s, tail[0] ? tail : NULL, first, last);
+ return true;
+}
+
+/* One `mark` between a head `[A-Za-z_][\w.]*` and a tail `[A-Za-z_]\w*`
+ * (`dotted_tail`: `[A-Za-z_][\w.]*`): the shapes of `Type#member` and of
+ * `module:attr`. */
+static bool md_head_mark_tail(const char *s, size_t n, char mark, bool dotted_tail) {
+ const char *m = memchr(s, mark, n);
+ if (!m || m == s || memchr(m + SKIP_ONE, mark, n - (size_t)(m - s) - SKIP_ONE)) {
+ return false;
+ }
+ unsigned char c0 = (unsigned char)s[0];
+ size_t head = (size_t)(m - s);
+ size_t tail = n - head - SKIP_ONE;
+ if (tail == 0) {
+ return false;
+ }
+ unsigned char t0 = (unsigned char)m[SKIP_ONE];
+ return (md_alpha(c0) || c0 == '_') && md_all_of(s, head, ".") && (md_alpha(t0) || t0 == '_') &&
+ md_all_of(m + SKIP_ONE, tail, dotted_tail ? "." : "");
+}
+
+/* No slash: a file name, a special file, `file.ext::member`, or a qualified
+ * name. A bare name is neither: at most a suggestion, never a link. */
+static bool md_classify_name(char *s, size_t n, CBMDocLinkMdPath *out) {
+ if (md_in_list(s, n, MD_SPECIAL_FILES, false)) {
+ md_shape(out, CBM_DOCLINK_MD_FILENAME, s, NULL, 0, 0);
+ return true;
+ }
+ uint32_t first = 0;
+ uint32_t last = 0;
+ size_t cut = n;
+ if (md_line_suffix(s, &cut, &first, &last)) {
+ const char *dot = NULL;
+ for (size_t i = cut; i > 0; i--) {
+ if (s[i - SKIP_ONE] == '.') {
+ dot = s + i - SKIP_ONE;
+ break;
+ }
+ }
+ size_t ext_len = dot ? cut - (size_t)(dot - s) - SKIP_ONE : 0;
+ if (dot && md_in_list(dot + SKIP_ONE, ext_len, MD_FILE_EXT, true)) {
+ n = cut;
+ s[n] = '\0';
+ } else {
+ first = 0;
+ last = 0;
+ }
+ }
+ bool skipped = false;
+ if (strstr(s, "::")) {
+ /* identifiers only: a qualified name; otherwise perhaps `file.ext::member` */
+ char copy[MD_SPAN_MAX + SKIP_ONE];
+ memcpy(copy, s, n + SKIP_ONE);
+ if (md_join(s, n, "::", MD_RUST_ROOTS, &skipped, out)) {
+ return true;
+ }
+ memcpy(s, copy, n + SKIP_ONE);
+ return md_filename_member(s, strstr(s, "::"), first, last, out);
+ }
+ if (md_has(s, n, '#')) {
+ if (!md_head_mark_tail(s, n, '#', false)) {
+ return false;
+ }
+ s[strcspn(s, "#")] = '.';
+ return md_join(s, n, ".", NULL, &skipped, out);
+ }
+ if (md_has(s, n, '\\')) {
+ while (n > 0 && s[n - SKIP_ONE] == '\\') {
+ n--;
+ }
+ size_t lead = 0;
+ while (lead < n && s[lead] == '\\') {
+ lead++;
+ }
+ return md_join(s + lead, n - lead, "\\", NULL, &skipped, out);
+ }
+ if (md_has(s, n, ':')) {
+ if (!md_head_mark_tail(s, n, ':', true)) {
+ return false;
+ }
+ s[strcspn(s, ":")] = '.';
+ if (!md_join(s, n, ".", NULL, &skipped, out)) {
+ return false;
+ }
+ out->colon = true;
+ return true;
+ }
+ if (!md_has(s, n, '.')) {
+ return false;
+ }
+ if (s[0] == '.') {
+ const char *rest = s + SKIP_ONE;
+ size_t rest_len = n - SKIP_ONE;
+ if (md_ident(rest, rest_len) && !md_in_list(rest, rest_len, MD_FILE_EXT, true)) {
+ return false; /* `.member` */
+ }
+ if (md_all_of(rest, rest_len, ".-")) {
+ md_shape(out, CBM_DOCLINK_MD_FILENAME, s, NULL, 0, 0);
+ return true;
+ }
+ return false;
+ }
+ const char *dot = strrchr(s, '.');
+ const char *ext = dot + SKIP_ONE;
+ size_t ext_len = n - (size_t)(ext - s);
+ if (md_in_list(ext, ext_len, MD_FILE_EXT, true) && md_all_of(s, n, ".+-")) {
+ size_t stem_len = (size_t)(dot - s);
+ bool one_dot = memchr(s, '.', stem_len) == NULL;
+ if (one_dot && s[0] >= 'A' && s[0] <= 'Z' && md_eq_ci(ext, ext_len, "js")) {
+ return false; /* `Node.js`: a product */
+ }
+ bool mod_sum = md_eq_ci(ext, ext_len, "mod") || md_eq_ci(ext, ext_len, "sum");
+ if (!mod_sum || (stem_len == PAIR_LEN && memcmp(s, "go", PAIR_LEN) == 0)) {
+ md_shape(out, CBM_DOCLINK_MD_FILENAME, s, NULL, first, last);
+ return true;
+ }
+ }
+ if (!md_join(s, n, ".", MD_INSTANCE_ROOTS, &skipped, out)) {
+ return false;
+ }
+ out->instance = skipped; /* `self.x`: the qualifier is an instance, not a type */
+ return true;
+}
+
+bool cbm_doclink_md_classify_span(const char *text, size_t len, char *buf, size_t cap,
+ CBMDocLinkMdPath *out) {
+ md_shape(out, CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0);
+ if (!text || !buf) {
+ return false;
+ }
+ while (len > 0 && md_blank((unsigned char)text[0])) {
+ text++;
+ len--;
+ }
+ while (len > 0 && md_blank((unsigned char)text[len - SKIP_ONE])) {
+ len--;
+ }
+ if (len == 0 || len > MD_SPAN_MAX || len + SKIP_ONE > cap || md_has(text, len, '\n')) {
+ return false;
+ }
+ memcpy(buf, text, len);
+ buf[len] = '\0';
+ char *s = buf;
+ size_t n = len;
+ if (md_in_list(s, n, MD_DOMAINS, true) || md_is_url(s, n)) {
+ return false;
+ }
+ bool only_slashes = true;
+ for (size_t i = 0; i < n; i++) {
+ only_slashes = only_slashes && s[i] == '/';
+ }
+ if (only_slashes) {
+ return false;
+ }
+ if (n > SKIP_ONE && strchr("$%>#", s[0]) && s[SKIP_ONE] == ' ') {
+ return false; /* a shell prompt */
+ }
+ if (n > SKIP_ONE && s[0] == '-' &&
+ (md_alpha((unsigned char)s[SKIP_ONE]) || s[SKIP_ONE] == '-')) {
+ return false; /* an option */
+ }
+ if (s[0] == '$' ||
+ (n >= PAIR_LEN && (s[0] == '"' || s[0] == '\'') && s[n - SKIP_ONE] == s[0]) ||
+ (s[0] == '<' && s[n - SKIP_ONE] == '>')) {
+ return false; /* a variable, a string, markup */
+ }
+ size_t eq = 0;
+ while (eq < n && (md_alnum((unsigned char)s[eq]) || s[eq] == '_')) {
+ eq++;
+ }
+ if (eq > 0 && eq < n && s[eq] == '=' && !md_digit((unsigned char)s[0]) && !md_has(s, n, ' ')) {
+ return false; /* NAME=value */
+ }
+ size_t callee = md_callee(s, n, true);
+ if (callee) {
+ n = callee;
+ s[n] = '\0';
+ }
+ if (md_has(s, n, ' ') || md_has(s, n, '\t')) {
+ return false; /* a declaration, a command line, a snippet */
+ }
+ if (s[0] == '@') {
+ size_t slash = 0;
+ while (slash < n && s[slash] != '/') {
+ slash++;
+ }
+ if (slash < n && slash > SKIP_ONE) {
+ return false; /* `@scope/package`: an import path (a later rung) */
+ }
+ s++;
+ n--;
+ if (n == 0) {
+ return false;
+ }
+ }
+ callee = md_callee(s, n, false);
+ if (callee) {
+ n = callee;
+ s[n] = '\0';
+ }
+ while (n > 0 && strchr(";,:", s[n - SKIP_ONE])) {
+ n--;
+ }
+ if (n > SKIP_ONE && s[n - SKIP_ONE] == '!') {
+ n--;
+ }
+ while (n > 0 && s[n - SKIP_ONE] == '?') {
+ n--;
+ }
+ n = md_strip_generics(s, n);
+ while (n > 0 && strchr("&*~", s[0])) {
+ s++;
+ n--;
+ }
+ if (n >= PAIR_LEN && s[0] == ':' && s[SKIP_ONE] == ':') {
+ s += PAIR_LEN;
+ n -= PAIR_LEN;
+ }
+ if (n == 0) {
+ return false;
+ }
+ s[n] = '\0';
+ size_t first_slash = 0;
+ while (first_slash < n && s[first_slash] != '/') {
+ first_slash++;
+ }
+ bool slash_path = first_slash < n && !strstr(s, "::");
+ if (first_slash < n && !slash_path) {
+ /* `a::b/c`: a "::" after the first slash still makes a path */
+ char *dc = strstr(s, "::");
+ slash_path = dc && (size_t)(dc - s) > first_slash;
+ }
+ bool windows_path = false;
+ if (!slash_path && md_has(s, n, '\\')) {
+ const char *bs = strrchr(s, '\\');
+ size_t tail = n - (size_t)(bs - s) - SKIP_ONE;
+ windows_path = tail > 0 && md_all_of(bs + SKIP_ONE, tail, ".-") && md_ext_ok(bs, tail + 1);
+ }
+ if (slash_path || windows_path) {
+ return md_classify_path(s, n, out);
+ }
+ return md_classify_name(s, n, out);
+}
+
+/* ── Position lists ──────────────────────────────────────────────── */
+
+typedef struct {
+ int32_t *v;
+ int n;
+ int cap;
+} md_list_t;
+
+static bool md_push_int(md_list_t *l, int32_t x) {
+ if (l->n == l->cap) {
+ if (l->cap > INT32_MAX / PAIR_LEN) {
+ return false;
+ }
+ int ncap = l->cap ? l->cap * PAIR_LEN : MD_LIST_INIT;
+ int32_t *grown =
+ (int32_t *)cbm_realloc(CBM_MEM_CLASS_EXTRACT, l->v, (size_t)ncap * sizeof(*grown));
+ if (!grown) {
+ return false;
+ }
+ l->v = grown;
+ l->cap = ncap;
+ }
+ l->v[l->n++] = x;
+ return true;
+}
+
+static bool md_push_pair(md_list_t *l, int32_t a, int32_t b) {
+ return md_push_int(l, a) && md_push_int(l, b);
+}
+
+static void md_list_free(md_list_t *l) {
+ cbm_free(CBM_MEM_CLASS_EXTRACT, l->v);
+ l->v = NULL;
+ l->n = 0;
+ l->cap = 0;
+}
+
+/* Index of the first value >= x in an ascending list. */
+static int md_lower_bound(const md_list_t *l, int32_t x) {
+ int lo = 0;
+ int hi = l->n;
+ while (lo < hi) {
+ int mid = lo + ((hi - lo) / PAIR_LEN);
+ if (l->v[mid] < x) {
+ lo = mid + SKIP_ONE;
+ } else {
+ hi = mid;
+ }
+ }
+ return lo;
+}
+
+/* The first value >= x, or -1. */
+static int32_t md_next_at(const md_list_t *l, int32_t x) {
+ int i = md_lower_bound(l, x);
+ return i < l->n ? l->v[i] : CBM_NOT_FOUND;
+}
+
+/* ── The scan ────────────────────────────────────────────────────── */
+
+typedef struct {
+ uint32_t line;
+ const char *qn;
+ /* Another heading of the file has the same qualified name: the graph keeps
+ * one node for both, which owns only one of the headings, so this
+ * section's references belong to the file. */
+ bool shared_qn;
+} md_section_t;
+
+typedef struct {
+ bool in_front;
+ bool in_fence;
+ bool in_comment;
+ char fence_char;
+ int fence_len;
+} md_state_t;
+
+typedef struct {
+ CBMExtractCtx *ctx;
+ md_section_t *secs;
+ int nsecs;
+ char *buf; /* the current line, masked in place */
+ int len;
+ uint32_t line;
+ char *span_buf; /* classification scratch, MD_SPAN_MAX + 1 bytes */
+ md_list_t runs; /* backtick runs: start, length */
+ md_list_t by_len; /* the runs as (length, start), sorted */
+ md_list_t ranges; /* ranges to mask: start, end */
+ md_list_t stack; /* open '[' while matching */
+ md_list_t cands; /* link candidates: '[', ']' */
+ md_list_t opens; /* '(' */
+ md_list_t closes; /* ')' */
+ md_list_t bal; /* each ')' as (depth before it, position), sorted */
+ md_list_t gts; /* '>' */
+ md_list_t blanks; /* runs of spaces and tabs: start, end */
+ bool failed;
+} md_scan_t;
+
+static int md_section_cmp(const void *a, const void *b) {
+ const md_section_t *x = (const md_section_t *)a;
+ const md_section_t *y = (const md_section_t *)b;
+ if (x->line != y->line) {
+ return x->line < y->line ? -1 : 1;
+ }
+ return strcmp(x->qn, y->qn);
+}
+
+static int md_section_ptr_qn_cmp(const void *a, const void *b) {
+ const md_section_t *x = *(const md_section_t *const *)a;
+ const md_section_t *y = *(const md_section_t *const *)b;
+ return strcmp(x->qn, y->qn);
+}
+
+static int md_pair_cmp(const void *a, const void *b) {
+ const int32_t *x = (const int32_t *)a;
+ const int32_t *y = (const int32_t *)b;
+ if (x[0] != y[0]) {
+ return x[0] < y[0] ? -1 : 1;
+ }
+ return (x[SKIP_ONE] > y[SKIP_ONE]) - (x[SKIP_ONE] < y[SKIP_ONE]);
+}
+
+static void md_fail(md_scan_t *s) {
+ s->failed = true;
+ s->ctx->result->doc_links.failed = true;
+}
+
+/* Text that may be a reference: well-formed UTF-8 (no overlong form, no
+ * surrogate, nothing above U+10FFFF) without control bytes. */
+static bool md_clean_text(const char *t, int n) {
+ int i = 0;
+ while (i < n) {
+ unsigned char c = (unsigned char)t[i];
+ if (c < UTF8_CTRL_END || c == UTF8_DEL) {
+ return false;
+ }
+ int need;
+ unsigned char lo = UTF8_CONT_MIN;
+ unsigned char hi = UTF8_CONT_MAX;
+ if (c < UTF8_ASCII_END) {
+ need = 0;
+ } else if (c >= UTF8_LEAD2_MIN && c <= UTF8_LEAD2_MAX) {
+ need = SKIP_ONE;
+ } else if (c >= UTF8_LEAD3_MIN && c <= UTF8_LEAD3_MAX) {
+ need = PAIR_LEN;
+ lo = c == UTF8_LEAD3_MIN ? UTF8_E0_SECOND_MIN : lo; /* no overlong form */
+ hi = c == UTF8_SURROGATE_LEAD ? UTF8_ED_SECOND_MAX : hi; /* no surrogate */
+ } else if (c >= UTF8_LEAD4_MIN && c <= UTF8_LEAD4_MAX) {
+ need = PAIR_LEN + SKIP_ONE;
+ lo = c == UTF8_LEAD4_MIN ? UTF8_F0_SECOND_MIN : lo;
+ hi = c == UTF8_LEAD4_MAX ? UTF8_F4_SECOND_MAX : hi;
+ } else {
+ return false;
+ }
+ if (i + need >= n + (need == 0)) {
+ return false;
+ }
+ for (int k = SKIP_ONE; k <= need; k++) {
+ unsigned char cc = (unsigned char)t[i + k];
+ unsigned char kl = k == SKIP_ONE ? lo : UTF8_CONT_MIN;
+ unsigned char kh = k == SKIP_ONE ? hi : UTF8_CONT_MAX;
+ if (cc < kl || cc > kh) {
+ return false;
+ }
+ }
+ i += need + SKIP_ONE;
+ }
+ return true;
+}
+
+static void md_emit(md_scan_t *s, int syntax, const char *text, int n) {
+ while (n > 0 && md_blank((unsigned char)text[0])) {
+ text++;
+ n--;
+ }
+ while (n > 0 && md_blank((unsigned char)text[n - SKIP_ONE])) {
+ n--;
+ }
+ if (n <= 0 || memchr(text, MD_MASK, (size_t)n) || !md_clean_text(text, n)) {
+ return;
+ }
+ int lo = 0;
+ int hi = s->nsecs;
+ while (lo < hi) {
+ int mid = lo + ((hi - lo) / PAIR_LEN);
+ if (s->secs[mid].line <= s->line) {
+ lo = mid + SKIP_ONE;
+ } else {
+ hi = mid;
+ }
+ }
+ const md_section_t *sec = lo > 0 ? &s->secs[lo - SKIP_ONE] : NULL;
+ if (sec && sec->shared_qn) {
+ sec = NULL; /* the file, not the node another heading owns */
+ }
+ char *raw = cbm_arena_strndup(s->ctx->arena, text, (size_t)n);
+ if (!raw) {
+ md_fail(s);
+ return;
+ }
+ CBMDocLink link = {
+ .source_qn = sec ? sec->qn : (s->ctx->module_qn ? s->ctx->module_qn : ""),
+ .raw = raw,
+ .line = s->line,
+ .def_line = sec ? sec->line : SKIP_ONE,
+ .syntax = (uint16_t)syntax,
+ .flags = sec ? 0 : CBM_DOCLINK_FLAG_FILE,
+ };
+ cbm_doclinks_push(&s->ctx->result->doc_links, s->ctx->arena, link);
+}
+
+/* A code span's text: a reference when it names a path or a qualified name. */
+static void md_emit_span(md_scan_t *s, const char *text, int n) {
+ CBMDocLinkMdPath p;
+ if (n > 0 &&
+ cbm_doclink_md_classify_span(text, (size_t)n, s->span_buf, MD_SPAN_MAX + SKIP_ONE, &p)) {
+ md_emit(s,
+ p.shape == CBM_DOCLINK_MD_QUALIFIED ? CBM_DOCLINK_MD_CODE_NAME
+ : CBM_DOCLINK_MD_CODE_PATH,
+ text, n);
+ }
+}
+
+static void md_mask(md_scan_t *s, int a, int b) {
+ if (a < 0) {
+ a = 0;
+ }
+ if (b > s->len) {
+ b = s->len;
+ }
+ if (a < b) {
+ memset(s->buf + a, MD_MASK, (size_t)(b - a));
+ }
+}
+
+static int md_find(const char *buf, int len, int from, const char *needle, bool ci) {
+ int k = (int)strlen(needle);
+ for (int i = from; i + k <= len; i++) {
+ int j = 0;
+ while (j < k && (ci ? md_lower((unsigned char)buf[i + j]) : (unsigned char)buf[i + j]) ==
+ (unsigned char)needle[j]) {
+ j++;
+ }
+ if (j == k) {
+ return i;
+ }
+ }
+ return CBM_NOT_FOUND;
+}
+
+/* HTML <code> spans (tables in READMEs write code that way): their text,
+ * without inner tags and with the common entities decoded. */
+static void md_html_code(md_scan_t *s) {
+ int i = 0;
+ while (i < s->len) {
+ int open = md_find(s->buf, s->len, i, "<code", true);
+ if (open < 0) {
+ return;
+ }
+ int after = open + (int)MD_SLEN("<code");
+ int body;
+ if (after < s->len && s->buf[after] == '>') {
+ body = after + SKIP_ONE;
+ } else if (after < s->len && md_blank((unsigned char)s->buf[after])) {
+ const char *gt = memchr(s->buf + after, '>', (size_t)(s->len - after));
+ if (!gt) {
+ return;
+ }
+ body = (int)(gt - s->buf) + SKIP_ONE;
+ } else {
+ i = open + SKIP_ONE;
+ continue;
+ }
+ int close = md_find(s->buf, s->len, body, "</code>", true);
+ if (close < 0) {
+ return;
+ }
+ /* text without tags, entities decoded; never longer than the body */
+ char *text = s->span_buf + MD_SPAN_MAX + SKIP_ONE; /* second half of the scratch */
+ int w = 0;
+ int k = body;
+ while (k < close && w < MD_SPAN_MAX + SKIP_ONE) {
+ char c = s->buf[k];
+ if (c == '<') {
+ int lim = k + MD_TAG_MAX + PAIR_LEN; /* `<`, up to 200 bytes, `>` */
+ const char *gt = memchr(s->buf + k + SKIP_ONE, '>',
+ (size_t)((lim < close ? lim : close) - k - SKIP_ONE));
+ if (gt) {
+ k = (int)(gt - s->buf) + SKIP_ONE;
+ continue;
+ }
+ } else if (c == '&') {
+ static const struct {
+ const char *ent;
+ char ch;
+ } ents[] = {{"&lt;", '<'}, {"&gt;", '>'}, {"&amp;", '&'}, {"&quot;", '"'},
+ {"&#39;", '\''}, {"&#x27;", '\''}, {"&apos;", '\''}, {"&nbsp;", ' '}};
+ bool hit = false;
+ for (size_t e = 0; e < sizeof(ents) / sizeof(ents[0]); e++) {
+ int el = (int)strlen(ents[e].ent);
+ if (k + el <= close && memcmp(s->buf + k, ents[e].ent, (size_t)el) == 0) {
+ text[w++] = ents[e].ch;
+ k += el;
+ hit = true;
+ break;
+ }
+ }
+ if (hit) {
+ continue;
+ }
+ }
+ text[w++] = c;
+ k++;
+ }
+ if (k >= close) {
+ md_emit_span(s, text, w); /* a text longer than a span's limit is no name */
+ }
+ md_mask(s, open, close + (int)MD_SLEN("</code>"));
+ i = close + (int)MD_SLEN("</code>");
+ }
+}
+
+/* Code spans: a run of N backticks up to the next run of exactly N. An
+ * escaped first backtick (an odd run of backslashes before it) does not open
+ * a span. Closers come from the runs sorted by (length, start). */
+static void md_code_spans(md_scan_t *s) {
+ s->runs.n = 0;
+ s->by_len.n = 0;
+ s->ranges.n = 0;
+ for (int i = 0; i < s->len;) {
+ if (s->buf[i] != '`') {
+ i++;
+ continue;
+ }
+ int j = i;
+ while (j < s->len && s->buf[j] == '`') {
+ j++;
+ }
+ if (!md_push_pair(&s->runs, i, j - i) || !md_push_pair(&s->by_len, j - i, i)) {
+ md_fail(s);
+ return;
+ }
+ i = j;
+ }
+ int nruns = s->runs.n / PAIR_LEN;
+ if (nruns < PAIR_LEN) {
+ return;
+ }
+ qsort(s->by_len.v, (size_t)nruns, sizeof(int32_t) * PAIR_LEN, md_pair_cmp);
+ int pos = 0;
+ for (int r = 0; r < nruns; r++) {
+ int start = s->runs.v[r * PAIR_LEN];
+ int len = s->runs.v[(r * PAIR_LEN) + SKIP_ONE];
+ if (start < pos) {
+ continue;
+ }
+ int bs = 0;
+ while (start - bs > 0 && s->buf[start - bs - SKIP_ONE] == '\\') {
+ bs++;
+ }
+ if (bs % PAIR_LEN) {
+ start++;
+ len--;
+ if (len == 0) {
+ continue;
+ }
+ }
+ /* the first run of exactly `len` starting at or after start + len */
+ int lo = 0;
+ int hi = nruns;
+ int32_t key[PAIR_LEN] = {len, start + len};
+ while (lo < hi) {
+ int mid = lo + ((hi - lo) / PAIR_LEN);
+ if (md_pair_cmp(&s->by_len.v[mid * PAIR_LEN], key) < 0) {
+ lo = mid + SKIP_ONE;
+ } else {
+ hi = mid;
+ }
+ }
+ if (lo < nruns && s->by_len.v[lo * PAIR_LEN] == len) {
+ int close = s->by_len.v[(lo * PAIR_LEN) + SKIP_ONE];
+ int a = start + len;
+ int b = close;
+ if (b - a >= PAIR_LEN && s->buf[a] == ' ' && s->buf[b - SKIP_ONE] == ' ') {
+ bool all_space = true;
+ for (int k = a; k < b && all_space; k++) {
+ all_space = s->buf[k] == ' ';
+ }
+ if (!all_space) {
+ a++;
+ b--;
+ }
+ }
+ md_emit_span(s, s->buf + a, b - a);
+ if (!md_push_pair(&s->ranges, start, close + len)) {
+ md_fail(s);
+ return;
+ }
+ pos = close + len;
+ } else {
+ pos = start + len;
+ }
+ }
+ for (int i = 0; i < s->ranges.n; i += PAIR_LEN) {
+ md_mask(s, s->ranges.v[i], s->ranges.v[i + SKIP_ONE]);
+ }
+}
+
+/* `blanks` holds the space/tab runs as start, end, start, end, ... -- one
+ * strictly ascending list. The first value above i: an END when i lies in a
+ * run (its index is odd), a START (or nothing) when it does not. */
+static int md_blank_after(const md_scan_t *s, int i) {
+ return md_lower_bound(&s->blanks, i + SKIP_ONE);
+}
+
+/* The first space or tab at or after i (the line's end when there is none). */
+static int md_next_blank(const md_scan_t *s, int i) {
+ int k = md_blank_after(s, i);
+ if (k % PAIR_LEN == SKIP_ONE) {
+ return i;
+ }
+ return k < s->blanks.n ? s->blanks.v[k] : s->len;
+}
+
+/* The first byte at or after i that is no space or tab. */
+static int md_skip_blank(const md_scan_t *s, int i) {
+ int k = md_blank_after(s, i);
+ return k % PAIR_LEN == SKIP_ONE ? s->blanks.v[k] : i;
+}
+
+/* Where a link destination that starts at t ends: at the first space or tab,
+ * or at the first ')' at the destination's own parenthesis depth 0. */
+static int md_dest_end(const md_scan_t *s, int t) {
+ int depth = md_lower_bound(&s->opens, t) - md_lower_bound(&s->closes, t);
+ int end = md_next_blank(s, t);
+ /* the first ')' at or after t with the depth t had */
+ int nb = s->bal.n / PAIR_LEN;
+ int lo = 0;
+ int hi = nb;
+ int32_t key[PAIR_LEN] = {depth, t};
+ while (lo < hi) {
+ int mid = lo + ((hi - lo) / PAIR_LEN);
+ if (md_pair_cmp(&s->bal.v[mid * PAIR_LEN], key) < 0) {
+ lo = mid + SKIP_ONE;
+ } else {
+ hi = mid;
+ }
+ }
+ if (lo < nb && s->bal.v[lo * PAIR_LEN] == depth) {
+ int p = s->bal.v[(lo * PAIR_LEN) + SKIP_ONE];
+ if (p < end) {
+ end = p;
+ }
+ }
+ return end;
+}
+
+static bool md_line_lists(md_scan_t *s) {
+ s->stack.n = 0;
+ s->cands.n = 0;
+ s->opens.n = 0;
+ s->closes.n = 0;
+ s->bal.n = 0;
+ s->gts.n = 0;
+ s->blanks.n = 0;
+ int depth = 0;
+ for (int i = 0; i < s->len; i++) {
+ char c = s->buf[i];
+ bool ok = true;
+ switch (c) {
+ case '[':
+ ok = md_push_int(&s->stack, i);
+ break;
+ case ']':
+ if (s->stack.n > 0) {
+ int o = s->stack.v[--s->stack.n];
+ if (i + SKIP_ONE < s->len && s->buf[i + SKIP_ONE] == '(') {
+ ok = md_push_pair(&s->cands, o, i);
+ }
+ }
+ break;
+ case '(':
+ ok = md_push_int(&s->opens, i);
+ depth++;
+ break;
+ case ')':
+ ok = md_push_int(&s->closes, i) && md_push_pair(&s->bal, depth, i);
+ depth--;
+ break;
+ case '>':
+ ok = md_push_int(&s->gts, i);
+ break;
+ case ' ':
+ case '\t': {
+ int j = i;
+ while (j < s->len && md_sp_tab((unsigned char)s->buf[j])) {
+ j++;
+ }
+ ok = md_push_pair(&s->blanks, i, j);
+ i = j - SKIP_ONE;
+ break;
+ }
+ default:
+ break;
+ }
+ if (!ok) {
+ return false;
+ }
+ }
+ if (s->bal.n > PAIR_LEN) {
+ qsort(s->bal.v, (size_t)(s->bal.n / PAIR_LEN), sizeof(int32_t) * PAIR_LEN, md_pair_cmp);
+ }
+ return true;
+}
+
+static void md_link_target(md_scan_t *s, int a, int b, bool image) {
+ while (a < b && md_blank((unsigned char)s->buf[a])) {
+ a++;
+ }
+ while (b > a && md_blank((unsigned char)s->buf[b - SKIP_ONE])) {
+ b--;
+ }
+ if (a >= b || image || s->buf[a] == '#' || memchr(s->buf + a, MD_MASK, (size_t)(b - a)) ||
+ md_is_url(s->buf + a, (size_t)(b - a))) {
+ return; /* empty, an image, an in-page anchor, masked text, a URL */
+ }
+ md_emit(s, CBM_DOCLINK_MD_LINK, s->buf + a, b - a);
+}
+
+/* Inline links and images `[text](dest "title")`. */
+static void md_links(md_scan_t *s) {
+ if (!md_line_lists(s)) {
+ md_fail(s);
+ return;
+ }
+ s->ranges.n = 0;
+ int pos = 0;
+ int floor = 0;
+ for (int c = 0; c < s->cands.n; c += PAIR_LEN) {
+ int o = s->cands.v[c];
+ int k = s->cands.v[c + SKIP_ONE];
+ if (k < pos || o < floor) {
+ continue;
+ }
+ int t = k + PAIR_LEN;
+ while (t < s->len && s->buf[t] == ' ') {
+ t++;
+ }
+ int ta;
+ int tb;
+ int after;
+ if (t < s->len && s->buf[t] == '<') {
+ int e = md_next_at(&s->gts, t);
+ if (e < 0) {
+ pos = k + PAIR_LEN;
+ continue;
+ }
+ ta = t + SKIP_ONE;
+ tb = e;
+ after = e + SKIP_ONE;
+ } else {
+ int e = md_dest_end(s, t);
+ ta = t;
+ tb = e;
+ after = e;
+ }
+ int close = md_next_at(&s->closes, after);
+ if (close < 0) {
+ pos = k + PAIR_LEN;
+ continue;
+ }
+ int q = md_skip_blank(s, after);
+ if (q < close && !strchr("\"'(", s->buf[q])) {
+ pos = k + PAIR_LEN;
+ continue;
+ }
+ bool image = o > 0 && s->buf[o - SKIP_ONE] == '!';
+ md_link_target(s, ta, tb, image);
+ if (!md_push_pair(&s->ranges, o - (image ? SKIP_ONE : 0), close + SKIP_ONE)) {
+ md_fail(s);
+ return;
+ }
+ pos = close + SKIP_ONE;
+ floor = pos;
+ }
+ for (int i = 0; i < s->ranges.n; i += PAIR_LEN) {
+ md_mask(s, s->ranges.v[i], s->ranges.v[i + SKIP_ONE]);
+ }
+}
+
+/* A link reference definition `[label]: dest` (the whole line). */
+static void md_refdef(md_scan_t *s) {
+ int i = 0;
+ while (i < s->len && i < MD_INDENT_MAX && md_blank((unsigned char)s->buf[i])) {
+ i++;
+ }
+ if (i >= s->len || s->buf[i] != '[') {
+ return;
+ }
+ const char *rb = memchr(s->buf + i + SKIP_ONE, ']', (size_t)(s->len - i - SKIP_ONE));
+ if (!rb) {
+ return;
+ }
+ int j = (int)(rb - s->buf);
+ if (j == i + SKIP_ONE || j + SKIP_ONE >= s->len || s->buf[j + SKIP_ONE] != ':') {
+ return;
+ }
+ int k = j + PAIR_LEN;
+ while (k < s->len && md_blank((unsigned char)s->buf[k])) {
+ k++;
+ }
+ if (k < s->len && s->buf[k] == '<') {
+ k++;
+ }
+ int e = k;
+ while (e < s->len && !md_blank((unsigned char)s->buf[e]) && s->buf[e] != '>') {
+ e++;
+ }
+ if (e > k) {
+ md_link_target(s, k, e, false);
+ }
+ md_mask(s, 0, s->len);
+}
+
+static bool md_url_stop(unsigned char c) {
+ return md_blank(c) || c == '<' || c == '>' || c == '"' || c == '\'' || c == '`' ||
+ c == MD_MASK || c == ')' || c == ']' || c == '|';
+}
+
+static bool md_path_stop(unsigned char c) {
+ return md_blank(c) || strchr("()[]{}<>\"',;:`*|", (int)c) != NULL || c == MD_MASK;
+}
+
+/* Bare URLs are masked (they are no repository paths); then every token with
+ * a slash and a file extension is a bare path. */
+static void md_urls_and_paths(md_scan_t *s) {
+ static const char *const schemes[MD_URL_SCHEMES] = {"http://", "https://", "ftp://"};
+ for (int i = 0; i < s->len; i++) {
+ char c = s->buf[i];
+ if (c != 'h' && c != 'f') {
+ continue;
+ }
+ for (int k = 0; k < MD_URL_SCHEMES; k++) {
+ int sl = (int)strlen(schemes[k]);
+ if (i + sl < s->len && memcmp(s->buf + i, schemes[k], (size_t)sl) == 0 &&
+ !md_url_stop((unsigned char)s->buf[i + sl])) {
+ int j = i + sl;
+ while (j < s->len && !md_url_stop((unsigned char)s->buf[j])) {
+ j++;
+ }
+ int e = j;
+ while (e > i && strchr(".,;:!?", s->buf[e - SKIP_ONE])) {
+ e--;
+ }
+ md_mask(s, i, e);
+ i = j - SKIP_ONE;
+ break;
+ }
+ }
+ }
+ for (int i = 0; i < s->len;) {
+ if (md_path_stop((unsigned char)s->buf[i])) {
+ i++;
+ continue;
+ }
+ int j = i;
+ while (j < s->len && !md_path_stop((unsigned char)s->buf[j])) {
+ j++;
+ }
+ int e = j;
+ while (e > i && s->buf[e - SKIP_ONE] == '.') {
+ e--;
+ }
+ if (e == i) {
+ i = j; /* only dots */
+ continue;
+ }
+ const char *tok = s->buf + i;
+ size_t n = (size_t)(e - i);
+ bool path = md_has(tok, n, '/') && !(n >= PAIR_LEN && tok[0] == '/' && tok[1] == '/');
+ for (size_t k = 0; path && k < n; k++) {
+ unsigned char c = (unsigned char)tok[k];
+ path = md_alnum(c) || strchr("_-+@~./", (int)c) != NULL;
+ }
+ if (path) {
+ size_t end = n;
+ while (end > 0 && tok[end - SKIP_ONE] == '/') {
+ end--;
+ }
+ size_t base = end;
+ while (base > 0 && tok[base - SKIP_ONE] != '/') {
+ base--;
+ }
+ const char *last = tok + base;
+ size_t last_len = end - base;
+ size_t dots = 0;
+ for (size_t k = 0; k < last_len; k++) {
+ dots += last[k] == '.';
+ }
+ bool tiny_dotfile = last_len > 0 && last[0] == '.' && dots == SKIP_ONE &&
+ last_len < (size_t)MD_TINY_DOTFILE;
+ if (md_ext_ok(last, last_len) && !tiny_dotfile) {
+ md_emit(s, CBM_DOCLINK_MD_PATH, tok, (int)n);
+ }
+ }
+ i = j;
+ }
+}
+
+static void md_inline(md_scan_t *s) {
+ md_html_code(s);
+ if (!s->failed) {
+ md_code_spans(s);
+ }
+ if (!s->failed) {
+ md_links(s);
+ }
+ if (!s->failed) {
+ md_refdef(s);
+ md_urls_and_paths(s);
+ }
+}
+
+/* Leading blanks skipped: the line's content. */
+static const char *md_lstrip(const char *p, int len, int *rest) {
+ int i = 0;
+ while (i < len && md_blank((unsigned char)p[i])) {
+ i++;
+ }
+ *rest = len - i;
+ return p + i;
+}
+
+static bool md_trim_eq(const char *p, int len, const char *word) {
+ int n = 0;
+ const char *t = md_lstrip(p, len, &n);
+ while (n > 0 && md_blank((unsigned char)t[n - SKIP_ONE])) {
+ n--;
+ }
+ return (size_t)n == strlen(word) && memcmp(t, word, (size_t)n) == 0;
+}
+
+/* One line of the document. `raw` is not NUL-terminated. */
+static void md_line(md_scan_t *s, md_state_t *st, const char *raw, int len, bool mdx) {
+ if (s->line == SKIP_ONE && md_trim_eq(raw, len, "---")) {
+ st->in_front = true;
+ return;
+ }
+ if (st->in_front) {
+ if (md_trim_eq(raw, len, "---") || md_trim_eq(raw, len, "...")) {
+ st->in_front = false;
+ }
+ return;
+ }
+ int rest = 0;
+ const char *t = md_lstrip(raw, len, &rest);
+ if (st->in_fence) {
+ int k = 0;
+ while (k < rest && t[k] == st->fence_char) {
+ k++;
+ }
+ int tail = k;
+ while (tail < rest && md_blank((unsigned char)t[tail])) {
+ tail++;
+ }
+ if (k >= st->fence_len && tail == rest) {
+ st->in_fence = false;
+ }
+ return;
+ }
+ if (rest >= MD_FENCE_MIN && (t[0] == '`' || t[0] == '~')) {
+ int k = 0;
+ while (k < rest && t[k] == t[0]) {
+ k++;
+ }
+ if (k >= MD_FENCE_MIN && !md_has(t + k, (size_t)(rest - k), '`')) {
+ st->in_fence = true;
+ st->fence_char = t[0];
+ st->fence_len = k;
+ return;
+ }
+ }
+ memcpy(s->buf, raw, (size_t)len);
+ s->buf[len] = '\0';
+ s->len = len;
+ int from = 0;
+ if (st->in_comment) {
+ int end = md_find(s->buf, s->len, 0, "-->", false);
+ if (end < 0) {
+ return;
+ }
+ st->in_comment = false;
+ memset(s->buf, ' ', (size_t)end + MD_SLEN("-->"));
+ from = end + (int)MD_SLEN("-->");
+ }
+ for (;;) {
+ int a = md_find(s->buf, s->len, from, "<!--", false);
+ if (a < 0) {
+ break;
+ }
+ int b = md_find(s->buf, s->len, a + (int)MD_SLEN("<!--"), "-->", false);
+ if (b < 0) {
+ s->len = a;
+ s->buf[a] = '\0';
+ st->in_comment = true;
+ break;
+ }
+ memset(s->buf + a, ' ', (size_t)(b + (int)MD_SLEN("-->") - a));
+ from = b + (int)MD_SLEN("-->");
+ }
+ if (mdx &&
+ (strncmp(s->buf, "import", MD_SLEN("import")) == 0 ||
+ strncmp(s->buf, "export", MD_SLEN("export")) == 0) &&
+ s->len > (int)MD_SLEN("import") && md_blank((unsigned char)s->buf[MD_SLEN("import")])) {
+ return;
+ }
+ md_inline(s);
+}
+
+/* The file's sections: its Section definitions by start line. False only when
+ * memory ran out (a file without headings has none, and that is no failure). */
+static bool md_sections(CBMExtractCtx *ctx, CBMArena *a, md_section_t **out, int *count) {
+ const CBMDefArray *defs = &ctx->result->defs;
+ int n = 0;
+ for (int i = 0; i < defs->count; i++) {
+ const CBMDefinition *d = &defs->items[i];
+ n += d->label && d->qualified_name && strcmp(d->label, "Section") == 0;
+ }
+ *out = NULL;
+ *count = 0;
+ if (n == 0) {
+ return true;
+ }
+ md_section_t *secs = (md_section_t *)cbm_arena_alloc(a, (size_t)n * sizeof(*secs));
+ if (!secs) {
+ return false;
+ }
+ for (int i = 0; i < defs->count; i++) {
+ const CBMDefinition *d = &defs->items[i];
+ if (d->label && d->qualified_name && strcmp(d->label, "Section") == 0) {
+ secs[(*count)++] =
+ (md_section_t){.line = d->start_line, .qn = d->qualified_name, .shared_qn = false};
+ }
+ }
+ /* repeated qualified names, found through a copy sorted by name */
+ const md_section_t **by_qn =
+ (const md_section_t **)cbm_arena_alloc(a, (size_t)n * sizeof(*by_qn));
+ if (!by_qn) {
+ return false;
+ }
+ for (int i = 0; i < *count; i++) {
+ by_qn[i] = &secs[i];
+ }
+ qsort(by_qn, (size_t)*count, sizeof(*by_qn), md_section_ptr_qn_cmp);
+ for (int i = SKIP_ONE; i < *count; i++) {
+ if (strcmp(by_qn[i]->qn, by_qn[i - SKIP_ONE]->qn) == 0) {
+ ((md_section_t *)by_qn[i])->shared_qn = true;
+ ((md_section_t *)by_qn[i - SKIP_ONE])->shared_qn = true;
+ }
+ }
+ qsort(secs, (size_t)*count, sizeof(*secs), md_section_cmp);
+ *out = secs;
+ return true;
+}
+
+void cbm_doclink_md_scan_file(CBMExtractCtx *ctx) {
+ if (!ctx || !ctx->result || !ctx->source || ctx->source_len <= 0) {
+ return;
+ }
+ CBMArena *scratch = ctx->scratch ? ctx->scratch : ctx->arena;
+ md_scan_t s = {.ctx = ctx};
+ bool have_secs = md_sections(ctx, scratch, &s.secs, &s.nsecs);
+ s.buf = (char *)cbm_arena_alloc(scratch, (size_t)ctx->source_len + SKIP_ONE);
+ s.span_buf = (char *)cbm_arena_alloc(scratch, (size_t)(MD_SPAN_MAX + SKIP_ONE) * PAIR_LEN);
+ if (!s.buf || !s.span_buf || !have_secs) {
+ ctx->result->doc_links.failed = true;
+ return;
+ }
+ const char *rel = ctx->rel_path ? ctx->rel_path : "";
+ size_t rel_len = strlen(rel);
+ bool mdx = rel_len >= MD_SLEN(".mdx") &&
+ md_eq_ci(rel + rel_len - MD_SLEN(".mdx"), MD_SLEN(".mdx"), ".mdx");
+ md_state_t st = {0};
+ const char *src = ctx->source;
+ int n = ctx->source_len;
+ int pos = 0;
+ while (pos < n && !s.failed) {
+ const char *nl = memchr(src + pos, '\n', (size_t)(n - pos));
+ int end = nl ? (int)(nl - src) : n;
+ int len = end - pos;
+ if (len > 0 && src[pos + len - SKIP_ONE] == '\r') {
+ len--;
+ }
+ s.line++;
+ md_line(&s, &st, src + pos, len, mdx);
+ pos = end + SKIP_ONE;
+ }
+ md_list_free(&s.runs);
+ md_list_free(&s.by_len);
+ md_list_free(&s.ranges);
+ md_list_free(&s.stack);
+ md_list_free(&s.cands);
+ md_list_free(&s.opens);
+ md_list_free(&s.closes);
+ md_list_free(&s.bal);
+ md_list_free(&s.gts);
+ md_list_free(&s.blanks);
+}
diff --git a/src/pipeline/doc_links.c b/src/pipeline/doc_links.c
index 8ac85fcb5..bdad5249a 100644
--- a/src/pipeline/doc_links.c
+++ b/src/pipeline/doc_links.c
@@ -46,6 +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,
};
enum { DOCLINK_RESOLVER_COUNT = sizeof(DOCLINK_RESOLVERS) / sizeof(DOCLINK_RESOLVERS[0]) };
@@ -328,6 +329,9 @@ typedef struct {
int64_t src;
int64_t tgt;
uint32_t line;
+ uint32_t target_first; /* the target lines the reference names; 0: none */
+ uint32_t target_last;
+ const char *via;
uint16_t syntax;
bool exact;
} doclink_mention_t;
@@ -398,11 +402,16 @@ static void emit_mentions(cbm_doclinks_t *dl, const char *rel, doclink_mention_t
j++;
}
char props[CBM_SZ_256];
+ char lines[CBM_SZ_64] = "";
+ if (m[i].target_first > 0) {
+ snprintf(lines, sizeof(lines), ",\"target_lines\":[%u,%u]", m[i].target_first,
+ m[i].target_last);
+ }
snprintf(props, sizeof(props),
- "{\"via\":\"doc_comment\",\"syntax\":\"%s\",\"tier\":\"%s\",\"line\":%u,"
- "\"count\":%d}",
- cbm_doclink_syntax_name(m[i].syntax), exact ? "exact" : "unique", m[i].line,
- j - i);
+ "{\"via\":\"%s\",\"syntax\":\"%s\",\"tier\":\"%s\",\"line\":%u,"
+ "\"count\":%d%s}",
+ m[i].via, cbm_doclink_syntax_name(m[i].syntax), exact ? "exact" : "unique",
+ m[i].line, j - i, lines);
if (doclinks_insert_edge(edge_out, m[i].src, m[i].tgt, props) == 0) {
mark_failed(dl, rel, "alloc"); /* an edge that is not there is not counted */
} else {
@@ -488,6 +497,9 @@ void cbm_doclinks_resolve_file(cbm_doclinks_t *dl, int file_idx, const CBMFileRe
mentions[nm++] = (doclink_mention_t){.src = src->id,
.tgt = out.target->id,
.line = link->line,
+ .target_first = out.target_first,
+ .target_last = out.target_last,
+ .via = R->via ? R->via : "doc_comment",
.syntax = link->syntax,
.exact = out.exact};
continue;
diff --git a/src/pipeline/doc_links.h b/src/pipeline/doc_links.h
index 20f9fbfaa..a51ada8c2 100644
--- a/src/pipeline/doc_links.h
+++ b/src/pipeline/doc_links.h
@@ -67,6 +67,10 @@ typedef struct {
const cbm_gbuf_node_t *target;
bool exact; /* tier: "exact" (qualified/doc ID/alias) vs "unique" (scope lookup) */
int reason;
+ /* Lines of the target that the reference names (a document's `file#L3-L9`):
+ * the edge's "target_lines". 0 and 0: the reference names no lines. */
+ uint32_t target_first;
+ uint32_t target_last;
} cbm_doclink_outcome_t;
/* A file's stored doc-link scope (incremental runs: files not re-extracted). */
@@ -222,9 +226,14 @@ typedef struct {
* the run. */
int (*scope_accepted)(const char *scope);
char *(*rejected_scope)(const char *scope);
+ /* The `via` of its MENTIONS edges: what kind of text the reference is
+ * written in. NULL: "doc_comment". */
+ const char *via;
} cbm_doclink_resolver_t;
extern const cbm_doclink_resolver_t cbm_doclink_cs_resolver;
+/* Markdown documents (doc_links_md.c): via "markdown". */
+extern const cbm_doclink_resolver_t cbm_doclink_md_resolver;
#if defined(CBM_ENABLE_TEST_SEAMS) && CBM_ENABLE_TEST_SEAMS
/* Test seam (doc_links_cs.c): the scope levels and overloads the C# resolver
diff --git a/src/pipeline/doc_links_md.c b/src/pipeline/doc_links_md.c
new file mode 100644
index 000000000..6251cb336
--- /dev/null
+++ b/src/pipeline/doc_links_md.c
@@ -0,0 +1,1122 @@
+/*
+ * doc_links_md.c — Markdown references -> MENTIONS edges: the resolving half.
+ *
+ * A Markdown reference (doclink_md.c) names a repository PATH, so it is looked
+ * up in the graph as written: the File node, or the Folder node, at that path,
+ * read relative to the document's own directory and -- for a path with a
+ * directory part -- relative to the repository root as well (documents are
+ * written both ways). A file name alone is read relative to the document
+ * only: a file of that name elsewhere in the repository is not what the
+ * document says (the field tests' rule for bare file names).
+ *
+ * Into the file: a line range picks the innermost code definition that holds
+ * the WHOLE range; a member (`path::Name`, `path::Owner::name`) picks the one
+ * definition of that name in the file. Otherwise the edge goes to the file,
+ * and the range stays on it ("target_lines"). Every edge is exact: the
+ * document wrote the path.
+ *
+ * Unresolved:
+ * missing the path is not in the graph, but its directory is: the
+ * document names something that is not there (doc rot)
+ * ambiguous a file name alone that is not next to the document but exists
+ * elsewhere in the repository: the document does not say which
+ * Not a reference to this repository at all (LOCAL: no edge, no row): a link
+ * back into the same document; a path that is neither indexed nor of a type
+ * the indexer reads (an image, an archive, an extensionless page); a path
+ * whose directory is not in the repository either (a file a tutorial asks
+ * the reader to create, a system path, a path above the root); and, in a
+ * code span, a rooted single segment without a file extension, which is a
+ * URL route (`/docs`, `/health`), not the directory of that name.
+ */
+#include "pipeline/doc_links.h"
+
+#include "discover/discover.h" /* cbm_language_for_filename */
+#include "doclink.h"
+#include "foundation/arena.h"
+#include "foundation/constants.h"
+#include "foundation/hash_table.h"
+#include "foundation/mem_core.h"
+#include "graph_buffer/graph_buffer.h"
+
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+enum {
+ MDR_PATH_CAP = 1024, /* the longest repository path looked up */
+ MDR_TRIES = 2, /* relative to the document, relative to the root */
+ MDR_BASENAME_INIT = 1024, /* first capacity of the file-name table */
+ MDR_HEX_BASE = 16,
+ MDR_PCT_LEN = 3, /* `%XX` */
+};
+
+/* Labels whose nodes are code a range or a member can name. */
+/* Labels whose nodes are code a range, a member or a name can bind. Every one
+ * of them is proxied on the incremental route (pipeline_delta.c preseed), so
+ * a re-resolved document binds what a full build binds; Macro nodes are not
+ * proxied, and are no target here. */
+static const char *const MDR_CODE_LABELS[] = {
+ "Function", "Method", "Class", "Struct", "Interface", "Trait", "Enum", "Type",
+ "Variable", "Constant", "Field", "Table", "View", "Trigger", NULL};
+
+static unsigned char mdr_norm_c(unsigned char c);
+static bool mdr_in(const char *s, size_t n, const char *const *list);
+static void mdr_destroy(void *index);
+
+/* A module or package a qualified name can name: a code file without its
+ * extension (`pkg/routing.py` is `pkg.routing`), a package directory through
+ * its index file (`pkg/__init__.py`, `mod.rs`, `index.ts`, `lib.rs`), or a
+ * directory. */
+typedef struct mdr_pkg {
+ const char *chain; /* the pieces before its name, '.'-joined */
+ const cbm_gbuf_node_t *node;
+ const char *file; /* its code file (NULL: a directory) */
+ struct mdr_pkg *next; /* the next one of the same name */
+} mdr_pkg_t;
+
+/* A code definition and its file: the by-file list ranges and members are
+ * read from. */
+typedef struct {
+ const char *file;
+ const cbm_gbuf_node_t *node;
+} mdr_def_t;
+
+typedef struct {
+ const char *project;
+ size_t project_len;
+ const char **run_paths; /* run_file -> rel_path (NULL: not a Markdown file of this run) */
+ int run_count;
+ /* base name -> number of File nodes with it (a file name alone that is
+ * not next to the document: ambiguous when the name exists anywhere) */
+ CBMHashTable *basenames;
+ CBMHashTable *pkgs; /* name -> mdr_pkg_t list */
+ CBMHashTable *top; /* normalized top-level directory and code-file names */
+ CBMArena arena; /* the strings and records of pkgs and top */
+ mdr_def_t *defs; /* every code definition, sorted by (file, start line, id) */
+ int ndefs;
+ CBMHashTable *folders; /* directory path -> its Folder node */
+} mdr_index_t;
+
+static const char *mdr_base(const char *path) {
+ const char *slash = strrchr(path, '/');
+ return slash ? slash + SKIP_ONE : path;
+}
+
+static bool mdr_code_file(const char *path) {
+ CBMLanguage lang = cbm_language_for_filename(mdr_base(path));
+ return lang != CBM_LANG_COUNT && lang != CBM_LANG_MARKDOWN && lang != CBM_LANG_RST &&
+ lang != CBM_LANG_HTML && lang != CBM_LANG_CSS && lang != CBM_LANG_SCSS &&
+ !cbm_has_config_extension(path);
+}
+
+/* The stems of a package directory's index file. */
+static const char *const MDR_INDEX_STEMS[] = {"__init__", "mod", "index", "lib", NULL};
+
+/* Lower-cased copy, '-' read as '_'. */
+static char *mdr_norm_dup(CBMArena *a, const char *s, size_t n) {
+ char *out = cbm_arena_strndup(a, s, n);
+ for (size_t i = 0; out && i < n; i++) {
+ out[i] = (char)mdr_norm_c((unsigned char)out[i]);
+ }
+ return out;
+}
+
+/* Add the module `key` (a path without extension, '/'-separated, whose last
+ * piece may hold dots) unless one is there. False when memory ran out. */
+static bool mdr_add_pkg(mdr_index_t *x, CBMHashTable *seen, const char *key, size_t klen,
+ const cbm_gbuf_node_t *node, const char *file) {
+ char *seen_key = cbm_arena_strndup(&x->arena, key, klen); /* borrowed by `seen` */
+ char *k = seen_key ? cbm_arena_strndup(&x->arena, key, klen) : NULL;
+ if (!k) {
+ return false;
+ }
+ if (cbm_ht_get(seen, seen_key)) {
+ return true; /* the first file of a key wins (files come sorted by path) */
+ }
+ cbm_ht_set(seen, seen_key, (void *)node);
+ /* pieces: '/'- and '.'-separated; the name is the last one */
+ for (char *c = k; *c; c++) {
+ if (*c == '/') {
+ *c = '.';
+ }
+ }
+ char *last = strrchr(k, '.');
+ const char *name = last ? last + SKIP_ONE : k;
+ if (!name[0]) {
+ return true;
+ }
+ mdr_pkg_t *p = (mdr_pkg_t *)cbm_arena_alloc(&x->arena, sizeof(*p));
+ if (!p) {
+ return false;
+ }
+ if (last) {
+ *last = '\0';
+ }
+ p->chain = last ? k : "";
+ p->node = node;
+ p->file = file;
+ p->next = (mdr_pkg_t *)cbm_ht_get(x->pkgs, name);
+ cbm_ht_set(x->pkgs, name, p);
+ return true;
+}
+
+static bool mdr_add_top(mdr_index_t *x, const char *s, size_t n) {
+ char *k = mdr_norm_dup(&x->arena, s, n);
+ if (!k) {
+ return false;
+ }
+ cbm_ht_set(x->top, k, (void *)k);
+ return true;
+}
+
+static int mdr_def_cmp(const void *a, const void *b) {
+ const mdr_def_t *x = (const mdr_def_t *)a;
+ const mdr_def_t *y = (const mdr_def_t *)b;
+ int c = strcmp(x->file, y->file);
+ if (c != 0) {
+ return c;
+ }
+ if (x->node->start_line != y->node->start_line) {
+ return x->node->start_line < y->node->start_line ? -1 : 1;
+ }
+ return (x->node->id > y->node->id) - (x->node->id < y->node->id);
+}
+
+/* Every code definition of the graph, sorted by file. False when memory ran
+ * out. */
+static bool mdr_build_defs(mdr_index_t *x, const cbm_gbuf_t *graph) {
+ int total = 0;
+ for (size_t l = 0; MDR_CODE_LABELS[l]; l++) {
+ const cbm_gbuf_node_t **nodes = NULL;
+ int count = 0;
+ if (cbm_gbuf_find_by_label(graph, MDR_CODE_LABELS[l], &nodes, &count) == 0) {
+ total += count;
+ }
+ }
+ if (total == 0) {
+ return true;
+ }
+ x->defs = (mdr_def_t *)cbm_alloc(CBM_MEM_CLASS_OTHER, (size_t)total * sizeof(*x->defs));
+ if (!x->defs) {
+ return false;
+ }
+ for (size_t l = 0; MDR_CODE_LABELS[l]; l++) {
+ const cbm_gbuf_node_t **nodes = NULL;
+ int count = 0;
+ if (cbm_gbuf_find_by_label(graph, MDR_CODE_LABELS[l], &nodes, &count) != 0) {
+ continue;
+ }
+ for (int i = 0; i < count && x->ndefs < total; i++) {
+ if (nodes[i]->file_path && nodes[i]->file_path[0]) {
+ x->defs[x->ndefs++] = (mdr_def_t){.file = nodes[i]->file_path, .node = nodes[i]};
+ }
+ }
+ }
+ qsort(x->defs, (size_t)x->ndefs, sizeof(*x->defs), mdr_def_cmp);
+ return true;
+}
+
+/* The module index over the graph's code files and directories. */
+static bool mdr_build_pkgs(mdr_index_t *x, const cbm_gbuf_t *graph) {
+ CBMHashTable *seen = cbm_ht_create_in(CBM_MEM_CLASS_HASH_TABLE, MDR_BASENAME_INIT);
+ if (!seen) {
+ return false;
+ }
+ bool ok = true;
+ const cbm_gbuf_node_t **nodes = NULL;
+ int count = 0;
+ if (cbm_gbuf_find_by_label(graph, "File", &nodes, &count) == 0) {
+ for (int i = 0; ok && i < count; i++) {
+ const char *fp = nodes[i]->file_path;
+ if (!fp || !fp[0] || !mdr_code_file(fp)) {
+ continue;
+ }
+ const char *base = mdr_base(fp);
+ const char *dot = strrchr(base, '.');
+ size_t stem_len = dot && dot != base ? (size_t)(dot - base) : strlen(base);
+ size_t dir_len = base > fp ? (size_t)(base - fp - SKIP_ONE) : 0;
+ ok = mdr_add_pkg(x, seen, fp, (size_t)(base - fp) + stem_len, nodes[i], fp);
+ if (ok && dir_len > 0 && mdr_in(base, stem_len, MDR_INDEX_STEMS)) {
+ ok = mdr_add_pkg(x, seen, fp, dir_len, nodes[i], fp);
+ }
+ if (ok && dir_len == 0) {
+ ok = mdr_add_top(x, base, stem_len);
+ }
+ }
+ }
+ if (ok && cbm_gbuf_find_by_label(graph, "Folder", &nodes, &count) == 0) {
+ for (int i = 0; ok && i < count; i++) {
+ const char *dp = nodes[i]->file_path;
+ if (!dp || !dp[0]) {
+ continue;
+ }
+ ok = mdr_add_pkg(x, seen, dp, strlen(dp), nodes[i], NULL);
+ if (ok && !strchr(dp, '/')) {
+ ok = mdr_add_top(x, dp, strlen(dp));
+ }
+ }
+ }
+ cbm_ht_free(seen);
+ return ok;
+}
+
+static void *mdr_build(const cbm_doclink_build_in_t *in) {
+ mdr_index_t *x = (mdr_index_t *)cbm_calloc(CBM_MEM_CLASS_OTHER, sizeof(*x));
+ if (!x) {
+ return NULL;
+ }
+ cbm_arena_init(&x->arena);
+ x->project = in->ctx ? in->ctx->project_name : NULL;
+ x->project_len = x->project ? strlen(x->project) : 0;
+ x->run_count = in->run_file_count;
+ x->run_paths = in->run_file_count > 0
+ ? (const char **)cbm_calloc(CBM_MEM_CLASS_OTHER,
+ (size_t)in->run_file_count * sizeof(char *))
+ : NULL;
+ x->basenames = cbm_ht_create_in(CBM_MEM_CLASS_HASH_TABLE, MDR_BASENAME_INIT);
+ x->pkgs = cbm_ht_create_in(CBM_MEM_CLASS_HASH_TABLE, MDR_BASENAME_INIT);
+ x->top = cbm_ht_create_in(CBM_MEM_CLASS_HASH_TABLE, MDR_BASENAME_INIT);
+ x->folders = cbm_ht_create_in(CBM_MEM_CLASS_HASH_TABLE, MDR_BASENAME_INIT);
+ if ((in->run_file_count > 0 && !x->run_paths) || !x->basenames || !x->pkgs || !x->top ||
+ !x->folders || !x->project || !mdr_build_pkgs(x, in->graph) ||
+ !mdr_build_defs(x, in->graph)) {
+ mdr_destroy(x);
+ return NULL;
+ }
+ for (int i = 0; i < in->file_count; i++) {
+ int rf = in->files[i].run_file;
+ if (rf >= 0 && rf < x->run_count) {
+ x->run_paths[rf] = in->files[i].rel_path; /* valid until destroy */
+ }
+ }
+ const cbm_gbuf_node_t **folders = NULL;
+ int nfolders = 0;
+ if (cbm_gbuf_find_by_label(in->graph, "Folder", &folders, &nfolders) == 0) {
+ for (int i = 0; i < nfolders; i++) {
+ if (folders[i]->file_path && folders[i]->file_path[0]) {
+ /* the graph outlives the index: its strings may be keys */
+ cbm_ht_set(x->folders, folders[i]->file_path, (void *)folders[i]);
+ }
+ }
+ }
+ const cbm_gbuf_node_t **files = NULL;
+ int nfiles = 0;
+ if (cbm_gbuf_find_by_label(in->graph, "File", &files, &nfiles) == 0) {
+ for (int i = 0; i < nfiles; i++) {
+ if (!files[i]->file_path || !files[i]->file_path[0]) {
+ continue;
+ }
+ const char *base = mdr_base(files[i]->file_path); /* the graph outlives the index */
+ uintptr_t n = (uintptr_t)cbm_ht_get(x->basenames, base);
+ cbm_ht_set(x->basenames, base, (void *)(n + SKIP_ONE));
+ }
+ }
+ return x;
+}
+
+static void mdr_destroy(void *index) {
+ mdr_index_t *x = (mdr_index_t *)index;
+ if (!x) {
+ return;
+ }
+ cbm_ht_free(x->basenames);
+ cbm_ht_free(x->pkgs);
+ cbm_ht_free(x->top);
+ cbm_ht_free(x->folders);
+ cbm_arena_destroy(&x->arena);
+ cbm_free(CBM_MEM_CLASS_OTHER, x->defs);
+ cbm_free(CBM_MEM_CLASS_OTHER, x->run_paths);
+ cbm_free(CBM_MEM_CLASS_OTHER, x);
+}
+
+/* ── Paths ───────────────────────────────────────────────────────── */
+
+static int mdr_hex(char c) {
+ if (c >= '0' && c <= '9') {
+ return c - '0';
+ }
+ if (c >= 'a' && c <= 'f') {
+ return c - 'a' + CBM_DECIMAL_BASE;
+ }
+ if (c >= 'A' && c <= 'F') {
+ return c - 'A' + CBM_DECIMAL_BASE;
+ }
+ return CBM_NOT_FOUND;
+}
+
+/* `base` + "/" + `p`, normalized: "." dropped, ".." pops a segment. False
+ * when the path climbs above the root or does not fit. */
+static bool mdr_join(const char *base, const char *p, char *out, size_t cap) {
+ size_t w = 0;
+ const char *parts[PAIR_LEN] = {base, p};
+ for (int k = 0; k < PAIR_LEN; k++) {
+ const char *s = parts[k];
+ while (s && *s) {
+ const char *e = strchr(s, '/');
+ size_t n = e ? (size_t)(e - s) : strlen(s);
+ if (n == 0 || (n == SKIP_ONE && s[0] == '.')) {
+ /* empty or "." */
+ } else if (n == PAIR_LEN && s[0] == '.' && s[SKIP_ONE] == '.') {
+ if (w == 0) {
+ return false;
+ }
+ while (w > 0 && out[w - SKIP_ONE] != '/') {
+ w--;
+ }
+ if (w > 0) {
+ w--; /* the slash before the popped segment */
+ }
+ } else {
+ if (w + n + PAIR_LEN > cap) {
+ return false;
+ }
+ if (w > 0) {
+ out[w++] = '/';
+ }
+ memcpy(out + w, s, n);
+ w += n;
+ }
+ s = e ? e + SKIP_ONE : NULL;
+ }
+ }
+ out[w] = '\0';
+ return true;
+}
+
+static const cbm_gbuf_node_t *mdr_folder(const mdr_index_t *x, const cbm_gbuf_t *graph,
+ const char *path) {
+ (void)graph;
+ return path[0] ? (const cbm_gbuf_node_t *)cbm_ht_get(x->folders, path) : NULL;
+}
+
+static bool mdr_code_label(const char *label) {
+ for (size_t i = 0; label && MDR_CODE_LABELS[i]; i++) {
+ if (strcmp(label, MDR_CODE_LABELS[i]) == 0) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/* The member text's last segment (after "::" or "."), and the one before it. */
+static void mdr_member_names(const char *member, const char **name, size_t *name_len,
+ const char **owner, size_t *owner_len) {
+ const char *segs[PAIR_LEN] = {NULL, NULL};
+ size_t lens[PAIR_LEN] = {0, 0};
+ const char *s = member;
+ while (*s) {
+ size_t n = strcspn(s, ":.");
+ if (n > 0) {
+ segs[0] = segs[SKIP_ONE];
+ lens[0] = lens[SKIP_ONE];
+ segs[SKIP_ONE] = s;
+ lens[SKIP_ONE] = n;
+ }
+ s += n;
+ while (*s == ':' || *s == '.') {
+ s++;
+ }
+ }
+ *name = segs[SKIP_ONE];
+ *name_len = lens[SKIP_ONE];
+ *owner = segs[0];
+ *owner_len = lens[0];
+}
+
+/* The QN segment before the node's own name ends with `owner`. */
+static bool mdr_owned_by(const cbm_gbuf_node_t *n, const char *owner, size_t owner_len) {
+ const char *qn = n->qualified_name;
+ size_t ql = qn ? strlen(qn) : 0;
+ size_t nl = n->name ? strlen(n->name) : 0;
+ if (!owner || ql < nl + owner_len + PAIR_LEN) {
+ return false;
+ }
+ size_t end = ql - nl - SKIP_ONE; /* the '.' before the name */
+ if (qn[end] != '.') {
+ return false;
+ }
+ size_t start = end - owner_len;
+ return memcmp(qn + start, owner, owner_len) == 0 && (start == 0 || qn[start - SKIP_ONE] == '.');
+}
+
+/* The code definitions of `path`: [*lo, *hi) of the index's sorted list. */
+static void mdr_file_defs(const mdr_index_t *x, const char *path, int *lo, int *hi) {
+ int a = 0;
+ int b = x->ndefs;
+ while (a < b) {
+ int mid = a + ((b - a) / PAIR_LEN);
+ if (strcmp(x->defs[mid].file, path) < 0) {
+ a = mid + SKIP_ONE;
+ } else {
+ b = mid;
+ }
+ }
+ int e = a;
+ while (e < x->ndefs && strcmp(x->defs[e].file, path) == 0) {
+ e++;
+ }
+ *lo = a;
+ *hi = e;
+}
+
+/* The code definition of file `path` that the range or the member names, or
+ * NULL. Read from the index's definitions by file, never from DEFINES edges:
+ * an incremental run's graph holds the edges of the files it re-extracts
+ * only, while every node is there. */
+static const cbm_gbuf_node_t *mdr_segment(const mdr_index_t *x, const char *path, uint32_t first,
+ uint32_t last, const char *member) {
+ int lo = 0;
+ int hi = 0;
+ mdr_file_defs(x, path, &lo, &hi);
+ const cbm_gbuf_node_t *best = NULL;
+ if (first > 0) {
+ for (int i = lo; i < hi; i++) {
+ const cbm_gbuf_node_t *n = x->defs[i].node;
+ if (n->start_line <= 0 || (uint32_t)n->start_line > first ||
+ (uint32_t)n->end_line < last) {
+ continue;
+ }
+ int span = n->end_line - n->start_line;
+ int best_span = best ? best->end_line - best->start_line : 0;
+ if (!best || span < best_span ||
+ (span == best_span && (n->start_line > best->start_line ||
+ (n->start_line == best->start_line && n->id < best->id)))) {
+ best = n;
+ }
+ }
+ if (best) {
+ return best;
+ }
+ }
+ if (!member) {
+ return NULL;
+ }
+ const char *name;
+ const char *owner;
+ size_t name_len;
+ size_t owner_len;
+ mdr_member_names(member, &name, &name_len, &owner, &owner_len);
+ if (!name) {
+ return NULL;
+ }
+ const cbm_gbuf_node_t *hit = NULL;
+ int hits = 0;
+ const cbm_gbuf_node_t *owned = NULL;
+ int owned_hits = 0;
+ for (int i = lo; i < hi; i++) {
+ const cbm_gbuf_node_t *n = x->defs[i].node;
+ if (!n->name || strlen(n->name) != name_len || memcmp(n->name, name, name_len) != 0) {
+ continue;
+ }
+ hit = n;
+ hits++;
+ if (owner && mdr_owned_by(n, owner, owner_len)) {
+ owned = n;
+ owned_hits++;
+ }
+ }
+ if (owned_hits == SKIP_ONE) {
+ return owned;
+ }
+ return owned_hits == 0 && hits == SKIP_ONE ? hit : NULL;
+}
+
+/* Is `path` of a file type the indexer reads? */
+static bool mdr_indexable(const char *path) {
+ return cbm_language_for_filename(mdr_base(path)) != CBM_LANG_COUNT;
+}
+
+/* ── Qualified names ─────────────────────────────────────────────── */
+
+/* Path pieces a written qualifier may leave out (`pkg.Foo` for
+ * `pkg/src/Foo`, `pkg.mod.Foo` for `pkg/mod.rs`'s Foo). */
+static const char *const MDR_TRANSPARENT[] = {
+ "src", "lib", "mod", "__init__", "index", "main", "java", "kotlin", "scala", "groovy", NULL};
+
+/* Directory names and file names of test code. */
+static const char *const MDR_TEST_DIRS[] = {"test",
+ "tests",
+ "testing",
+ "__tests__",
+ "spec",
+ "specs",
+ "testdata",
+ "test_data",
+ "fixtures",
+ "e2e",
+ "integration_tests",
+ "testutil",
+ "testutils",
+ "benchmark",
+ "benchmarks",
+ "bench",
+ "mocks",
+ "mock",
+ "fakes",
+ "fake",
+ "testlib",
+ NULL};
+
+static unsigned char mdr_norm_c(unsigned char c) {
+ if (c >= 'A' && c <= 'Z') {
+ return (unsigned char)(c - 'A' + 'a');
+ }
+ return c == '-' ? '_' : c;
+}
+
+/* Equal after lower-casing and reading '-' as '_'. */
+static bool mdr_norm_eq(const char *a, size_t al, const char *b, size_t bl) {
+ if (al != bl) {
+ return false;
+ }
+ for (size_t i = 0; i < al; i++) {
+ if (mdr_norm_c((unsigned char)a[i]) != mdr_norm_c((unsigned char)b[i])) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/* s[0..n) ends with `suffix`. */
+static bool mdr_ends(const char *s, size_t n, const char *suffix) {
+ size_t k = strlen(suffix);
+ return n >= k && memcmp(s + n - k, suffix, k) == 0;
+}
+
+static bool mdr_in(const char *s, size_t n, const char *const *list) {
+ for (size_t i = 0; list[i]; i++) {
+ if (mdr_norm_eq(s, n, list[i], strlen(list[i]))) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/* A test file or a file in a test directory. */
+static bool mdr_test_path(const char *path) {
+ const char *s = path;
+ for (const char *slash = strchr(s, '/'); slash; slash = strchr(s, '/')) {
+ if (mdr_in(s, (size_t)(slash - s), MDR_TEST_DIRS)) {
+ return true;
+ }
+ s = slash + SKIP_ONE;
+ }
+ const char *base = s;
+ if (strncmp(base, "test_", strlen("test_")) == 0 || strcmp(base, "conftest.py") == 0) {
+ return true;
+ }
+ const char *dot = strrchr(base, '.');
+ if (!dot) {
+ return false;
+ }
+ size_t stem = (size_t)(dot - base);
+ const char *ext = dot + SKIP_ONE;
+ bool lower_ext = ext[0] != '\0';
+ for (const char *e = ext; *e; e++) {
+ lower_ext = lower_ext && *e >= 'a' && *e <= 'z';
+ }
+ static const char *const jvm_like[] = {"java", "kt", "cs", "scala", "groovy", "php", NULL};
+ return (lower_ext && (mdr_ends(base, stem, "_test") || mdr_ends(base, stem, ".test") ||
+ mdr_ends(base, stem, ".spec"))) ||
+ (strcmp(ext, "rb") == 0 && mdr_ends(base, stem, "_spec")) ||
+ (mdr_in(ext, strlen(ext), jvm_like) &&
+ (mdr_ends(base, stem, "Test") || mdr_ends(base, stem, "Tests")));
+}
+
+typedef struct {
+ const char *path; /* as written (no fragment, decoded) */
+ uint32_t first;
+ uint32_t last;
+ const char *member;
+ bool name_only; /* a file name alone: the document's directory only */
+ bool dir; /* written as a directory */
+ bool link; /* a link: relative to the document by definition */
+} mdr_ref_t;
+
+static void mdr_edge(cbm_doclink_outcome_t *out, const cbm_gbuf_node_t *target, uint32_t first,
+ uint32_t last) {
+ out->kind = CBM_DOCLINK_EDGE;
+ out->target = target;
+ out->exact = true;
+ out->target_first = first;
+ out->target_last = last;
+}
+
+enum { MDR_MAX_PIECES = 80 }; /* a code span is at most 150 bytes */
+
+typedef struct {
+ const char *s[MDR_MAX_PIECES];
+ size_t n[MDR_MAX_PIECES];
+ int count;
+} mdr_pieces_t;
+
+/* The '.'-separated pieces of s. False when there are too many. */
+static bool mdr_split(const char *s, mdr_pieces_t *p) {
+ p->count = 0;
+ for (;;) {
+ if (p->count == MDR_MAX_PIECES) {
+ return false;
+ }
+ size_t n = strcspn(s, ".");
+ p->s[p->count] = s;
+ p->n[p->count] = n;
+ p->count++;
+ if (!s[n]) {
+ return true;
+ }
+ s += n + SKIP_ONE;
+ }
+}
+
+/* Is the written qualifier q[0..nq) a piece-aligned suffix of `chain` (a
+ * node's '.'-joined qualifier pieces), when chain pieces in MDR_TRANSPARENT
+ * may be skipped? `exact`: every piece as written; otherwise lower-cased and
+ * '-' read as '_' (`rootMulti.Store` names package rootmulti). */
+static bool mdr_chain_suffix(const char *chain, size_t clen, const mdr_pieces_t *q, int nq,
+ bool exact) {
+ size_t ce = clen;
+ bool more = clen > 0;
+ int j = nq - SKIP_ONE;
+ while (j >= 0) {
+ if (!more) {
+ return false;
+ }
+ size_t cs = ce;
+ while (cs > 0 && chain[cs - SKIP_ONE] != '.') {
+ cs--;
+ }
+ const char *piece = chain + cs;
+ size_t pl = ce - cs;
+ bool same = exact ? (pl == q->n[j] && memcmp(piece, q->s[j], pl) == 0)
+ : mdr_norm_eq(piece, pl, q->s[j], q->n[j]);
+ if (same) {
+ j--;
+ } else if (!mdr_in(piece, pl, MDR_TRANSPARENT)) {
+ return false;
+ }
+ more = cs > 0;
+ ce = more ? cs - SKIP_ONE : 0;
+ }
+ return true;
+}
+
+/* The node's qualifier chain (its QN without the project and its own name);
+ * false when the QN does not have that shape. */
+static bool mdr_node_chain(const mdr_index_t *x, const cbm_gbuf_node_t *n, const char **chain,
+ size_t *clen) {
+ const char *qn = n->qualified_name;
+ size_t name_len = n->name ? strlen(n->name) : 0;
+ if (!qn || name_len == 0 || strncmp(qn, x->project, x->project_len) != 0 ||
+ qn[x->project_len] != '.') {
+ return false;
+ }
+ const char *rest = qn + x->project_len + SKIP_ONE;
+ size_t rl = strlen(rest);
+ if (rl < name_len || strcmp(rest + rl - name_len, n->name) != 0) {
+ return false;
+ }
+ if (rl == name_len) {
+ *chain = rest;
+ *clen = 0;
+ return true;
+ }
+ if (rest[rl - name_len - SKIP_ONE] != '.') {
+ return false;
+ }
+ *chain = rest;
+ *clen = rl - name_len - SKIP_ONE;
+ return true;
+}
+
+static bool mdr_python_file(const char *path) {
+ return mdr_ends(path, strlen(path), ".py") || mdr_ends(path, strlen(path), ".pyi");
+}
+
+static bool mdr_classlike(const char *label) {
+ static const char *const labels[] = {"Class", "Struct", "Interface", "Trait",
+ "Enum", "Type", NULL};
+ for (size_t i = 0; label && labels[i]; i++) {
+ if (strcmp(label, labels[i]) == 0) {
+ return true;
+ }
+ }
+ return false;
+}
+
+/* Does the repository itself define the written root (`fastapi` of
+ * `fastapi.routing.X`): a top-level directory or code file, or a type? */
+static bool mdr_root_known(const mdr_index_t *x, const cbm_gbuf_t *graph, const char *root,
+ size_t len) {
+ char key[MDR_PATH_CAP];
+ if (len >= sizeof(key)) {
+ return false;
+ }
+ for (size_t i = 0; i < len; i++) {
+ key[i] = (char)mdr_norm_c((unsigned char)root[i]);
+ }
+ key[len] = '\0';
+ if (cbm_ht_get(x->top, key)) {
+ return true;
+ }
+ memcpy(key, root, len);
+ key[len] = '\0';
+ const cbm_gbuf_node_t **nodes = NULL;
+ int count = 0;
+ if (cbm_gbuf_find_by_name(graph, key, &nodes, &count) == 0) {
+ for (int i = 0; i < count; i++) {
+ if (mdr_classlike(nodes[i]->label) && nodes[i]->file_path &&
+ mdr_code_file(nodes[i]->file_path)) {
+ return true;
+ }
+ }
+ }
+ return false;
+}
+
+/* The one non-member definition named `name` in the module file `file`. */
+static const cbm_gbuf_node_t *mdr_module_item(const mdr_index_t *x, const char *file,
+ const char *name) {
+ int lo = 0;
+ int hi = 0;
+ mdr_file_defs(x, file, &lo, &hi);
+ const cbm_gbuf_node_t *hit = NULL;
+ for (int i = lo; i < hi; i++) {
+ const cbm_gbuf_node_t *n = x->defs[i].node;
+ if (!n->name || strcmp(n->name, name) != 0 || strcmp(n->label, "Method") == 0 ||
+ strcmp(n->label, "Field") == 0) {
+ continue;
+ }
+ if (hit) {
+ return NULL;
+ }
+ hit = n;
+ }
+ return hit;
+}
+
+/* Candidates of one class: the first one, and how many (counting stops at
+ * two: one is an edge, two are ambiguous). */
+typedef struct {
+ const cbm_gbuf_node_t *node;
+ const mdr_pkg_t *pkg;
+ int hits;
+} mdr_tally_t;
+
+static void mdr_tally(mdr_tally_t *t, const cbm_gbuf_node_t *node, const mdr_pkg_t *pkg) {
+ if (t->hits == 0) {
+ t->node = node;
+ t->pkg = pkg;
+ }
+ if (t->hits < PAIR_LEN) {
+ t->hits++;
+ }
+}
+
+/* A qualified name written in a code span: EXACT only. The one code
+ * definition named like its last piece whose qualifier chain ends with the
+ * written qualifier, or the one module or package so named. A match with
+ * every piece as written outranks one that needs case folding, so
+ * `fastapi.middleware` names the package fastapi/middleware, not the method
+ * FastAPI.middleware. Order: definitions as written, modules as written,
+ * definitions folded, modules folded; the first class with a candidate
+ * decides. */
+static void mdr_resolve_name(const mdr_index_t *x, const cbm_gbuf_t *graph, const char *doc,
+ const CBMDocLinkMdPath *p, cbm_doclink_outcome_t *out) {
+ mdr_pieces_t q;
+ out->kind = CBM_DOCLINK_UNRESOLVED;
+ out->reason = CBM_DOCLINK_REASON_UNPARSEABLE;
+ if (!mdr_split(p->path, &q) || q.count < PAIR_LEN) {
+ return;
+ }
+ int nq = q.count - SKIP_ONE; /* the qualifier pieces */
+ char name[MDR_PATH_CAP];
+ size_t name_len = q.n[nq];
+ if (name_len >= sizeof(name)) {
+ return;
+ }
+ memcpy(name, q.s[nq], name_len);
+ name[name_len] = '\0';
+ bool doc_test = mdr_test_path(doc);
+ enum { DEF_EXACT, MOD_EXACT, DEF_FOLDED, MOD_FOLDED, TALLIES };
+ mdr_tally_t tally[TALLIES] = {{0}};
+ int test_hits = 0;
+ const cbm_gbuf_node_t **nodes = NULL;
+ int count = 0;
+ if (cbm_gbuf_find_by_name(graph, name, &nodes, &count) != 0) {
+ count = 0;
+ }
+ for (int i = 0; i < count; i++) {
+ const cbm_gbuf_node_t *n = nodes[i];
+ const char *chain = NULL;
+ size_t clen = 0;
+ if (!mdr_code_label(n->label) || !n->file_path || !mdr_code_file(n->file_path) ||
+ !mdr_node_chain(x, n, &chain, &clen)) {
+ continue;
+ }
+ if (p->colon && !mdr_python_file(n->file_path)) {
+ continue; /* `module:attr` is Python's form */
+ }
+ if (strcmp(n->label, "Field") == 0) {
+ /* a field only through its type, written as the type is named:
+ * never through an instance (`self.x`, `app.state`) */
+ const char *owner = chain + clen;
+ while (owner > chain && owner[-SKIP_ONE] != '.') {
+ owner--;
+ }
+ size_t ol = (size_t)(chain + clen - owner);
+ if (p->instance || ol != q.n[nq - SKIP_ONE] ||
+ memcmp(owner, q.s[nq - SKIP_ONE], ol) != 0) {
+ continue;
+ }
+ }
+ bool exact = mdr_chain_suffix(chain, clen, &q, nq, true);
+ if (!exact && !mdr_chain_suffix(chain, clen, &q, nq, false)) {
+ continue;
+ }
+ if (!doc_test && mdr_test_path(n->file_path)) {
+ test_hits++;
+ continue;
+ }
+ mdr_tally(&tally[exact ? DEF_EXACT : DEF_FOLDED], n, NULL);
+ }
+ /* modules and packages so named */
+ for (const mdr_pkg_t *m = (const mdr_pkg_t *)cbm_ht_get(x->pkgs, name); m; m = m->next) {
+ size_t cl = strlen(m->chain);
+ bool exact = mdr_chain_suffix(m->chain, cl, &q, nq, true);
+ if (!exact && !mdr_chain_suffix(m->chain, cl, &q, nq, false)) {
+ continue;
+ }
+ if (!doc_test && mdr_test_path(m->file ? m->file : m->node->file_path)) {
+ test_hits++;
+ continue;
+ }
+ mdr_tally(&tally[exact ? MOD_EXACT : MOD_FOLDED], m->node, m);
+ }
+ for (int k = 0; k < TALLIES; k++) {
+ if (tally[k].hits == 0) {
+ continue;
+ }
+ if (tally[k].hits > SKIP_ONE) {
+ out->reason = CBM_DOCLINK_REASON_AMBIGUOUS;
+ return;
+ }
+ const mdr_pkg_t *mod = tally[k].pkg;
+ const cbm_gbuf_node_t *item = mod && mod->file ? mdr_module_item(x, mod->file, name) : NULL;
+ mdr_edge(out, item ? item : tally[k].node, 0, 0);
+ return;
+ }
+ if (test_hits > 0) {
+ out->reason = CBM_DOCLINK_REASON_TEST_ONLY;
+ return;
+ }
+ if (mdr_root_known(x, graph, q.s[0], q.n[0])) {
+ out->reason = CBM_DOCLINK_REASON_MISSING; /* the repository's name, but nothing so named */
+ return;
+ }
+ out->kind = CBM_DOCLINK_LOCAL; /* code of another project (a library, the standard one) */
+}
+
+static void mdr_resolve_path(const mdr_index_t *x, const cbm_gbuf_t *graph, const char *doc,
+ const mdr_ref_t *r, cbm_doclink_outcome_t *out) {
+ const char *p = r->path;
+ bool rooted = p[0] == '/';
+ bool relative = strncmp(p, "./", PAIR_LEN) == 0 || strncmp(p, "../", PAIR_LEN + 1) == 0;
+ char doc_dir[MDR_PATH_CAP];
+ const char *slash = strrchr(doc, '/');
+ size_t dl = slash ? (size_t)(slash - doc) : 0;
+ if (dl >= sizeof(doc_dir)) {
+ out->kind = CBM_DOCLINK_UNRESOLVED;
+ out->reason = CBM_DOCLINK_REASON_UNPARSEABLE;
+ return;
+ }
+ memcpy(doc_dir, doc, dl);
+ doc_dir[dl] = '\0';
+ char tries[MDR_TRIES][MDR_PATH_CAP];
+ int nt = 0;
+ int attempted = 0;
+ if (!rooted) {
+ attempted++;
+ nt += mdr_join(doc_dir, p, tries[nt], MDR_PATH_CAP);
+ }
+ if (!relative && !r->name_only) {
+ attempted++;
+ const char *q = p;
+ while (*q == '/') {
+ q++;
+ }
+ if (mdr_join("", q, tries[nt], MDR_PATH_CAP) && (nt == 0 || strcmp(tries[0], tries[nt]))) {
+ nt++;
+ }
+ }
+ for (int i = 0; i < nt; i++) {
+ const char *t = tries[i];
+ if (!t[0]) {
+ continue; /* the repository root itself */
+ }
+ const cbm_gbuf_node_t *file = cbm_pipeline_file_node(graph, x->project, t);
+ if (file) {
+ if (strcmp(t, doc) == 0) {
+ out->kind = CBM_DOCLINK_LOCAL; /* a link into the same document */
+ return;
+ }
+ const cbm_gbuf_node_t *seg = (r->first > 0 || r->member)
+ ? mdr_segment(x, t, r->first, r->last, r->member)
+ : NULL;
+ mdr_edge(out, seg ? seg : file, r->first, r->last);
+ return;
+ }
+ const cbm_gbuf_node_t *folder = mdr_folder(x, graph, t);
+ if (folder) {
+ mdr_edge(out, folder, 0, 0);
+ return;
+ }
+ }
+ out->kind = CBM_DOCLINK_UNRESOLVED;
+ if ((attempted > 0 && nt == 0) || (!r->dir && !mdr_indexable(p))) {
+ /* above the repository root; a file or a page the indexer does not read */
+ out->kind = CBM_DOCLINK_LOCAL;
+ return;
+ }
+ if (r->name_only && !r->link && cbm_ht_get(x->basenames, mdr_base(p))) {
+ out->reason = CBM_DOCLINK_REASON_AMBIGUOUS;
+ return;
+ }
+ /* doc rot when the reference points into the repository: its directory is
+ * there (a bare name in a link: the document's own directory) */
+ for (int i = 0; i < nt; i++) {
+ char parent[MDR_PATH_CAP];
+ const char *ps = strrchr(tries[i], '/');
+ size_t pl = ps ? (size_t)(ps - tries[i]) : 0;
+ memcpy(parent, tries[i], pl);
+ parent[pl] = '\0';
+ if (pl > 0 && mdr_folder(x, graph, parent) && (strchr(p, '/') || r->link)) {
+ out->reason = CBM_DOCLINK_REASON_MISSING;
+ return;
+ }
+ if (pl == 0 && r->link && !rooted) {
+ out->reason = CBM_DOCLINK_REASON_MISSING;
+ return;
+ }
+ }
+ out->kind = CBM_DOCLINK_LOCAL; /* not in this repository, nor its directory */
+}
+
+/* A link destination: `<...>` dropped, %XX decoded, `#L` fragment read, query
+ * dropped. False when nothing of a path is left (an anchor or a query). */
+static bool mdr_link_path(const char *raw, char *buf, size_t cap, mdr_ref_t *r) {
+ size_t n = strlen(raw);
+ while (n > 0 && (raw[0] == '<' || raw[0] == '>')) {
+ raw++;
+ n--;
+ }
+ while (n > 0 && (raw[n - SKIP_ONE] == '<' || raw[n - SKIP_ONE] == '>')) {
+ n--;
+ }
+ size_t w = 0;
+ for (size_t i = 0; i < n; i++) {
+ if (w + SKIP_ONE >= cap) {
+ return false;
+ }
+ int h1 = i + PAIR_LEN < n && raw[i] == '%' ? mdr_hex(raw[i + SKIP_ONE]) : CBM_NOT_FOUND;
+ int h2 = h1 >= 0 ? mdr_hex(raw[i + PAIR_LEN]) : CBM_NOT_FOUND;
+ if (h1 >= 0 && h2 >= 0 && (h1 * MDR_HEX_BASE) + h2 != 0) {
+ buf[w++] = (char)((h1 * MDR_HEX_BASE) + h2);
+ i += MDR_PCT_LEN - SKIP_ONE;
+ } else {
+ buf[w++] = raw[i];
+ }
+ }
+ buf[w] = '\0';
+ char *hash = strchr(buf, '#');
+ if (hash) {
+ *hash = '\0';
+ (void)cbm_doclink_md_line_fragment(hash + SKIP_ONE, &r->first, &r->last);
+ }
+ char *query = strchr(buf, '?');
+ if (query) {
+ *query = '\0';
+ }
+ r->path = buf;
+ r->dir = buf[0] && buf[strlen(buf) - SKIP_ONE] == '/';
+ r->name_only = !strchr(buf, '/');
+ return buf[0] != '\0';
+}
+
+static void mdr_resolve(const void *index, void *state, int run_file, const CBMDocLink *link,
+ const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {
+ (void)state;
+ const mdr_index_t *x = (const mdr_index_t *)index;
+ const char *doc = (run_file >= 0 && run_file < x->run_count) ? x->run_paths[run_file] : NULL;
+ if (!doc || !link->raw) {
+ out->kind = CBM_DOCLINK_UNRESOLVED;
+ out->reason = CBM_DOCLINK_REASON_UNPARSEABLE;
+ return;
+ }
+ char buf[MDR_PATH_CAP];
+ mdr_ref_t r = {0};
+ switch (link->syntax) {
+ case CBM_DOCLINK_MD_LINK:
+ r.link = true;
+ if (!mdr_link_path(link->raw, buf, sizeof(buf), &r)) {
+ out->kind = CBM_DOCLINK_LOCAL; /* an anchor, a query: nothing of a path */
+ return;
+ }
+ break;
+ case CBM_DOCLINK_MD_PATH: {
+ size_t n = strlen(link->raw);
+ if (n >= sizeof(buf)) {
+ break; /* longer than any path looked up: unparseable */
+ }
+ memcpy(buf, link->raw, n + SKIP_ONE);
+ r.path = buf;
+ break;
+ }
+ case CBM_DOCLINK_MD_CODE_NAME: {
+ CBMDocLinkMdPath p;
+ if (cbm_doclink_md_classify_span(link->raw, strlen(link->raw), buf, sizeof(buf), &p) &&
+ p.shape == CBM_DOCLINK_MD_QUALIFIED) {
+ mdr_resolve_name(x, graph, doc, &p, out);
+ return;
+ }
+ break;
+ }
+ case CBM_DOCLINK_MD_CODE_PATH: {
+ CBMDocLinkMdPath p;
+ if (!cbm_doclink_md_classify_span(link->raw, strlen(link->raw), buf, sizeof(buf), &p) ||
+ p.shape == CBM_DOCLINK_MD_QUALIFIED) {
+ break;
+ }
+ r.path = p.path;
+ r.member = p.member;
+ r.first = p.first_line;
+ r.last = p.last_line;
+ r.name_only = p.shape == CBM_DOCLINK_MD_FILENAME;
+ r.dir = p.shape == CBM_DOCLINK_MD_DIR;
+ if (r.dir && r.path[0] == '/' && !strchr(r.path + SKIP_ONE, '/')) {
+ /* `/docs`, `/health`: one rooted segment is a URL route, not the
+ * directory of that name (`/x/bank` stays a path) */
+ out->kind = CBM_DOCLINK_LOCAL;
+ return;
+ }
+ break;
+ }
+ default:
+ break;
+ }
+ if (!r.path || !r.path[0]) {
+ out->kind = CBM_DOCLINK_UNRESOLVED;
+ out->reason = CBM_DOCLINK_REASON_UNPARSEABLE;
+ return;
+ }
+ mdr_resolve_path(x, graph, doc, &r, out);
+}
+
+const cbm_doclink_resolver_t cbm_doclink_md_resolver = {
+ .langs = {CBM_LANG_MARKDOWN},
+ .lang_count = 1,
+ .scope_tag = NULL,
+ .build = mdr_build,
+ .destroy = mdr_destroy,
+ .resolve = mdr_resolve,
+ .via = "markdown",
+};
diff --git a/src/pipeline/pipeline_delta.c b/src/pipeline/pipeline_delta.c
index 8634a633e..a237881ec 100644
--- a/src/pipeline/pipeline_delta.c
+++ b/src/pipeline/pipeline_delta.c
@@ -300,7 +300,8 @@ int64_t cbm_delta_preseed(cbm_store_t *store, const char *project, cbm_gbuf_t *g
" CASE WHEN label IN ('Module','Variable')"
" AND instr(properties, '\"http_client\"') > 0"
" THEN json_object('http_client', json_extract(properties, '$.http_client'),"
- " 'http_base_url', json_extract(properties, '$.http_base_url')) END"
+ " 'http_base_url', json_extract(properties, '$.http_base_url')) END,"
+ " start_line, end_line"
" FROM nodes"
" WHERE project = ?1 AND label NOT IN"
" ('Macro','Comment','Section','Branch','Commit','Tag')"
@@ -318,10 +319,15 @@ int64_t cbm_delta_preseed(cbm_store_t *store, const char *project, cbm_gbuf_t *g
const char *qn = (const char *)sqlite3_column_text(stmt, 3);
const char *fp = (const char *)sqlite3_column_text(stmt, 4);
const char *client_props = (const char *)sqlite3_column_text(stmt, 5);
+ /* Lines too: a document reference that names a line range binds the
+ * definition holding it (doc_links_md.c), in a re-resolved document as
+ * in a full build. */
+ int start_line = sqlite3_column_int(stmt, 6);
+ int end_line = sqlite3_column_int(stmt, 7);
/* Pin the gbuf id to the database id: proxies ARE their rows. */
cbm_gbuf_set_next_id(gbuf, id);
- int64_t got = cbm_gbuf_upsert_node(gbuf, label, name, qn, fp ? fp : "", 0, 0,
- client_props ? client_props : "{}");
+ int64_t got = cbm_gbuf_upsert_node(gbuf, label, name, qn, fp ? fp : "", start_line,
+ end_line, client_props ? client_props : "{}");
if (got != id) {
/* A QN collision inside the preseed set would silently split
* identity between RAM and disk; the run cannot be trusted. */
diff --git a/tests/test_doc_links_md.c b/tests/test_doc_links_md.c
new file mode 100644
index 000000000..5f33416de
--- /dev/null
+++ b/tests/test_doc_links_md.c
@@ -0,0 +1,419 @@
+/*
+ * test_doc_links_md.c — Markdown documents -> MENTIONS edges.
+ *
+ * Extraction (doclink_md.c: which text is a reference, its family, line and
+ * section), the span classifier, the resolver (doc_links_md.c: paths, ranges,
+ * members, qualified names, the unresolved reasons, what is no reference at
+ * all), back navigation, and incremental == full. Pipeline tests index a real
+ * fixture through cbm_pipeline_run (helpers: test_doc_mentions_helpers.h).
+ */
+#include "../src/foundation/compat.h"
+#include "test_framework.h"
+#include "test_helpers.h"
+#include "test_doc_mentions_helpers.h"
+
+#include "cbm.h"
+#include "doclink.h"
+#include "pipeline/pipeline.h"
+#include "pipeline/pipeline_internal.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* ── the fixture ─────────────────────────────────────────────────── */
+
+/* docs/guide.md, line by line (the line numbers are asserted below). */
+static const char
+ MD_GUIDE[] = "Intro names `pkg/config.go` before any heading.\n" /* 1 */
+ "\n" /* 2 */
+ "# Guide\n" /* 3 */
+ "\n" /* 4 */
+ "See [the config](../pkg/config.go) and [routing][r].\n" /* 5 */
+ "\n" /* 6 */
+ "[r]: ../app/routing.py\n" /* 7 */
+ "\n" /* 8 */
+ "## Paths\n" /* 9 */
+ "\n" /* 10 */
+ "Range `app/routing.py#L4-L5`, span `app/routing.py:1-9`, bare "
+ "app/applications.py.\n" /* 11 */
+ "Dir `app/middleware/`, route `/docs`, ![x](img/a.png) and "
+ "https://example.org/a/b.py.\n" /* 12 */
+ "\n" /* 13 */
+ "## Names\n" /* 14 */
+ "\n" /* 15 */
+ "Use `app.routing.APIRouter.add`, `app.middleware`, `pkg.Config.Name`, "
+ "`self.Name`.\n" /* 16 */
+ "Also `os.path.join`, `app.Nope`, `test_routing.only_in_tests`, `main.py`, "
+ "`../app/gone.py`.\n" /* 17 */
+ "\n" /* 18 */
+ "```\n" /* 19 */
+ "`app/fenced.py` inside a fence\n" /* 20 */
+ "```\n" /* 21 */
+ "<!-- `app/commented.py` in a comment -->\n" /* 22 */
+ "<code>app/html.py</code> in HTML, `cfg.Name` through an instance.\n"; /* 23 */
+
+static void md_write_fixture(const char *tmp) {
+ th_write_file(TH_PATH(tmp, "docs/guide.md"), MD_GUIDE);
+ th_write_file(TH_PATH(tmp, "app/__init__.py"), "");
+ th_write_file(TH_PATH(tmp, "app/routing.py"), "class APIRouter:\n" /* 1 */
+ " prefix = ''\n" /* 2 */
+ "\n" /* 3 */
+ " def add(self, p):\n" /* 4 */
+ " return p\n" /* 5 */
+ "\n" /* 6 */
+ "\n" /* 7 */
+ "def helper():\n" /* 8 */
+ " return 1\n"); /* 9 */
+ th_write_file(TH_PATH(tmp, "app/applications.py"), "class App:\n"
+ " def middleware(self):\n"
+ " return None\n");
+ th_write_file(TH_PATH(tmp, "app/middleware/__init__.py"), "VALUE = 1\n");
+ th_write_file(TH_PATH(tmp, "tests/test_routing.py"), "def only_in_tests():\n"
+ " return 0\n");
+ th_write_file(TH_PATH(tmp, "lib/main.py"), "def run():\n"
+ " return None\n");
+ th_write_file(TH_PATH(tmp, "pkg/config.go"), "package pkg\n"
+ "\n"
+ "type Config struct {\n"
+ "\tName string\n"
+ "}\n"
+ "\n"
+ "func Util() {}\n");
+}
+
+/* ── extraction ──────────────────────────────────────────────────── */
+
+static const CBMDocLink *md_token(const CBMFileResult *r, const char *raw) {
+ return dm_find_token(r, raw);
+}
+
+static bool md_ends_with(const char *s, const char *suffix) {
+ size_t a = s ? strlen(s) : 0;
+ size_t b = strlen(suffix);
+ return a >= b && strcmp(s + a - b, suffix) == 0;
+}
+
+TEST(doc_links_md_extract_tokens) {
+ CBMFileResult *r = dm_extract(MD_GUIDE, CBM_LANG_MARKDOWN, "docs/guide.md");
+ ASSERT_NOT_NULL(r);
+ ASSERT_FALSE(r->doc_links.failed);
+ /* before the first heading: the file is the source */
+ const CBMDocLink *t = md_token(r, "pkg/config.go");
+ ASSERT_NOT_NULL(t);
+ ASSERT_EQ(t->line, 1);
+ ASSERT_EQ(t->syntax, CBM_DOCLINK_MD_CODE_PATH);
+ ASSERT_TRUE((t->flags & CBM_DOCLINK_FLAG_FILE) != 0);
+ /* an inline link and a link reference definition, under "Guide" */
+ t = md_token(r, "../pkg/config.go");
+ ASSERT_NOT_NULL(t);
+ ASSERT_EQ(t->line, 5);
+ ASSERT_EQ(t->syntax, CBM_DOCLINK_MD_LINK);
+ ASSERT_TRUE(md_ends_with(t->source_qn, "Guide"));
+ ASSERT_EQ(t->def_line, 3);
+ ASSERT_EQ(t->flags & CBM_DOCLINK_FLAG_FILE, 0);
+ t = md_token(r, "../app/routing.py");
+ ASSERT_NOT_NULL(t);
+ ASSERT_EQ(t->line, 7);
+ ASSERT_EQ(t->syntax, CBM_DOCLINK_MD_LINK);
+ /* paths under "Paths" */
+ t = md_token(r, "app/routing.py#L4-L5");
+ ASSERT_NOT_NULL(t);
+ ASSERT_EQ(t->line, 11);
+ ASSERT_TRUE(md_ends_with(t->source_qn, "Paths"));
+ ASSERT_NOT_NULL(md_token(r, "app/routing.py:1-9"));
+ t = md_token(r, "app/applications.py");
+ ASSERT_NOT_NULL(t);
+ ASSERT_EQ(t->syntax, CBM_DOCLINK_MD_PATH);
+ ASSERT_NOT_NULL(md_token(r, "app/middleware/"));
+ ASSERT_NOT_NULL(md_token(r, "/docs")); /* a token; the resolver calls it a route */
+ /* an image, a URL: no tokens */
+ ASSERT_NULL(md_token(r, "img/a.png"));
+ ASSERT_NULL(md_token(r, "https://example.org/a/b.py"));
+ ASSERT_NULL(md_token(r, "a/b.py"));
+ /* qualified names under "Names" */
+ t = md_token(r, "app.routing.APIRouter.add");
+ ASSERT_NOT_NULL(t);
+ ASSERT_EQ(t->syntax, CBM_DOCLINK_MD_CODE_NAME);
+ ASSERT_EQ(t->line, 16);
+ ASSERT_TRUE(md_ends_with(t->source_qn, "Names"));
+ ASSERT_NOT_NULL(md_token(r, "pkg.Config.Name"));
+ ASSERT_NULL(md_token(r, "self.Name")); /* one identifier after `self.`: a bare name */
+ ASSERT_NOT_NULL(md_token(r, "os.path.join"));
+ ASSERT_NOT_NULL(md_token(r, "main.py"));
+ /* fenced code and HTML comments are not scanned; HTML <code> is */
+ ASSERT_NULL(md_token(r, "app/fenced.py"));
+ ASSERT_NULL(md_token(r, "app/commented.py"));
+ t = md_token(r, "app/html.py");
+ ASSERT_NOT_NULL(t);
+ ASSERT_EQ(t->line, 23);
+ cbm_free_result(r);
+ PASS();
+}
+
+/* Two headings with one title share one Section node, which owns only one of
+ * them: their references belong to the file, never to the other heading. */
+TEST(doc_links_md_repeated_headings) {
+ const char *src = "# Changes\n" /* 1 */
+ "\n" /* 2 */
+ "## Fixes\n" /* 3 */
+ "\n" /* 4 */
+ "See `app/one.py`.\n" /* 5 */
+ "\n" /* 6 */
+ "## Fixes\n" /* 7 */
+ "\n" /* 8 */
+ "See `app/two.py`.\n" /* 9 */
+ "\n" /* 10 */
+ "## Unique\n" /* 11 */
+ "\n" /* 12 */
+ "See `app/three.py`.\n"; /* 13 */
+ CBMFileResult *r = dm_extract(src, CBM_LANG_MARKDOWN, "CHANGES.md");
+ ASSERT_NOT_NULL(r);
+ const CBMDocLink *one = md_token(r, "app/one.py");
+ const CBMDocLink *two = md_token(r, "app/two.py");
+ const CBMDocLink *three = md_token(r, "app/three.py");
+ ASSERT_NOT_NULL(one);
+ ASSERT_NOT_NULL(two);
+ ASSERT_NOT_NULL(three);
+ ASSERT_TRUE((one->flags & CBM_DOCLINK_FLAG_FILE) != 0);
+ ASSERT_TRUE((two->flags & CBM_DOCLINK_FLAG_FILE) != 0);
+ ASSERT_EQ(three->flags & CBM_DOCLINK_FLAG_FILE, 0);
+ ASSERT_TRUE(md_ends_with(three->source_qn, "Unique"));
+ cbm_free_result(r);
+ PASS();
+}
+
+typedef struct {
+ const char *text;
+ CBMDocLinkMdShape shape;
+ const char *path;
+ const char *member;
+ uint32_t first;
+ uint32_t last;
+ bool instance;
+ bool colon;
+} md_case_t;
+
+TEST(doc_links_md_classify_span) {
+ static const md_case_t cases[] = {
+ {"src/app/main.go", CBM_DOCLINK_MD_FILE, "src/app/main.go", NULL, 0, 0, false, false},
+ {"src/app/", CBM_DOCLINK_MD_DIR, "src/app/", NULL, 0, 0, false, false},
+ {"src/app/main.go#L3-L9", CBM_DOCLINK_MD_FILE, "src/app/main.go", NULL, 3, 9, false, false},
+ {"src/app/main.go:12", CBM_DOCLINK_MD_FILE, "src/app/main.go", NULL, 12, 12, false, false},
+ {"src/lib.rs::Type::run", CBM_DOCLINK_MD_FILE, "src/lib.rs", "Type::run", 0, 0, false,
+ false},
+ {"src\\win\\file.cs", CBM_DOCLINK_MD_FILE, "src/win/file.cs", NULL, 0, 0, false, false},
+ {"main.go:7-8", CBM_DOCLINK_MD_FILENAME, "main.go", NULL, 7, 8, false, false},
+ {"README.md", CBM_DOCLINK_MD_FILENAME, "README.md", NULL, 0, 0, false, false},
+ {"Makefile", CBM_DOCLINK_MD_FILENAME, "Makefile", NULL, 0, 0, false, false},
+ {"main.rs::run", CBM_DOCLINK_MD_FILENAME, "main.rs", "run", 0, 0, false, false},
+ {"fastapi.routing.APIRouter", CBM_DOCLINK_MD_QUALIFIED, "fastapi.routing.APIRouter", NULL,
+ 0, 0, false, false},
+ {"crate::extract::Json", CBM_DOCLINK_MD_QUALIFIED, "extract.Json", NULL, 0, 0, false,
+ false},
+ {"Vec<u8>::new", CBM_DOCLINK_MD_QUALIFIED, "Vec.new", NULL, 0, 0, false, false},
+ {"self.app.state", CBM_DOCLINK_MD_QUALIFIED, "app.state", NULL, 0, 0, true, false},
+ {"pkg.module:attr", CBM_DOCLINK_MD_QUALIFIED, "pkg.module.attr", NULL, 0, 0, false, true},
+ {"Foo#bar", CBM_DOCLINK_MD_QUALIFIED, "Foo.bar", NULL, 0, 0, false, false},
+ {"App\\Http\\Kernel", CBM_DOCLINK_MD_QUALIFIED, "App.Http.Kernel", NULL, 0, 0, false,
+ false},
+ {"server.New()", CBM_DOCLINK_MD_QUALIFIED, "server.New", NULL, 0, 0, false, false},
+ /* no path and no qualified name */
+ {"foo", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"self.x", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"Node.js", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"github.com/x/y", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"https://x.org/a.py", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"$HOME/a.py", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"PATH=/usr/bin", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"--verbose", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"go run main.go", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"\"a/b.py\"", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"pkg/Type.Member", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ {"@scope/pkg", CBM_DOCLINK_MD_NONE, NULL, NULL, 0, 0, false, false},
+ };
+ for (size_t i = 0; i < sizeof(cases) / sizeof(cases[0]); i++) {
+ const md_case_t *c = &cases[i];
+ char buf[256];
+ CBMDocLinkMdPath p;
+ bool ok = cbm_doclink_md_classify_span(c->text, strlen(c->text), buf, sizeof(buf), &p);
+ if (ok != (c->shape != CBM_DOCLINK_MD_NONE) || p.shape != c->shape) {
+ printf(" case %s: shape %d, expected %d\n", c->text, (int)p.shape, (int)c->shape);
+ FAIL("classification differs");
+ }
+ if (!ok) {
+ continue;
+ }
+ if (strcmp(p.path, c->path) != 0 ||
+ (c->member ? !p.member || strcmp(p.member, c->member) != 0 : p.member != NULL) ||
+ p.first_line != c->first || p.last_line != c->last || p.instance != c->instance ||
+ p.colon != c->colon) {
+ printf(" case %s: path %s member %s lines %u-%u instance %d colon %d\n", c->text,
+ p.path, p.member ? p.member : "(none)", p.first_line, p.last_line, p.instance,
+ p.colon);
+ FAIL("classification differs");
+ }
+ }
+ /* a name never fits a buffer by being cut */
+ char tiny[8];
+ CBMDocLinkMdPath p;
+ ASSERT_FALSE(cbm_doclink_md_classify_span("src/app/main.go", 15, tiny, sizeof(tiny), &p));
+ PASS();
+}
+
+/* ── resolution ──────────────────────────────────────────────────── */
+
+/* Properties of the MENTIONS edge from the section or file whose qualified
+ * name ends with `src` to the node whose qualified name ends with `tgt`. */
+static int md_edge(const char *db, const char *src, const char *tgt, char *props, size_t cap) {
+ int n = 0;
+ dm_edge(db, src, tgt, props, cap, &n);
+ return n;
+}
+
+TEST(doc_links_md_resolve) {
+ char tmp[256];
+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlmd_XXXXXX");
+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+ md_write_fixture(tmp);
+ char db[512];
+ snprintf(db, sizeof(db), "%s/md.db", tmp);
+ ASSERT_EQ(dm_index(tmp, db, NULL), 0);
+ char props[512];
+ char reason[64];
+ char syntax[64];
+
+ /* a link and a link reference definition: their files */
+ ASSERT_EQ(md_edge(db, "Guide", "config.go.__file__", props, sizeof(props)), 1);
+ ASSERT_NOT_NULL(strstr(props, "\"via\":\"markdown\""));
+ ASSERT_NOT_NULL(strstr(props, "\"syntax\":\"link\""));
+ ASSERT_NOT_NULL(strstr(props, "\"tier\":\"exact\""));
+ ASSERT_NOT_NULL(strstr(props, "\"line\":5"));
+ ASSERT_EQ(md_edge(db, "Guide", "routing.py.__file__", props, sizeof(props)), 1);
+ /* the reference before the first heading: from the File node */
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "
+ "JOIN nodes t ON t.id = e.target_id WHERE e.type = 'MENTIONS' "
+ "AND s.label = 'File' AND s.file_path = 'docs/guide.md' "
+ "AND t.file_path = 'pkg/config.go' AND t.label = 'File'"),
+ 1);
+ /* a range held by one definition: that definition, the range on the edge */
+ ASSERT_EQ(md_edge(db, "Paths", "APIRouter.add", props, sizeof(props)), 1);
+ ASSERT_NOT_NULL(strstr(props, "\"target_lines\":[4,5]"));
+ ASSERT_NOT_NULL(strstr(props, "\"syntax\":\"code_path\""));
+ /* a range across definitions: the file, with the range */
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "
+ "JOIN nodes t ON t.id = e.target_id WHERE e.type = 'MENTIONS' "
+ "AND s.qualified_name LIKE '%.Paths' AND t.label = 'File' "
+ "AND t.file_path = 'app/routing.py' "
+ "AND e.properties LIKE '%\"target_lines\":[1,9]%'"),
+ 1);
+ /* a bare path in prose; a directory */
+ ASSERT_EQ(md_edge(db, "Paths", "applications.py.__file__", props, sizeof(props)), 1);
+ ASSERT_NOT_NULL(strstr(props, "\"syntax\":\"path\""));
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "
+ "JOIN nodes t ON t.id = e.target_id WHERE e.type = 'MENTIONS' "
+ "AND s.qualified_name LIKE '%.Paths' AND t.label = 'Folder' "
+ "AND t.file_path = 'app/middleware'"),
+ 1);
+ /* a route, an image, a URL: neither edges nor rows */
+ dm_row(db, "docs/guide.md", "/docs", reason, sizeof(reason), NULL, 0);
+ ASSERT_STR_EQ(reason, "");
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes t ON t.id = e.target_id "
+ "WHERE e.type = 'MENTIONS' AND t.label = 'Folder' "
+ "AND t.file_path = 'docs'"),
+ 0);
+ dm_row(db, "docs/guide.md", "img/a.png", reason, sizeof(reason), NULL, 0);
+ ASSERT_STR_EQ(reason, "");
+
+ /* qualified names: a method, a field through its type */
+ ASSERT_EQ(md_edge(db, "Names", "routing.APIRouter.add", props, sizeof(props)), 1);
+ ASSERT_NOT_NULL(strstr(props, "\"syntax\":\"code_name\""));
+ ASSERT_EQ(md_edge(db, "Names", "Config.Name", props, sizeof(props)), 1);
+ /* `app.middleware`: the package as written, not the method App.middleware */
+ ASSERT_EQ(md_edge(db, "Names", "App.middleware", props, sizeof(props)), 0);
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "
+ "JOIN nodes t ON t.id = e.target_id WHERE e.type = 'MENTIONS' "
+ "AND s.qualified_name LIKE '%.Names' "
+ "AND t.file_path = 'app/middleware/__init__.py'"),
+ 1);
+ /* a field never through an instance */
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes t ON t.id = e.target_id "
+ "WHERE e.type = 'MENTIONS' AND t.label = 'Field' "
+ "AND e.properties LIKE '%\"line\":23%'"),
+ 0);
+
+ /* unresolved, by reason */
+ dm_row(db, "docs/guide.md", "app.Nope", reason, sizeof(reason), syntax, sizeof(syntax));
+ ASSERT_STR_EQ(reason, "missing");
+ ASSERT_STR_EQ(syntax, "code_name");
+ dm_row(db, "docs/guide.md", "test_routing.only_in_tests", reason, sizeof(reason), NULL, 0);
+ ASSERT_STR_EQ(reason, "test_only_target");
+ dm_row(db, "docs/guide.md", "main.py", reason, sizeof(reason), NULL, 0);
+ ASSERT_STR_EQ(reason, "ambiguous"); /* lib/main.py, but not next to the document */
+ dm_row(db, "docs/guide.md", "../app/gone.py", reason, sizeof(reason), NULL, 0);
+ ASSERT_STR_EQ(reason, "missing");
+ dm_row(db, "docs/guide.md", "app/html.py", reason, sizeof(reason), NULL, 0);
+ ASSERT_STR_EQ(reason, "missing");
+ /* another project's code is no reference to this repository */
+ dm_row(db, "docs/guide.md", "os.path.join", reason, sizeof(reason), NULL, 0);
+ ASSERT_STR_EQ(reason, "");
+
+ /* back navigation: the sections that mention a method, one hop away */
+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "
+ "JOIN nodes t ON t.id = e.target_id WHERE e.type = 'MENTIONS' "
+ "AND t.qualified_name LIKE '%.APIRouter.add' AND s.label = 'Section'"),
+ 2);
+
+ th_cleanup(tmp);
+ PASS();
+}
+
+/* ── incremental == full ─────────────────────────────────────────── */
+
+TEST(doc_links_md_incremental) {
+ char tmp[256];
+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlmd_inc_XXXXXX");
+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));
+ char repo[512];
+ snprintf(repo, sizeof(repo), "%s/repo", tmp);
+ md_write_fixture(repo);
+ char db[512];
+ char full_db[512];
+ snprintf(db, sizeof(db), "%s/inc.db", tmp);
+ snprintf(full_db, sizeof(full_db), "%s/full.db", tmp);
+ ASSERT_EQ(dm_index(repo, db, NULL), 0);
+
+ /* a body edit of a linked code file: its linking document re-resolves */
+ th_write_file(TH_PATH(repo, "app/routing.py"), "class APIRouter:\n"
+ " prefix = ''\n"
+ "\n"
+ " def add(self, p):\n"
+ " return p + p\n"
+ "\n"
+ "\n"
+ "def helper():\n"
+ " return 2\n");
+ ASSERT_EQ(dm_step(repo, db, full_db, "code body edit", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR),
+ 0);
+ /* the document itself changes: a new link, a reference gone */
+ char guide[sizeof(MD_GUIDE) + 64];
+ snprintf(guide, sizeof(guide), "%s\nSee also [helpers](../app/routing.py#L8-L9).\n", MD_GUIDE);
+ th_write_file(TH_PATH(repo, "docs/guide.md"), guide);
+ ASSERT_EQ(dm_step(repo, db, full_db, "document edit", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);
+ /* the name a row calls missing is added: the run goes FULL and the row
+ * becomes an edge, exactly as a full index has it */
+ th_write_file(TH_PATH(repo, "app/nope.py"), "def Nope():\n"
+ " return None\n");
+ ASSERT_EQ(dm_step(repo, db, full_db, "missing name added", CBM_INCREMENTAL_ROUTE_FORCED_FULL),
+ 0);
+ th_cleanup(tmp);
+ PASS();
+}
+
+SUITE(doc_links_md) {
+ RUN_TEST(doc_links_md_extract_tokens);
+ RUN_TEST(doc_links_md_repeated_headings);
+ RUN_TEST(doc_links_md_classify_span);
+ RUN_TEST(doc_links_md_resolve);
+ RUN_TEST(doc_links_md_incremental);
+}
diff --git a/tests/test_main.c b/tests/test_main.c
index dcbc1252c..a4fa4a154 100644
--- a/tests/test_main.c
+++ b/tests/test_main.c
@@ -1821,6 +1821,7 @@ extern void suite_doclinks(void);
extern void suite_doc_mentions(void);
extern void suite_doc_mentions_cost(void);
extern void suite_doc_mentions_msbuild(void);
+extern void suite_doc_links_md(void);
extern void suite_infrascan(void);
extern void suite_cli(void);
extern void suite_agent_clients(void);
@@ -2288,6 +2289,7 @@ int main(int argc, char **argv) {
RUN_SELECTED_SUITE(doc_mentions);
RUN_SELECTED_SUITE(doc_mentions_cost);
RUN_SELECTED_SUITE(doc_mentions_msbuild);
+ RUN_SELECTED_SUITE(doc_links_md);
/* Infrastructure scanning */
RUN_SELECTED_SUITE(infrascan);