Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
doc-links(perl): POD L<> codes become MENTIONS edges, held until their audit
Martin Vogelf4277ae783de
diff --git a/Makefile.cbm b/Makefile.cbmindex 43999c35c..b8aa4f71e 100644--- a/Makefile.cbm+++ b/Makefile.cbm@@ -389,6 +389,7 @@ EXTRACTION_SRCS = \$(CBM_DIR)/doclink_go.c \$(CBM_DIR)/doclink_jvm.c \$(CBM_DIR)/doclink_rs.c \+ $(CBM_DIR)/doclink_perl.c \$(CBM_DIR)/sql_values.c \$(CBM_DIR)/helpers.c \$(CBM_DIR)/cpp_branch_views.c \@@ -518,6 +519,7 @@ PIPELINE_SRCS = \src/pipeline/doc_links_go.c \src/pipeline/doc_links_jvm.c \src/pipeline/doc_links_rs.c \+ src/pipeline/doc_links_perl.c \src/pipeline/doc_links_msbuild.c \src/pipeline/pass_route_nodes.c \src/pipeline/pass_enrichment.c \@@ -780,7 +782,7 @@ TEST_DISCOVER_SRCS = \TEST_GRAPH_BUFFER_SRCS = tests/test_graph_buffer.c-TEST_PIPELINE_SRCS = tests/test_registry.c tests/test_pipeline.c tests/test_pipeline_conventions.c tests/test_pipeline_frozen.c tests/test_importance.c tests/test_cross_repo.c tests/test_fqn.c tests/test_route_canon.c tests/test_path_alias.c tests/test_configlink.c tests/test_doclinks.c tests/test_doc_mentions.c tests/test_doc_links_md.c tests/test_doc_links_pdf.c tests/test_doc_links_rst.c tests/test_doc_links_adoc.c tests/test_doc_mentions_go.c tests/test_doc_mentions_jvm.c tests/test_doc_mentions_rs.c tests/test_infrascan.c tests/test_worker_pool.c tests/test_parallel.c tests/test_index_resilience.c tests/test_index_format.c tests/test_call_reference_contract.c tests/repro/repro_call_scope_usages.c tests/repro/repro_call_argument_usages.c tests/repro/repro_reference_precision.c tests/repro/repro_lexical_binding_precision.c tests/repro/repro_call_argument_matrix_a.c tests/repro/repro_call_argument_matrix_b.c tests/repro/repro_call_node_behaviors.c tests/repro/repro_language_registry.c tests/repro/repro_call_node_manifest.c tests/repro/repro_lsp_ordered_signatures.c tests/repro/repro_lsp_ordered_local.c tests/repro/repro_ts_overload_return_chains.c tests/repro/repro_harness_cleanup.c tests/repro/repro_runner_filter.c+TEST_PIPELINE_SRCS = tests/test_registry.c tests/test_pipeline.c tests/test_pipeline_conventions.c tests/test_pipeline_frozen.c tests/test_importance.c tests/test_cross_repo.c tests/test_fqn.c tests/test_route_canon.c tests/test_path_alias.c tests/test_configlink.c tests/test_doclinks.c tests/test_doc_mentions.c tests/test_doc_links_md.c tests/test_doc_links_pdf.c tests/test_doc_links_rst.c tests/test_doc_links_adoc.c tests/test_doc_mentions_go.c tests/test_doc_mentions_jvm.c tests/test_doc_mentions_rs.c tests/test_doc_mentions_perl.c tests/test_infrascan.c tests/test_worker_pool.c tests/test_parallel.c tests/test_index_resilience.c tests/test_index_format.c tests/test_call_reference_contract.c tests/repro/repro_call_scope_usages.c tests/repro/repro_call_argument_usages.c tests/repro/repro_reference_precision.c tests/repro/repro_lexical_binding_precision.c tests/repro/repro_call_argument_matrix_a.c tests/repro/repro_call_argument_matrix_b.c tests/repro/repro_call_node_behaviors.c tests/repro/repro_language_registry.c tests/repro/repro_call_node_manifest.c tests/repro/repro_lsp_ordered_signatures.c tests/repro/repro_lsp_ordered_local.c tests/repro/repro_ts_overload_return_chains.c tests/repro/repro_harness_cleanup.c tests/repro/repro_runner_filter.cTEST_WATCHER_SRCS = tests/test_watcher.cdiff --git a/internal/cbm/doclink.c b/internal/cbm/doclink.cindex 92892d6e3..4957e5489 100644--- a/internal/cbm/doclink.c+++ b/internal/cbm/doclink.c@@ -211,6 +211,12 @@ static const doclink_lang_t DOCLINK_LANGS[] = {.scan_scope = cbm_doclink_rs_manifest_scan_scope,.scope_tag = CBM_DOCLINK_RS_SCOPE_TAG,.portable_scope = cbm_doclink_rs_portable_scope},+ /* Perl: POD L<> codes; the scope blob carries no lines, so it persists as+ * it is */+ {.lang = CBM_LANG_PERL,+ .parse_doc = cbm_doclink_perl_parse_doc,+ .scan_scope = cbm_doclink_perl_scan_scope,+ .scope_tag = CBM_DOCLINK_PERL_SCOPE_TAG},};static const doclink_lang_t *doclink_lang(CBMLanguage lang) {diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.hindex 4a5127437..479d104ff 100644--- a/internal/cbm/doclink.h+++ b/internal/cbm/doclink.h@@ -98,6 +98,8 @@/* rust (doclink_rs.c): intra-doc links; held until their audit passes */ \X(CBM_DOCLINK_RS_INTRA_DOC, CBM_LANG_RUST, "intra_doc", false, false, "MENTIONS") \X(CBM_DOCLINK_RS_LINK_DEF, CBM_LANG_RUST, "link_def", false, false, "MENTIONS") \+ /* perl (doclink_perl.c): POD L<> codes; held until their audit passes */ \+ X(CBM_DOCLINK_PERL_POD_L, CBM_LANG_PERL, "pod_L", false, false, "MENTIONS") \/* markdown (doclink_md.c): what a document's text names explicitly */ \X(CBM_DOCLINK_MD_LINK, CBM_LANG_MARKDOWN, "link", false, true, "MENTIONS") \X(CBM_DOCLINK_MD_PATH, CBM_LANG_MARKDOWN, "path", false, true, "MENTIONS") \@@ -535,5 +537,47 @@ typedef enum {* are read. */CBMDocLinkRsPathStatus cbm_doclink_rs_parse_path(const char *raw, size_t len, bool lenient,CBMDocLinkRsPath *out);+/* ── Perl POD (doclink_perl.c) ─────────────────────────────────────── */++void cbm_doclink_perl_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,+ uint32_t doc_line);+const char *cbm_doclink_perl_scan_scope(CBMExtractCtx *ctx);++/* The Perl scope blob starts with this tag line. */+#define CBM_DOCLINK_PERL_SCOPE_TAG "perl1"++enum {+ /* Longest L<> content kept as a token's raw text; a longer one is cut and+ * marked malformed (its raw text then starts with `L<`). */+ CBM_DOCLINK_PERL_RAW_MAX = 512,+ /* Buffer for a page name, a section text or a heading key. */+ CBM_DOCLINK_PERL_KEY_MAX = 256,+};++/* A POD text as it renders: formatting codes replaced by their content+ * (X<> and Z<> by nothing, E<> by its character), white-space runs as one+ * space, none at the ends. Headings and the section part of a link are+ * compared in this form. Writes a NUL-terminated string into `out` (cut at+ * cap - 1, never inside a UTF-8 character) and returns its length. */+size_t cbm_doclink_perl_plain_text(const char *in, size_t len, char *out, size_t cap);++typedef enum {+ CBM_PERL_LINK_UNPARSEABLE = 0, /* malformed, nested L<>, or no page name */+ CBM_PERL_LINK_PAGE, /* L<Module::Name> or L<Module::Name/section> */+ CBM_PERL_LINK_SECTION, /* L</section>, L<"section">: the same page */+ CBM_PERL_LINK_MAN, /* L<name(3)>: a man page */+} CBMPerlLinkKind;++/* One pod_L token's raw text, split the way perlpodspec splits it. */+typedef struct {+ CBMPerlLinkKind kind;+ char page[CBM_DOCLINK_PERL_KEY_MAX]; /* "" for a section of the same page */+ char section[CBM_DOCLINK_PERL_KEY_MAX]; /* "" when only a page is named */+} CBMPerlLink;++/* Split a pod_L token's raw text: the first top-level `|` ends the link text,+ * the first top-level `/` after it separates page and section, quotes around+ * a section are dropped. False (kind UNPARSEABLE) for anything else. */+bool cbm_doclink_perl_parse_link(const char *raw, CBMPerlLink *out);#endif /* CBM_DOCLINK_H */diff --git a/internal/cbm/doclink_perl.c b/internal/cbm/doclink_perl.cnew file mode 100644index 000000000..42bdb72de--- /dev/null+++ b/internal/cbm/doclink_perl.c@@ -0,0 +1,1677 @@+/*+ * doclink_perl.c — Perl POD `L<>` references and the Perl doc-link scope.+ *+ * Tokens. A sub's stored doc is every POD section whose =headN / =item heading+ * names it (extract_defs.c), verbatim and joined by a blank line. Its L<>+ * formatting codes are the references, read the way perlpodspec and+ * Pod::Simple read them:+ * - a paragraph is a run of non-blank lines. Codes are looked for in ordinary+ * paragraphs and in the text of =headN and =item. A verbatim paragraph+ * (first byte a space or tab), a =for paragraph and a =begin .. =end+ * region of a format without a leading colon are data and hold no code;+ * - a code is a capital letter and `<`. `X<< text >>` (two or more brackets+ * and whitespace) ends at whitespace and as many `>`. Codes nest; an L+ * inside an L is not a link (perlpodspec: links must not nest);+ * - an L<> whose target (what follows `text|`) matches `\w+:[^:\s]\S*` is a+ * URL: the core's href family. Every other one is a pod_L token whose raw+ * text is the code's content as written, white space squeezed. A code the+ * paragraph ends before, and one longer than CBM_DOCLINK_PERL_RAW_MAX,+ * keeps its opening `L<` in the raw text: nothing parses that, so the+ * resolver records it as unparseable.+ * A doc that does not start with a POD command is a `#` comment and has no+ * formatting codes at all.+ *+ * Lines. The stored doc carries no position, and several sections can be+ * joined in it, so every section of the file is found again here (the same+ * paragraph, command and section rules as extract_defs.c) and the doc is+ * matched against them byte for byte: a reference then gets the source line it+ * is written on. A part of a doc that matches no section keeps the line the+ * core passed (the definition's). That needs the file's sections once per+ * file, and parse_doc is called per definition: the call for the file's first+ * documented definition harvests the whole file, the later ones return.+ *+ * Scope blob (one record per line, tab-separated, first line "perl1"; no line+ * numbers, so it is persisted as it is):+ * E the tree has a parse error: which package a sub belongs to+ * is not trusted+ * P name a package, class or role the file declares; document+ * order, each name once+ * S pkg name a sub that has a definition, in definition order; pkg is+ * the 0-based index of its P record, `-` before any package+ * (main), `?` when it could not be placed+ * H sub key a POD heading (=headN / =item): `key` is its text with+ * formatting codes reduced to what they render+ * (cbm_doclink_perl_plain_text) and an item's bullet+ * dropped; `sub` is the identifier the heading names by+ * extract_defs.c's rule, `-` when it names none+ * Packages and the placement of subs come from the tree; the subs themselves+ * from the file's definitions (so a sub listed here has a node); the headings+ * from a line scan of the file, which is what perldoc reads.+ */+#include "doclink.h"++#include "arena.h"+#include "foundation/constants.h"+#include "tree_sitter/api.h"++#include <ctype.h>+#include <stdio.h>+#include <stdlib.h>+#include <string.h>++enum {+ PL_CODE_DEPTH = 32, /* open formatting codes; deeper nesting is malformed */+ PL_INIT_CAP = 32,+ PL_SB_INIT = 1024,+ PL_ENT_MAX = 12, /* longest E<> body that is decoded */+ PL_MALFORMED = 2, /* strlen("L<"): what a malformed code's raw text starts with */+ PL_UTF8_CONT = 0x80, /* 10xxxxxx */+ PL_UTF8_CONT_MASK = 0xC0,+ PL_UTF8_LEAD2 = 0xC0,+ PL_UTF8_LEAD3 = 0xE0,+ PL_UTF8_LEAD4 = 0xF0,+ PL_UTF8_LEAD_END = 0xF8,+ PL_ASCII_DEL = 0x7F,+ PL_HEAD_WORD = 5, /* strlen("headN") */+ PL_NAME_MAX = 255,+};++/* ── Characters ──────────────────────────────────────────────────── */++static bool pl_blank(char c) {+ return c == ' ' || c == '\t' || c == '\r';+}++static bool pl_space(char c) {+ return c == ' ' || c == '\t' || c == '\r' || c == '\n' || c == '\f' || c == '\v';+}++static bool pl_word(char c) {+ return isalnum((unsigned char)c) || c == '_';+}++static bool pl_upper(char c) {+ return c >= 'A' && c <= 'Z';+}++/* A control byte that is not white space: never copied into a blob record or+ * a raw text (a NUL would end either). */+static bool pl_control(char c) {+ unsigned char u = (unsigned char)c;+ return (u < ' ' && !pl_space(c)) || u == PL_ASCII_DEL;+}++static CBMArena *pl_scratch(CBMExtractCtx *ctx) {+ return ctx->scratch ? ctx->scratch : ctx->arena;+}++/* ── Paragraphs ──────────────────────────────────────────────────── */++/* Next paragraph (a maximal run of non-blank lines) of s[*pos, end): [*pb,+ * *pe). The same rule as extract_defs.c's pod_next_para. */+static bool pl_next_para(const char *s, size_t *pos, size_t end, size_t *pb, size_t *pe) {+ size_t i = *pos;+ bool in = false;+ size_t start = 0;+ while (i < end) {+ const char *nl = (const char *)memchr(s + i, '\n', end - i);+ size_t le = nl ? (size_t)(nl - s) : end;+ bool blank = true;+ for (size_t k = i; k < le && blank; k++) {+ blank = pl_blank(s[k]);+ }+ if (!blank && !in) {+ in = true;+ start = i;+ }+ if (blank && in) {+ *pb = start;+ *pe = i;+ *pos = i;+ return true;+ }+ i = le < end ? le + SKIP_ONE : end;+ }+ *pos = end;+ if (in) {+ *pb = start;+ *pe = end;+ }+ return in;+}++/* True when the paragraph s[pb, pe) is a command (`=` and a letter). */+static bool pl_is_command(const char *s, size_t pb, size_t pe) {+ return pb + SKIP_ONE < pe && s[pb] == '=' && isalpha((unsigned char)s[pb + SKIP_ONE]);+}++/* End of the command word that follows the `=` at s[pb]. */+static size_t pl_command_word_end(const char *s, size_t pb, size_t pe) {+ size_t wb = pb + SKIP_ONE;+ while (wb < pe && pl_word(s[wb])) {+ wb++;+ }+ return wb;+}++static bool pl_word_is(const char *w, size_t n, const char *lit) {+ return n == strlen(lit) && memcmp(w, lit, n) == 0;+}++/* `headN`: the level, 0 for another word. */+static int pl_head_level(const char *w, size_t n) {+ static const char head[] = "head";+ size_t hl = sizeof(head) - SKIP_ONE;+ if (n != PL_HEAD_WORD || memcmp(w, head, hl) != 0 || !isdigit((unsigned char)w[hl])) {+ return 0;+ }+ return w[hl] - '0';+}++/* ── Formatting codes ────────────────────────────────────────────── */++typedef struct {+ uint8_t width[PL_CODE_DEPTH]; /* brackets of each open code: 1 simple, more complex */+ int depth;+ bool overflow; /* nested deeper than PL_CODE_DEPTH */+} pl_codes_t;++enum { PL_EV_TEXT = 0, PL_EV_OPEN, PL_EV_CLOSE };++/* A code opens at t[i]: push it and return where its content starts. */+static size_t pl_code_open(pl_codes_t *st, const char *t, size_t i, size_t e, bool *pushed) {+ size_t j = i + SKIP_ONE;+ while (j < e && t[j] == '<') {+ j++;+ }+ size_t brackets = j - i - SKIP_ONE;+ size_t content = i + PAIR_LEN;+ size_t width = SKIP_ONE;+ if (brackets >= PAIR_LEN && j < e && pl_space(t[j])) {+ while (j < e && pl_space(t[j])) {+ j++;+ }+ content = j;+ width = brackets > UINT8_MAX ? UINT8_MAX : brackets;+ }+ *pushed = st->depth < PL_CODE_DEPTH;+ if (*pushed) {+ st->width[st->depth++] = (uint8_t)width;+ } else {+ st->overflow = true;+ }+ return content;+}++/* One lexing step at t[i], i < e (Pod::Simple's treelet tokens).+ * PL_EV_OPEN a code opened at t[i]; its content starts at *next+ * PL_EV_CLOSE the innermost code's content ended at i; *next follows its+ * closing brackets+ * PL_EV_TEXT t[i, *next) is literal */+static int pl_code_step(pl_codes_t *st, const char *t, size_t i, size_t e, size_t *next) {+ char c = t[i];+ if (pl_upper(c) && i + SKIP_ONE < e && t[i + SKIP_ONE] == '<') {+ bool pushed = false;+ *next = pl_code_open(st, t, i, e, &pushed);+ return pushed ? PL_EV_OPEN : PL_EV_TEXT;+ }+ size_t need = st->depth > 0 ? st->width[st->depth - SKIP_ONE] : 0;+ if (need == SKIP_ONE && c == '>') {+ st->depth--;+ *next = i + SKIP_ONE;+ return PL_EV_CLOSE;+ }+ if (need > SKIP_ONE && pl_space(c)) {+ size_t k = i;+ while (k < e && pl_space(t[k])) {+ k++;+ }+ size_t m = k;+ while (m < e && t[m] == '>') {+ m++;+ }+ if (m - k >= need) {+ st->depth--;+ *next = k + need;+ return PL_EV_CLOSE;+ }+ *next = m; /* white space and too few brackets: literal */+ return PL_EV_TEXT;+ }+ *next = i + SKIP_ONE;+ return PL_EV_TEXT;+}++/* ── Bounded text output ─────────────────────────────────────────── */++typedef struct {+ char *buf;+ size_t cap; /* bytes of text that fit (the buffer holds one more) */+ size_t len;+ bool space; /* a white-space run is pending */+ bool cut; /* something did not fit */+} pl_out_t;++/* Bytes of the UTF-8 character that `lead` starts; 1 for anything else. */+static size_t pl_utf8_len(unsigned char lead) {+ if (lead >= PL_UTF8_LEAD4 && lead < PL_UTF8_LEAD_END) {+ return 4;+ }+ if (lead >= PL_UTF8_LEAD3 && lead < PL_UTF8_LEAD4) {+ return 3;+ }+ if (lead >= PL_UTF8_LEAD2 && lead < PL_UTF8_LEAD3) {+ return PAIR_LEN;+ }+ return SKIP_ONE;+}++/* Append t[0, n): white-space runs become one space (none at the start),+ * control bytes are dropped, and a character that does not fit whole ends+ * the output. */+static void pl_out_text(pl_out_t *o, const char *t, size_t n) {+ for (size_t i = 0; i < n && !o->cut; i++) {+ char c = t[i];+ if (pl_space(c)) {+ o->space = o->len > 0;+ continue;+ }+ if (pl_control(c)) {+ continue;+ }+ size_t need = pl_utf8_len((unsigned char)c) + (o->space ? SKIP_ONE : 0);+ if (o->len + need > o->cap) {+ o->cut = true;+ return;+ }+ if (o->space) {+ o->buf[o->len++] = ' ';+ o->space = false;+ }+ o->buf[o->len++] = c;+ }+}++static void pl_out_end(pl_out_t *o) {+ o->buf[o->len] = '\0';+}++/* t[b, e) squeezed into out (cap + 1 bytes); *cut when it did not fit. */+static size_t pl_squeeze(const char *t, size_t b, size_t e, char *out, size_t cap, bool *cut) {+ pl_out_t o = {.buf = out, .cap = cap};+ pl_out_text(&o, t + b, e - b);+ pl_out_end(&o);+ *cut = o.cut;+ return o.len;+}++/* ── Plain text ──────────────────────────────────────────────────── */++/* Append the UTF-8 form of `cp`; false for what is no character. */+static bool pl_out_codepoint(pl_out_t *o, unsigned long cp) {+ enum {+ CP_1 = 0x80,+ CP_2 = 0x800,+ CP_3 = 0x10000,+ CP_MAX = 0x10FFFF,+ CP_SURR_LO = 0xD800,+ CP_SURR_HI = 0xDFFF,+ SHIFT = 6,+ LOW = 0x3F,+ };+ if (cp == 0 || cp > CP_MAX || (cp >= CP_SURR_LO && cp <= CP_SURR_HI)) {+ return false;+ }+ char u[4];+ size_t n = 0;+ if (cp < CP_1) {+ u[n++] = (char)cp;+ } else if (cp < CP_2) {+ u[n++] = (char)(PL_UTF8_LEAD2 | (cp >> SHIFT));+ u[n++] = (char)(PL_UTF8_CONT | (cp & LOW));+ } else if (cp < CP_3) {+ u[n++] = (char)(PL_UTF8_LEAD3 | (cp >> (SHIFT + SHIFT)));+ u[n++] = (char)(PL_UTF8_CONT | ((cp >> SHIFT) & LOW));+ u[n++] = (char)(PL_UTF8_CONT | (cp & LOW));+ } else {+ u[n++] = (char)(PL_UTF8_LEAD4 | (cp >> (SHIFT + SHIFT + SHIFT)));+ u[n++] = (char)(PL_UTF8_CONT | ((cp >> (SHIFT + SHIFT)) & LOW));+ u[n++] = (char)(PL_UTF8_CONT | ((cp >> SHIFT) & LOW));+ u[n++] = (char)(PL_UTF8_CONT | (cp & LOW));+ }+ pl_out_text(o, u, n);+ return true;+}++/* The number an E<> body writes (decimal, 0x hex, 0 octal); false for a name. */+static bool pl_entity_number(const char *e, size_t n, unsigned long *cp) {+ enum { DEC = 10, HEX = 16, OCT = 8 };+ int base = DEC;+ size_t i = 0;+ if (n > PAIR_LEN && e[0] == '0' && (e[1] == 'x' || e[1] == 'X')) {+ base = HEX;+ i = PAIR_LEN;+ } else if (n > SKIP_ONE && e[0] == '0') {+ base = OCT;+ i = SKIP_ONE;+ }+ unsigned long v = 0;+ for (; i < n; i++) {+ int d = isdigit((unsigned char)e[i]) ? e[i] - '0'+ : isxdigit((unsigned char)e[i]) ? tolower((unsigned char)e[i]) - 'a' + DEC+ : base;+ if (d >= base) {+ return false;+ }+ v = (v * (unsigned long)base) + (unsigned long)d;+ }+ *cp = v;+ return n > 0;+}++/* Append what E<body> renders; an unknown body stays as written. */+static void pl_out_entity(pl_out_t *o, const char *body, size_t n, bool closed) {+ static const struct {+ const char *name;+ char ch;+ } ents[] = {{"lt", '<'}, {"gt", '>'}, {"verbar", '|'},+ {"sol", '/'}, {"quot", '"'}, {"amp", '&'}};+ for (size_t i = 0; closed && i < sizeof(ents) / sizeof(ents[0]); i++) {+ if (pl_word_is(body, n, ents[i].name)) {+ pl_out_text(o, &ents[i].ch, SKIP_ONE);+ return;+ }+ }+ unsigned long cp = 0;+ if (closed && pl_entity_number(body, n, &cp) && pl_out_codepoint(o, cp)) {+ return;+ }+ pl_out_text(o, "E<", PL_MALFORMED);+ pl_out_text(o, body, n);+ if (closed) {+ pl_out_text(o, ">", SKIP_ONE);+ }+}++size_t cbm_doclink_perl_plain_text(const char *in, size_t len, char *out, size_t cap) {+ if (!out || cap == 0) {+ return 0;+ }+ pl_out_t o = {.buf = out, .cap = cap - SKIP_ONE};+ pl_codes_t st = {.depth = 0};+ int drop_depth = 0; /* an X<> or Z<> is open at this depth: no text */+ int ent_depth = 0; /* an E<> is open at this depth */+ char ent[PL_ENT_MAX];+ size_t ent_len = 0;+ size_t i = 0;+ while (in && i < len && !st.overflow) {+ size_t next = i;+ int ev = pl_code_step(&st, in, i, len, &next);+ if (ev == PL_EV_OPEN && drop_depth == 0 && ent_depth == 0) {+ if (in[i] == 'X' || in[i] == 'Z') {+ drop_depth = st.depth;+ } else if (in[i] == 'E') {+ ent_depth = st.depth;+ ent_len = 0;+ }+ } else if (ev == PL_EV_CLOSE && drop_depth != 0) {+ drop_depth = st.depth < drop_depth ? 0 : drop_depth;+ } else if (ev == PL_EV_CLOSE && ent_depth != 0 && st.depth < ent_depth) {+ pl_out_entity(&o, ent, ent_len, true);+ ent_depth = 0;+ } else if (ev == PL_EV_TEXT && drop_depth == 0 && ent_depth == 0) {+ pl_out_text(&o, in + i, next - i);+ } else if (ev == PL_EV_TEXT && drop_depth == 0) {+ for (size_t k = i; k < next && ent_len < sizeof(ent); k++) {+ ent[ent_len++] = in[k];+ }+ }+ i = next;+ }+ if (ent_depth != 0) {+ pl_out_entity(&o, ent, ent_len, false);+ }+ if (in && i < len) {+ pl_out_text(&o, in + i, len - i); /* nested too deep: the rest as written */+ }+ pl_out_end(&o);+ return o.len;+}++/* ── Link grammar (perlpodspec; Pod::Simple's _treat_Ls) ─────────── */++typedef struct {+ size_t bar; /* first top-level `|`; SIZE_MAX: none */+ size_t slash; /* first top-level `/` after it; SIZE_MAX: none */+ bool space; /* a top-level space in a link that has no `|` */+ bool well_formed; /* every code closes, none nests too deep, no L inside */+} pl_shape_t;++/* Where the top-level `|` and `/` of a link's content are. */+static pl_shape_t pl_link_shape(const char *t, size_t n) {+ pl_shape_t sh = {.bar = SIZE_MAX, .slash = SIZE_MAX, .well_formed = true};+ pl_codes_t st = {.depth = 0};+ size_t i = 0;+ while (i < n && sh.well_formed) {+ size_t next = i;+ int ev = pl_code_step(&st, t, i, n, &next);+ sh.well_formed = !st.overflow && !(ev == PL_EV_OPEN && t[i] == 'L');+ for (size_t k = i; ev == PL_EV_TEXT && st.depth == 0 && k < next; k++) {+ if (t[k] == '|' && sh.bar == SIZE_MAX) {+ sh.bar = k;+ sh.slash = SIZE_MAX; /* the name and section follow the text */+ } else if (t[k] == '/' && sh.slash == SIZE_MAX) {+ sh.slash = k;+ } else if (t[k] == ' ' && sh.bar == SIZE_MAX) {+ sh.space = true;+ }+ }+ i = next;+ }+ sh.well_formed = sh.well_formed && st.depth == 0;+ return sh;+}++/* perlpodspec: a link whose target matches \A\w+:[^:\s]\S*\z is a URL. */+static bool pl_is_url(const char *t, size_t n) {+ size_t i = 0;+ while (i < n && pl_word(t[i])) {+ i++;+ }+ if (i == 0 || i + SKIP_ONE >= n || t[i] != ':' || t[i + SKIP_ONE] == ':') {+ return false;+ }+ for (size_t k = i + SKIP_ONE; k < n; k++) {+ if (pl_space(t[k])) {+ return false;+ }+ }+ return true;+}++/* The start of t[b, e) after its leading spaces. */+static size_t pl_lead_spaces_end(const char *t, size_t b, size_t e) {+ while (b < e && t[b] == ' ') {+ b++;+ }+ return b;+}++/* The end of t[b, e) before its trailing spaces. */+static size_t pl_trail_spaces_start(const char *t, size_t b, size_t e) {+ while (e > b && t[e - SKIP_ONE] == ' ') {+ e--;+ }+ return e;+}++/* Trim t[*b, *e) and drop one pair of surrounding double quotes. */+static void pl_trim(const char *t, size_t *b, size_t *e, bool *quoted) {+ size_t lo = pl_lead_spaces_end(t, *b, *e);+ size_t hi = pl_trail_spaces_start(t, lo, *e);+ *quoted = hi - lo >= PAIR_LEN && t[lo] == '"' && t[hi - SKIP_ONE] == '"';+ *b = *quoted ? lo + SKIP_ONE : lo;+ *e = *quoted ? hi - SKIP_ONE : hi;+}++/* `name(3)`: a man page. */+static bool pl_is_man_page(const char *p) {+ size_t n = strlen(p);+ if (n < 4 || p[n - SKIP_ONE] != ')') {+ return false;+ }+ size_t open = n - SKIP_ONE;+ while (open > 0 && p[open] != '(') {+ open--;+ }+ if (open == 0 || open + SKIP_ONE == n - SKIP_ONE) {+ return false;+ }+ for (size_t k = open + SKIP_ONE; k < n - SKIP_ONE; k++) {+ if (!isalnum((unsigned char)p[k]) && p[k] != '-') {+ return false;+ }+ }+ return memchr(p, '/', open) == NULL;+}++/* `Ident(::Ident)*`: a module name. */+static bool pl_is_module_name(const char *p) {+ if (!(isalpha((unsigned char)p[0]) || p[0] == '_')) {+ return false;+ }+ for (size_t i = 0; p[i]; i++) {+ if (pl_word(p[i])) {+ continue;+ }+ if (p[i] != ':' || p[i + SKIP_ONE] != ':' || !pl_word(p[i + PAIR_LEN])) {+ return false;+ }+ i++;+ }+ return true;+}++bool cbm_doclink_perl_parse_link(const char *raw, CBMPerlLink *out) {+ if (!out) {+ return false;+ }+ memset(out, 0, sizeof(*out));+ out->kind = CBM_PERL_LINK_UNPARSEABLE;+ size_t n = raw ? strlen(raw) : 0;+ if (n == 0 || n > CBM_DOCLINK_PERL_RAW_MAX || (raw[0] == 'L' && raw[1] == '<')) {+ return false; /* empty, or kept as written because it is malformed */+ }+ pl_shape_t sh = pl_link_shape(raw, n);+ if (!sh.well_formed) {+ return false;+ }+ size_t nb = sh.bar == SIZE_MAX ? 0 : sh.bar + SKIP_ONE;+ size_t ne = sh.slash == SIZE_MAX ? n : sh.slash;+ size_t sb = sh.slash == SIZE_MAX ? n : sh.slash + SKIP_ONE;+ size_t se = n;+ bool name_quoted = false;+ bool sec_quoted = false;+ pl_trim(raw, &nb, &ne, &name_quoted);+ pl_trim(raw, &sb, &se, &sec_quoted);+ bool section_only = sh.slash == SIZE_MAX && (name_quoted || sh.space);+ if (section_only) { /* L<"sec"> and the old L<two words> name a section */+ sb = nb;+ se = ne;+ ne = nb;+ } else if (name_quoted) {+ nb--; /* the quotes of a page name are part of it */+ ne++;+ }+ cbm_doclink_perl_plain_text(raw + nb, ne - nb, out->page, sizeof(out->page));+ cbm_doclink_perl_plain_text(raw + sb, se - sb, out->section, sizeof(out->section));+ if (!out->page[0]) {+ out->kind = out->section[0] ? CBM_PERL_LINK_SECTION : CBM_PERL_LINK_UNPARSEABLE;+ } else if (pl_is_man_page(out->page)) {+ out->kind = CBM_PERL_LINK_MAN;+ } else if (pl_is_module_name(out->page)) {+ out->kind = CBM_PERL_LINK_PAGE;+ }+ return out->kind != CBM_PERL_LINK_UNPARSEABLE;+}++/* ── Tokens ──────────────────────────────────────────────────────── */++typedef struct {+ CBMExtractCtx *ctx;+ const CBMDefinition *def;+ const char *text; /* what is being read: the file, or a doc of unknown position */+ size_t line_pos; /* lines are counted from here ... */+ uint32_t line; /* ... which is on this line */+ bool fixed_line; /* every token gets `line` */+} pl_emit_t;++typedef struct {+ size_t at; /* the code's letter */+ size_t cb; /* its content */+ size_t ce;+ bool closed; /* false: the paragraph ended first */+} pl_code_t;++static uint32_t pl_line_at(pl_emit_t *em, size_t at) {+ if (em->fixed_line) {+ return em->line;+ }+ for (size_t k = em->line_pos; k < at; k++) {+ em->line += em->text[k] == '\n';+ }+ em->line_pos = at > em->line_pos ? at : em->line_pos;+ return em->line;+}++static void pl_push(pl_emit_t *em, const char *raw, size_t n, int syntax, uint32_t line) {+ char *copy = cbm_arena_strndup(em->ctx->arena, raw, n);+ if (!copy) {+ return;+ }+ CBMDocLink link = {+ .source_qn = em->def->qualified_name,+ .raw = copy,+ .line = line,+ .def_line = em->def->start_line,+ .syntax = (uint16_t)syntax,+ };+ cbm_doclinks_push(&em->ctx->result->doc_links, em->ctx->arena, link);+}++/* One L<> code of em->text -> one token (none for an empty code). */+static void pl_emit_link(pl_emit_t *em, const pl_code_t *code) {+ uint32_t line = pl_line_at(em, code->at);+ char buf[PL_MALFORMED + CBM_DOCLINK_PERL_RAW_MAX + SKIP_ONE] = "L<";+ char *content = buf + PL_MALFORMED;+ bool cut = false;+ size_t n = pl_squeeze(em->text, code->cb, code->ce, content, CBM_DOCLINK_PERL_RAW_MAX, &cut);+ if (!code->closed || cut) {+ size_t keep = n > CBM_DOCLINK_PERL_RAW_MAX - PL_MALFORMED+ ? CBM_DOCLINK_PERL_RAW_MAX - PL_MALFORMED+ : n;+ while (keep > 0 && ((unsigned char)content[keep] & PL_UTF8_CONT_MASK) == PL_UTF8_CONT) {+ keep--; /* not in the middle of a character */+ }+ pl_push(em, buf, PL_MALFORMED + keep, CBM_DOCLINK_PERL_POD_L, line);+ return;+ }+ if (n == 0) {+ return; /* Pod::Simple: "An empty L<>" is text */+ }+ pl_shape_t sh = pl_link_shape(content, n);+ size_t tb = sh.bar == SIZE_MAX ? 0 : sh.bar + SKIP_ONE;+ while (tb < n && content[tb] == ' ') {+ tb++;+ }+ if (sh.well_formed && pl_is_url(content + tb, n - tb)) {+ pl_push(em, content + tb, n - tb, CBM_DOCLINK_HREF, line);+ return;+ }+ pl_push(em, content, n, CBM_DOCLINK_PERL_POD_L, line);+}++/* The L<> codes of one paragraph's text em->text[b, e). */+static void pl_para_links(pl_emit_t *em, size_t b, size_t e) {+ const char *t = em->text;+ pl_codes_t st = {.depth = 0};+ pl_code_t link = {0};+ int link_depth = 0; /* stack depth of the open L; 0: none */+ bool harvest = false; /* the open L is a reference */+ size_t i = b;+ while (i < e && !st.overflow) {+ size_t next = i;+ int ev = pl_code_step(&st, t, i, e, &next);+ if (ev == PL_EV_OPEN && link_depth == 0 && t[i] == 'L') {+ link_depth = st.depth;+ harvest = !(i > b && pl_word(t[i - SKIP_ONE]));+ link = (pl_code_t){.at = i, .cb = next, .ce = next, .closed = false};+ } else if (ev == PL_EV_CLOSE && link_depth != 0 && st.depth < link_depth) {+ link.ce = i;+ link.closed = true;+ if (harvest) {+ pl_emit_link(em, &link);+ }+ link_depth = 0;+ }+ i = next;+ }+ if (link_depth != 0 && harvest) {+ link.ce = e; /* never closed, or nested too deep */+ pl_emit_link(em, &link);+ }+}++/* First byte after the white space that follows s[i]. */+static size_t pl_skip_blank(const char *s, size_t i, size_t e) {+ while (i < e && pl_space(s[i])) {+ i++;+ }+ return i;+}++/* The L<> codes of the POD text em->text[b, e): from its first command on, or+ * from its start when `in_pod` (a run of the module doc, which is POD only). */+static void pl_harvest_pod(pl_emit_t *em, size_t b, size_t e, bool in_pod) {+ const char *t = em->text;+ size_t pos = b;+ size_t pb = 0;+ size_t pe = 0;+ int begin_depth = 0; /* open =begin regions */+ int data_from = 0; /* depth of the outermost data region; 0: none */+ while (pl_next_para(t, &pos, e, &pb, &pe)) {+ bool cmd = pl_is_command(t, pb, pe);+ if (!cmd) {+ if (in_pod && data_from == 0 && t[pb] != ' ' && t[pb] != '\t') {+ pl_para_links(em, pb, pe);+ }+ continue;+ }+ size_t wb = pl_command_word_end(t, pb, pe);+ const char *w = t + pb + SKIP_ONE;+ size_t wl = wb - pb - SKIP_ONE;+ in_pod = !pl_word_is(w, wl, "cut");+ if (pl_word_is(w, wl, "begin")) {+ size_t f = pl_skip_blank(t, wb, pe);+ begin_depth++;+ if (data_from == 0 && !(f < pe && t[f] == ':')) {+ data_from = begin_depth;+ }+ } else if (pl_word_is(w, wl, "end") && begin_depth > 0) {+ data_from = begin_depth == data_from ? 0 : data_from;+ begin_depth--;+ } else if (data_from == 0 && (pl_head_level(w, wl) > 0 || pl_word_is(w, wl, "item"))) {+ pl_para_links(em, wb, pe);+ }+ }+}++/* ── The file's POD sections ─────────────────────────────────────── */++enum { PL_HEAD = 1, PL_ITEM, PL_OVER, PL_BACK, PL_CUT, PL_OTHER };++typedef struct {+ uint32_t sb; /* command paragraph */+ uint32_t eb;+ uint32_t wb; /* end of the command word */+ uint8_t type;+ uint8_t level; /* =headN: N; =item and =back: list depth */+} pl_cmd_t;++typedef struct {+ uint32_t sb; /* the heading's command paragraph */+ uint32_t eb; /* section end, trailing white space trimmed */+ uint32_t hb; /* heading text */+ uint32_t he;+ uint32_t line; /* 1-based line of sb */+ const char *name; /* the identifier the heading names; NULL: none */+ uint32_t name_len;+ bool item;+} pl_sec_t;++typedef struct {+ CBMArena *a;+ const char *src;+ uint32_t len;+ pl_sec_t *secs;+ int nsecs;+ int cap_secs;+ pl_cmd_t *cmds; /* of the block being read */+ int ncmds;+ int cap_cmds;+ uint32_t line_pos; /* lines are counted from here ... */+ uint32_t line; /* ... which is on this line */+ bool failed;+} pl_scan_t;++/* Room for one more element of `size` bytes in an arena array. */+static void *pl_grow(pl_scan_t *s, void *items, int count, int *cap, size_t size) {+ if (count < *cap) {+ return items;+ }+ int ncap = *cap ? *cap * PAIR_LEN : PL_INIT_CAP;+ void *grown = cbm_arena_alloc(s->a, (size_t)ncap * size);+ if (!grown) {+ s->failed = true;+ return NULL;+ }+ if (count > 0) {+ memcpy(grown, items, (size_t)count * size);+ }+ *cap = ncap;+ return grown;+}++/* Classify one command paragraph; `depth` is the =over nesting+ * (extract_defs.c's pod_classify). */+static pl_cmd_t pl_classify(const char *src, uint32_t sb, uint32_t eb, int *depth) {+ uint32_t wb = (uint32_t)pl_command_word_end(src, sb, eb);+ const char *w = src + sb + SKIP_ONE;+ size_t wl = wb - sb - SKIP_ONE;+ pl_cmd_t c = {sb, eb, wb, PL_OTHER, 0};+ if (pl_head_level(w, wl) > 0) {+ c.type = PL_HEAD;+ c.level = (uint8_t)pl_head_level(w, wl);+ } else if (pl_word_is(w, wl, "item")) {+ c.type = PL_ITEM;+ c.level = (uint8_t)*depth;+ } else if (pl_word_is(w, wl, "over")) {+ c.type = PL_OVER;+ (*depth)++;+ } else if (pl_word_is(w, wl, "back")) {+ c.type = PL_BACK;+ c.level = (uint8_t)*depth;+ if (*depth > 0) {+ (*depth)--;+ }+ } else if (pl_word_is(w, wl, "cut")) {+ c.type = PL_CUT;+ }+ return c;+}++/* The command paragraphs of the POD block src[pb, pe) into s->cmds. */+static void pl_block_commands(pl_scan_t *s, uint32_t pb, uint32_t pe) {+ s->ncmds = 0;+ int depth = 0;+ size_t pos = pb;+ size_t sb = 0;+ size_t eb = 0;+ while (!s->failed && pl_next_para(s->src, &pos, pe, &sb, &eb)) {+ if (!pl_is_command(s->src, sb, eb)) {+ continue;+ }+ pl_cmd_t *cmds = (pl_cmd_t *)pl_grow(s, s->cmds, s->ncmds, &s->cap_cmds, sizeof(pl_cmd_t));+ if (!cmds) {+ return;+ }+ s->cmds = cmds;+ s->cmds[s->ncmds++] = pl_classify(s->src, (uint32_t)sb, (uint32_t)eb, &depth);+ }+}++/* End byte of the section that cmds[ci] (a =head or =item) opens+ * (extract_defs.c's pod_section_end). */+static uint32_t pl_section_end(const pl_cmd_t *cmds, int n, int ci, uint32_t pe) {+ const pl_cmd_t *c = &cmds[ci];+ for (int j = ci + SKIP_ONE; j < n; j++) {+ const pl_cmd_t *d = &cmds[j];+ if (d->type == PL_CUT) {+ return d->sb;+ }+ if (d->type == PL_HEAD && (c->type == PL_ITEM || d->level <= c->level)) {+ return d->sb;+ }+ if (c->type == PL_ITEM && (d->type == PL_ITEM || d->type == PL_BACK) &&+ d->level == c->level) {+ return d->sb;+ }+ }+ return pe;+}++/* A heading's text with formatting codes removed and newlines and tabs as+ * spaces (extract_defs.c's pod_plain_heading, byte for byte: the name it+ * yields decides which sub a section is stored on). */+static char *pl_plain_heading(CBMArena *a, const char *src, uint32_t b, uint32_t e) {+ char *buf = (char *)cbm_arena_alloc(a, (size_t)(e - b) + SKIP_ONE);+ if (!buf) {+ return NULL;+ }+ size_t w = 0;+ for (uint32_t i = b; i < e; i++) {+ char c = src[i];+ if (pl_upper(c) && i + SKIP_ONE < e && src[i + SKIP_ONE] == '<') {+ uint32_t j = i + SKIP_ONE;+ while (j < e && src[j] == '<') {+ j++;+ }+ if (j - i > PAIR_LEN && j < e && (src[j] == ' ' || src[j] == '\t')) {+ j++; /* X<< text >> */+ }+ i = j - SKIP_ONE;+ continue;+ }+ if (c == '>' && !(w > 0 && buf[w - SKIP_ONE] == '-')) {+ continue;+ }+ buf[w++] = (c == '\n' || c == '\r' || c == '\t') ? ' ' : c;+ }+ buf[w] = '\0';+ return buf;+}++static const char *pl_skip_spaces(const char *p) {+ while (*p == ' ') {+ p++;+ }+ return p;+}++/* The sub a heading names: after a list bullet ("*", "1."), a `$obj->`+ * receiver and a sigil, the identifier that follows; its length, 0 for none+ * (extract_defs.c's pod_heading_name). */+static size_t pl_heading_name(CBMArena *a, const char *src, uint32_t b, uint32_t e,+ const char **name) {+ const char *buf = pl_plain_heading(a, src, b, e);+ if (!buf) {+ return 0;+ }+ const char *p = pl_skip_spaces(buf);+ if (*p == '*') {+ p++;+ } else if (isdigit((unsigned char)*p)) {+ while (isdigit((unsigned char)*p)) {+ p++;+ }+ if (*p == '.') {+ p++;+ }+ }+ p = pl_skip_spaces(p);+ if (*p == '$') {+ const char *q = p + SKIP_ONE;+ while (pl_word(*q)) {+ q++;+ }+ q = pl_skip_spaces(q);+ if (q > p + SKIP_ONE && q[0] == '-' && q[SKIP_ONE] == '>') {+ p = pl_skip_spaces(q + PAIR_LEN);+ }+ }+ if (*p == '$' || *p == '@' || *p == '%' || *p == '&') {+ p++;+ }+ if (!(isalpha((unsigned char)*p) || *p == '_')) {+ return 0;+ }+ const char *s = p;+ while (pl_word(*p)) {+ p++;+ }+ *name = s;+ return (size_t)(p - s);+}++static uint32_t pl_trim_end(const char *src, uint32_t sb, uint32_t eb) {+ while (eb > sb && pl_space(src[eb - SKIP_ONE])) {+ eb--;+ }+ return eb;+}++/* The 1-based line of src[at]; `at` never decreases between calls. */+static uint32_t pl_scan_line(pl_scan_t *s, uint32_t at) {+ for (uint32_t k = s->line_pos; k < at; k++) {+ s->line += s->src[k] == '\n';+ }+ s->line_pos = at > s->line_pos ? at : s->line_pos;+ return s->line;+}++/* The =head / =item sections of the POD block src[pb, pe). */+static void pl_block_sections(pl_scan_t *s, uint32_t pb, uint32_t pe) {+ pl_block_commands(s, pb, pe);+ for (int ci = 0; ci < s->ncmds && !s->failed; ci++) {+ const pl_cmd_t *c = &s->cmds[ci];+ if (c->type != PL_HEAD && c->type != PL_ITEM) {+ continue;+ }+ pl_sec_t *secs = (pl_sec_t *)pl_grow(s, s->secs, s->nsecs, &s->cap_secs, sizeof(pl_sec_t));+ if (!secs) {+ return;+ }+ s->secs = secs;+ pl_sec_t sec = {.sb = c->sb, .hb = c->wb, .he = c->eb, .item = c->type == PL_ITEM};+ sec.eb = pl_trim_end(s->src, c->sb, pl_section_end(s->cmds, s->ncmds, ci, pe));+ sec.line = pl_scan_line(s, c->sb);+ sec.name_len = (uint32_t)pl_heading_name(s->a, s->src, c->wb, c->eb, &sec.name);+ s->secs[s->nsecs++] = sec;+ }+}++/* True when the line src[i, le) is the `=cut` that ends a POD block. */+static bool pl_is_cut_line(const char *src, uint32_t i, uint32_t le) {+ static const char cut[] = "=cut";+ uint32_t n = (uint32_t)(sizeof(cut) - SKIP_ONE);+ return le - i >= n && memcmp(src + i, cut, n) == 0 && (le - i == n || !pl_word(src[i + n]));+}++/* Every POD section of the file. A block runs from a line that starts with+ * `=` and a letter through the next line that starts with `=cut`, or to the+ * end of the file: what perl skips and perldoc reads. */+static void pl_scan_file(pl_scan_t *s) {+ bool in_pod = false;+ uint32_t pb = 0;+ uint32_t i = 0;+ while (i < s->len && !s->failed) {+ const char *nl = (const char *)memchr(s->src + i, '\n', s->len - i);+ uint32_t le = nl ? (uint32_t)(nl - s->src) : s->len;+ if (!in_pod && pl_is_command(s->src, i, le)) {+ in_pod = true;+ pb = i;+ }+ if (in_pod && pl_is_cut_line(s->src, i, le)) {+ pl_block_sections(s, pb, le);+ in_pod = false;+ }+ i = le < s->len ? le + SKIP_ONE : s->len;+ }+ if (in_pod && !s->failed) {+ pl_block_sections(s, pb, s->len);+ }+}++static void pl_scan_init(pl_scan_t *s, CBMExtractCtx *ctx) {+ memset(s, 0, sizeof(*s));+ s->a = pl_scratch(ctx);+ s->src = ctx->source;+ s->len = (ctx->source && ctx->source_len > 0) ? (uint32_t)ctx->source_len : 0;+ s->line = SKIP_ONE;+}++/* ── Docs -> tokens ──────────────────────────────────────────────── */++typedef struct {+ const char *name;+ uint32_t len;+ int sec;+} pl_named_t;++static int pl_name_cmp(const char *a, size_t al, const char *b, size_t bl) {+ int c = memcmp(a, b, al < bl ? al : bl);+ if (c != 0) {+ return c;+ }+ return (al > bl) - (al < bl);+}++static int pl_named_cmp(const void *a, const void *b) {+ const pl_named_t *x = (const pl_named_t *)a;+ const pl_named_t *y = (const pl_named_t *)b;+ int c = pl_name_cmp(x->name, x->len, y->name, y->len);+ return c != 0 ? c : (x->sec > y->sec) - (x->sec < y->sec);+}++/* The sections that name something, sorted by name and then by position. */+static pl_named_t *pl_named_sections(const pl_scan_t *s, int *count) {+ *count = 0;+ pl_named_t *named =+ (pl_named_t *)cbm_arena_alloc(s->a, (size_t)(s->nsecs + SKIP_ONE) * sizeof(*named));+ if (!named) {+ return NULL;+ }+ int n = 0;+ for (int i = 0; i < s->nsecs; i++) {+ if (s->secs[i].name_len > 0) {+ named[n++] = (pl_named_t){s->secs[i].name, s->secs[i].name_len, i};+ }+ }+ qsort(named, (size_t)n, sizeof(*named), pl_named_cmp);+ *count = n;+ return named;+}++/* Index of the first section named `name`, or `count`. */+static int pl_named_first(const pl_named_t *named, int count, const char *name) {+ size_t nl = strlen(name);+ int lo = 0;+ int hi = count;+ while (lo < hi) {+ int mid = lo + ((hi - lo) / PAIR_LEN);+ if (pl_name_cmp(named[mid].name, named[mid].len, name, nl) < 0) {+ lo = mid + SKIP_ONE;+ } else {+ hi = mid;+ }+ }+ return lo;+}++/* True when doc[o, dl) starts with the section `sec`, alone or followed by the+ * blank line that joins it to the next one. */+static bool pl_piece_is(const pl_scan_t *s, const pl_sec_t *sec, const char *doc, size_t o,+ size_t dl) {+ size_t n = sec->eb - sec->sb;+ if (n == 0 || n > dl - o || memcmp(doc + o, s->src + sec->sb, n) != 0) {+ return false;+ }+ return o + n == dl ||+ (dl - o - n >= PAIR_LEN && doc[o + n] == '\n' && doc[o + n + SKIP_ONE] == '\n');+}++/* One definition's doc -> tokens: every piece of it that is a section of the+ * file is read where it stands, so its references carry their own lines. */+static void pl_harvest_def(CBMExtractCtx *ctx, const pl_scan_t *s, const pl_named_t *named,+ int count, const CBMDefinition *def, uint32_t fallback_line) {+ const char *doc = def->docstring;+ size_t dl = strlen(doc);+ if (!pl_is_command(doc, 0, dl)) {+ return; /* a `#` comment: no formatting codes */+ }+ size_t nl = strlen(def->name);+ size_t o = 0;+ int cand = named ? pl_named_first(named, count, def->name) : count;+ for (; o < dl && cand < count &&+ pl_name_cmp(named[cand].name, named[cand].len, def->name, nl) == 0;+ cand++) {+ const pl_sec_t *sec = &s->secs[named[cand].sec];+ if (!pl_piece_is(s, sec, doc, o, dl)) {+ continue; /* a section the doc does not hold */+ }+ pl_emit_t em = {+ .ctx = ctx, .def = def, .text = s->src, .line_pos = sec->sb, .line = sec->line};+ pl_harvest_pod(&em, sec->sb, sec->eb, false);+ o += sec->eb - sec->sb;+ o += o < dl ? PAIR_LEN : 0;+ }+ if (o < dl) { /* text whose place in the file is not known */+ pl_emit_t em = {+ .ctx = ctx, .def = def, .text = doc, .line = fallback_line, .fixed_line = true};+ pl_harvest_pod(&em, o, dl, false);+ }+}++/* The core's filter: a definition whose doc is harvested. */+static bool pl_documented(const CBMDefinition *d) {+ return d->docstring && d->docstring[0] && d->qualified_name && d->name;+}++typedef struct {+ const char *qn;+ int idx;+} pl_docdef_t;++static int pl_docdef_cmp(const void *a, const void *b) {+ const pl_docdef_t *x = (const pl_docdef_t *)a;+ const pl_docdef_t *y = (const pl_docdef_t *)b;+ int c = strcmp(x->qn, y->qn);+ return c != 0 ? c : (x->idx > y->idx) - (x->idx < y->idx);+}++/* twin[i]: definition i repeats the qualified name AND the doc of an earlier+ * one (the same sub name in two packages of a file is one node with one doc):+ * its references are the earlier one's. NULL when there is nothing to mark. */+static bool *pl_twins(CBMExtractCtx *ctx) {+ const CBMDefArray *defs = &ctx->result->defs;+ CBMArena *a = pl_scratch(ctx);+ pl_docdef_t *docs = (pl_docdef_t *)cbm_arena_alloc(a, (size_t)defs->count * sizeof(*docs));+ bool *twin = (bool *)cbm_arena_calloc(a, (size_t)defs->count * sizeof(bool));+ if (!docs || !twin) {+ return NULL;+ }+ int n = 0;+ for (int i = 0; i < defs->count; i++) {+ if (pl_documented(&defs->items[i])) {+ docs[n++] = (pl_docdef_t){defs->items[i].qualified_name, i};+ }+ }+ qsort(docs, (size_t)n, sizeof(*docs), pl_docdef_cmp);+ int first = 0;+ for (int i = SKIP_ONE; i < n; i++) {+ if (strcmp(docs[i].qn, docs[first].qn) != 0) {+ first = i;+ } else {+ twin[docs[i].idx] = strcmp(defs->items[docs[i].idx].docstring,+ defs->items[docs[first].idx].docstring) == 0;+ }+ }+ return twin;+}++/* Every documented definition of the file -> tokens, in definition order. */+static void pl_harvest_file(CBMExtractCtx *ctx) {+ pl_scan_t s;+ pl_scan_init(&s, ctx);+ pl_scan_file(&s);+ int count = 0;+ pl_named_t *named = s.failed ? NULL : pl_named_sections(&s, &count);+ const bool *twin = pl_twins(ctx);+ const CBMDefArray *defs = &ctx->result->defs;+ for (int i = 0; i < defs->count; i++) {+ const CBMDefinition *d = &defs->items[i];+ if (pl_documented(d) && !(twin && twin[i])) {+ pl_harvest_def(ctx, &s, named, named ? count : 0, d, d->start_line);+ }+ }+}++/* First position >= from of `needle` (n bytes) in src[0, len); SIZE_MAX: none. */+static size_t pl_find(const char *src, size_t from, size_t len, const char *needle, size_t n) {+ if (n == 0 || n > len) {+ return SIZE_MAX;+ }+ for (size_t i = from; i + n <= len; i++) {+ const char *hit = (const char *)memchr(src + i, needle[0], len - n + SKIP_ONE - i);+ if (!hit) {+ return SIZE_MAX;+ }+ i = (size_t)(hit - src);+ if (memcmp(src + i, needle, n) == 0) {+ return i;+ }+ }+ return SIZE_MAX;+}++/* The module doc (the core's File stand-in): runs of the file's POD joined by+ * a blank line (extract_defs.c, doc_perl_module), each found again in the+ * source after the one before, so that a reference gets the line it is written+ * on. Text that is not found keeps the doc's first line. */+static void pl_harvest_module(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,+ uint32_t doc_line) {+ const char *src = ctx->source;+ size_t sl = ctx->source_len > 0 ? (size_t)ctx->source_len : 0;+ size_t dl = strlen(doc);+ size_t o = 0;+ size_t at = 0;+ size_t line_pos = 0;+ uint32_t line = SKIP_ONE;+ while (src && o < dl) {+ size_t le = o;+ while (le < dl && doc[le] != '\n') {+ le++;+ }+ size_t p = pl_find(src, at, sl, doc + o, le - o);+ if (p == SIZE_MAX) {+ break;+ }+ size_t k = 0;+ while (o + k < dl && p + k < sl && doc[o + k] == src[p + k]) {+ k++;+ }+ for (; line_pos < p; line_pos++) {+ line += src[line_pos] == '\n' ? SKIP_ONE : 0;+ }+ pl_emit_t em = {.ctx = ctx, .def = def, .text = src, .line_pos = p, .line = line};+ pl_harvest_pod(&em, p, p + k, true);+ o += k;+ at = p + k;+ while (o < dl && doc[o] == '\n') {+ o++; /* the blank line that joins two runs */+ }+ }+ if (o < dl) {+ pl_emit_t em = {.ctx = ctx, .def = def, .text = doc, .line = doc_line, .fixed_line = true};+ pl_harvest_pod(&em, o, dl, true);+ }+}++/* Index of `def` in the file's definitions; -1 when it is not one of them. */+static int pl_def_index(const CBMDefArray *defs, const CBMDefinition *def) {+ uintptr_t base = (uintptr_t)defs->items;+ uintptr_t p = (uintptr_t)def;+ if (!defs->items || defs->count <= 0 || p < base) {+ return CBM_NOT_FOUND;+ }+ uintptr_t off = p - base;+ if (off % sizeof(CBMDefinition) != 0 || off / sizeof(CBMDefinition) >= (uintptr_t)defs->count) {+ return CBM_NOT_FOUND;+ }+ return (int)(off / sizeof(CBMDefinition));+}++void cbm_doclink_perl_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,+ uint32_t doc_line) {+ if (!ctx || !ctx->result || !def || !doc || !def->qualified_name) {+ return;+ }+ if (def->label && strcmp(def->label, "File") == 0) {+ pl_harvest_module(ctx, def, doc, doc_line); /* the file's module doc */+ return;+ }+ const CBMDefArray *defs = &ctx->result->defs;+ int idx = pl_def_index(defs, def);+ if (idx < 0 || doc != def->docstring) {+ /* a doc that is not a listed definition's own: nothing says where in+ * the file it stands, so its references get the line the core passed */+ if (pl_is_command(doc, 0, strlen(doc))) {+ pl_emit_t em = {+ .ctx = ctx, .def = def, .text = doc, .line = doc_line, .fixed_line = true};+ pl_harvest_pod(&em, 0, strlen(doc), false);+ }+ return;+ }+ for (int i = idx - SKIP_ONE; i >= 0; i--) {+ if (pl_documented(&defs->items[i])) {+ return; /* harvested with the file's first documented definition */+ }+ }+ pl_harvest_file(ctx);+}++/* ── Scope blob ──────────────────────────────────────────────────── */++typedef struct {+ CBMArena *a;+ char *buf;+ size_t len;+ size_t cap;+ bool failed;+} pl_sb_t;++static void pl_sb_put(pl_sb_t *sb, const char *s, size_t n) {+ if (sb->failed) {+ return;+ }+ if (sb->len + n + SKIP_ONE > sb->cap) {+ size_t ncap = sb->cap ? sb->cap : PL_SB_INIT;+ while (ncap < sb->len + n + SKIP_ONE) {+ ncap *= PAIR_LEN;+ }+ char *grown = (char *)cbm_arena_alloc(sb->a, ncap);+ if (!grown) {+ sb->failed = true;+ return;+ }+ if (sb->len > 0) {+ memcpy(grown, sb->buf, sb->len);+ }+ sb->buf = grown;+ sb->cap = ncap;+ }+ memcpy(sb->buf + sb->len, s, n);+ sb->len += n;+ sb->buf[sb->len] = '\0';+}++static void pl_sb_puts(pl_sb_t *sb, const char *s) {+ pl_sb_put(sb, s, strlen(s));+}++enum { PL_PKG_MAIN = -1, PL_PKG_UNKNOWN = -2 };++typedef struct {+ const char *name; /* in the source */+ uint32_t len;+ int order; /* declaration order in the file */+ int index; /* of its P record; set by pl_number_packages */+} pl_pkg_t;++typedef struct {+ const char *name; /* in the source */+ uint32_t len;+ uint32_t line;+ int pkg; /* declaration (pl_pkg_t.order) it stands in, or PL_PKG_* */+} pl_subdecl_t;++typedef struct {+ pl_scan_t *s; /* arena and growth */+ pl_pkg_t *pkgs;+ int npkgs;+ int cap_pkgs;+ pl_subdecl_t *subs;+ int nsubs;+ int cap_subs;+ int *saved; /* the package in force outside each open block */+ int nsaved;+ int cap_saved;+ int current; /* declaration in force, or PL_PKG_* */+ int pending_block; /* declaration whose block comes next, or PL_PKG_UNKNOWN */+ bool pending;+} pl_walk_t;++static bool pl_kind(TSNode n, const char *kind) {+ return strcmp(ts_node_type(n), kind) == 0;+}++/* A package or sub name as a blob field: word characters, `:` and `'`. */+static bool pl_name_ok(const char *p, size_t n) {+ if (n == 0 || n > PL_NAME_MAX) {+ return false;+ }+ for (size_t i = 0; i < n; i++) {+ if (!pl_word(p[i]) && p[i] != ':' && p[i] != '\'') {+ return false;+ }+ }+ return true;+}++/* The source text of a declaration's `name` field. */+static bool pl_decl_name(const pl_walk_t *w, TSNode decl, const char **name, uint32_t *len) {+ static const char field[] = "name";+ TSNode n = ts_node_child_by_field_name(decl, field, (uint32_t)(sizeof(field) - SKIP_ONE));+ if (ts_node_is_null(n)) {+ return false;+ }+ uint32_t b = ts_node_start_byte(n);+ uint32_t e = ts_node_end_byte(n);+ if (e <= b || e > w->s->len) {+ return false;+ }+ *name = w->s->src + b;+ *len = e - b;+ return pl_name_ok(*name, *len);+}++static bool pl_has_block(TSNode decl) {+ uint32_t n = ts_node_child_count(decl);+ for (uint32_t i = 0; i < n; i++) {+ if (pl_kind(ts_node_child(decl, i), "block")) {+ return true;+ }+ }+ return false;+}++/* `package NAME;` sets the package to the end of the enclosing block;+ * `package NAME { .. }` sets it inside its own block only. */+static void pl_walk_package(pl_walk_t *w, TSNode decl) {+ const char *name = NULL;+ uint32_t len = 0;+ int id = PL_PKG_UNKNOWN;+ if (pl_decl_name(w, decl, &name, &len)) {+ pl_pkg_t *pkgs =+ (pl_pkg_t *)pl_grow(w->s, w->pkgs, w->npkgs, &w->cap_pkgs, sizeof(pl_pkg_t));+ if (!pkgs) {+ return;+ }+ w->pkgs = pkgs;+ id = w->npkgs;+ w->pkgs[w->npkgs++] = (pl_pkg_t){.name = name, .len = len, .order = id};+ }+ if (pl_has_block(decl)) {+ w->pending = true;+ w->pending_block = id;+ } else {+ w->current = id;+ }+}++static void pl_walk_sub(pl_walk_t *w, TSNode decl) {+ const char *name = NULL;+ uint32_t len = 0;+ if (!pl_decl_name(w, decl, &name, &len)) {+ return;+ }+ pl_subdecl_t *subs =+ (pl_subdecl_t *)pl_grow(w->s, w->subs, w->nsubs, &w->cap_subs, sizeof(pl_subdecl_t));+ if (!subs) {+ return;+ }+ w->subs = subs;+ w->subs[w->nsubs++] = (pl_subdecl_t){.name = name,+ .len = len,+ .line = ts_node_start_point(decl).row + TS_LINE_OFFSET,+ .pkg = w->current};+}++static bool pl_is_scope(TSNode n) {+ return pl_kind(n, "block") || pl_kind(n, "block_statement");+}++/* Enter a node; false when its children are not walked (a sub's body and an+ * expression hold no declaration this blob lists). */+static bool pl_walk_enter(pl_walk_t *w, TSNode n) {+ if (pl_kind(n, "subroutine_declaration_statement")) {+ pl_walk_sub(w, n);+ return false;+ }+ if (pl_kind(n, "expression_statement") || pl_kind(n, "pod") ||+ pl_kind(n, "method_declaration_statement")) {+ return false;+ }+ if (pl_kind(n, "package_statement") || pl_kind(n, "class_statement") ||+ pl_kind(n, "role_statement")) {+ pl_walk_package(w, n);+ return true;+ }+ if (pl_is_scope(n)) {+ int *saved = (int *)pl_grow(w->s, w->saved, w->nsaved, &w->cap_saved, sizeof(int));+ if (!saved) {+ return false;+ }+ w->saved = saved;+ w->saved[w->nsaved++] = w->current;+ if (w->pending) {+ w->current = w->pending_block;+ w->pending = false;+ }+ }+ return true;+}++static void pl_walk_leave(pl_walk_t *w, TSNode n) {+ if (pl_is_scope(n) && w->nsaved > 0) {+ w->current = w->saved[--w->nsaved];+ }+}++/* Packages and subs of the tree, with the package each sub stands in. An+ * iterative walk: the nesting depth is the input's. */+static void pl_walk_tree(pl_walk_t *w, TSNode root) {+ TSTreeCursor cur = ts_tree_cursor_new(root);+ bool more = true;+ while (more && !w->s->failed) {+ TSNode n = ts_tree_cursor_current_node(&cur);+ bool entered = pl_walk_enter(w, n);+ if (entered && ts_tree_cursor_goto_first_child(&cur)) {+ continue;+ }+ if (entered) {+ pl_walk_leave(w, n);+ }+ while (more && !ts_tree_cursor_goto_next_sibling(&cur)) {+ more = ts_tree_cursor_goto_parent(&cur);+ if (more) {+ pl_walk_leave(w, ts_tree_cursor_current_node(&cur));+ }+ }+ }+ ts_tree_cursor_delete(&cur);+}++static int pl_pkg_name_cmp(const void *a, const void *b) {+ const pl_pkg_t *x = (const pl_pkg_t *)a;+ const pl_pkg_t *y = (const pl_pkg_t *)b;+ int c = pl_name_cmp(x->name, x->len, y->name, y->len);+ return c != 0 ? c : (x->order > y->order) - (x->order < y->order);+}++static int pl_pkg_order_cmp(const void *a, const void *b) {+ const pl_pkg_t *x = (const pl_pkg_t *)a;+ const pl_pkg_t *y = (const pl_pkg_t *)b;+ return (x->order > y->order) - (x->order < y->order);+}++/* Give every declaration the index of its name's P record (names in order of+ * their first declaration) and write the P records. */+static void pl_number_packages(pl_walk_t *w, pl_sb_t *sb) {+ qsort(w->pkgs, (size_t)w->npkgs, sizeof(pl_pkg_t), pl_pkg_name_cmp);+ for (int i = 0; i < w->npkgs; i++) { /* index = order of the name's first declaration */+ bool repeat =+ i > 0 && pl_name_cmp(w->pkgs[i].name, w->pkgs[i].len, w->pkgs[i - SKIP_ONE].name,+ w->pkgs[i - SKIP_ONE].len) == 0;+ w->pkgs[i].index = repeat ? w->pkgs[i - SKIP_ONE].index : w->pkgs[i].order;+ }+ qsort(w->pkgs, (size_t)w->npkgs, sizeof(pl_pkg_t), pl_pkg_order_cmp);+ int records = 0;+ for (int i = 0; i < w->npkgs; i++) {+ pl_pkg_t *p = &w->pkgs[i];+ if (p->index != p->order) {+ p->index = w->pkgs[p->index].index; /* its first declaration's record */+ continue;+ }+ p->index = records++;+ pl_sb_puts(sb, "P\t");+ pl_sb_put(sb, p->name, p->len);+ pl_sb_puts(sb, "\n");+ }+}++static int pl_subdecl_cmp(const void *a, const void *b) {+ const pl_subdecl_t *x = (const pl_subdecl_t *)a;+ const pl_subdecl_t *y = (const pl_subdecl_t *)b;+ if (x->line != y->line) {+ return x->line < y->line ? -1 : 1;+ }+ return pl_name_cmp(x->name, x->len, y->name, y->len);+}++/* One S record per sub definition of the file, with the package the tree+ * places it in. */+static void pl_put_subs(CBMExtractCtx *ctx, pl_walk_t *w, pl_sb_t *sb) {+ qsort(w->subs, (size_t)w->nsubs, sizeof(pl_subdecl_t), pl_subdecl_cmp);+ const CBMDefArray *defs = &ctx->result->defs;+ for (int i = 0; i < defs->count; i++) {+ const CBMDefinition *d = &defs->items[i];+ if (!d->name || !d->label || strcmp(d->label, "Function") != 0 ||+ !pl_name_ok(d->name, strlen(d->name))) {+ continue;+ }+ pl_subdecl_t key = {+ .name = d->name, .len = (uint32_t)strlen(d->name), .line = d->start_line};+ const pl_subdecl_t *hit =+ w->nsubs > 0 ? (const pl_subdecl_t *)bsearch(&key, w->subs, (size_t)w->nsubs,+ sizeof(pl_subdecl_t), pl_subdecl_cmp)+ : NULL;+ int pkg = hit ? hit->pkg : PL_PKG_UNKNOWN;+ char field[CBM_SZ_32];+ if (pkg >= 0) {+ snprintf(field, sizeof(field), "S\t%d\t", w->pkgs[pkg].index);+ } else {+ snprintf(field, sizeof(field), "S\t%s\t", pkg == PL_PKG_MAIN ? "-" : "?");+ }+ pl_sb_puts(sb, field);+ pl_sb_puts(sb, d->name);+ pl_sb_puts(sb, "\n");+ }+}++static void pl_put_heading(pl_sb_t *sb, const pl_sec_t *sec, const char *key) {+ if (!key[0]) {+ return;+ }+ pl_sb_puts(sb, "H\t");+ if (sec->name_len > 0) {+ pl_sb_put(sb, sec->name, sec->name_len);+ } else {+ pl_sb_puts(sb, "-");+ }+ pl_sb_puts(sb, "\t");+ pl_sb_puts(sb, key);+ pl_sb_puts(sb, "\n");+}++/* The text after an =item's bullet (`*`) or number (`1.`), or NULL when the+ * item has neither. */+static const char *pl_after_bullet(const char *key) {+ const char *p = key;+ if (*p == '*') {+ p++;+ } else {+ while (isdigit((unsigned char)*p)) {+ p++;+ }+ if (p == key) {+ return NULL;+ }+ p += *p == '.';+ }+ return (*p == ' ' || *p == '\0') ? pl_skip_spaces(p) : NULL;+}++/* One H record per heading. Pod::Simple reads `=item * text` and `=item 1.+ * text` as a bullet and its text when the list is a bullet or numbered list,+ * and as the whole text otherwise; which kind a list is depends on its first+ * item, so a numbered text is recorded both ways. */+static void pl_put_headings(const pl_scan_t *s, pl_sb_t *sb) {+ for (int i = 0; i < s->nsecs; i++) {+ const pl_sec_t *sec = &s->secs[i];+ char key[CBM_DOCLINK_PERL_KEY_MAX];+ cbm_doclink_perl_plain_text(s->src + sec->hb, sec->he - sec->hb, key, sizeof(key));+ const char *rest = sec->item ? pl_after_bullet(key) : NULL;+ if (!rest) {+ pl_put_heading(sb, sec, key);+ } else if (key[0] == '*') {+ pl_put_heading(sb, sec, rest);+ } else if (rest[0]) {+ pl_put_heading(sb, sec, key);+ pl_put_heading(sb, sec, rest);+ }+ }+}++const char *cbm_doclink_perl_scan_scope(CBMExtractCtx *ctx) {+ if (!ctx || !ctx->result || ts_node_is_null(ctx->root)) {+ return NULL;+ }+ pl_scan_t s;+ pl_scan_init(&s, ctx);+ pl_sb_t sb = {.a = ctx->arena};+ pl_sb_puts(&sb, CBM_DOCLINK_PERL_SCOPE_TAG "\n");+ if (ts_node_has_error(ctx->root)) {+ pl_sb_puts(&sb, "E\n");+ }+ pl_walk_t w = {.s = &s, .current = PL_PKG_MAIN, .pending_block = PL_PKG_UNKNOWN};+ pl_walk_tree(&w, ctx->root);+ pl_number_packages(&w, &sb);+ pl_put_subs(ctx, &w, &sb);+ pl_scan_file(&s);+ pl_put_headings(&s, &sb);+ if (s.failed || sb.failed || !sb.buf) {+ return NULL;+ }+ return sb.buf;+}diff --git a/src/pipeline/doc_links.c b/src/pipeline/doc_links.cindex a365ddf41..c912ac9e0 100644--- a/src/pipeline/doc_links.c+++ b/src/pipeline/doc_links.c@@ -47,7 +47,7 @@ const char *cbm_doclink_reason_name(int reason) {static const cbm_doclink_resolver_t *const DOCLINK_RESOLVERS[] = {&cbm_doclink_cs_resolver, &cbm_doclink_md_resolver, &cbm_doclink_pdf_resolver,&cbm_doclink_rst_resolver, &cbm_doclink_adoc_resolver, &cbm_doclink_go_resolver,- &cbm_doclink_jvm_resolver, &cbm_doclink_rs_resolver,+ &cbm_doclink_jvm_resolver, &cbm_doclink_rs_resolver, &cbm_doclink_perl_resolver,};enum { DOCLINK_RESOLVER_COUNT = sizeof(DOCLINK_RESOLVERS) / sizeof(DOCLINK_RESOLVERS[0]) };diff --git a/src/pipeline/doc_links.h b/src/pipeline/doc_links.hindex a85e3d512..e0ca5820f 100644--- a/src/pipeline/doc_links.h+++ b/src/pipeline/doc_links.h@@ -298,6 +298,7 @@ bool cbm_doclinks_binds_lines(CBMLanguage lang);extern const cbm_doclink_resolver_t cbm_doclink_go_resolver;extern const cbm_doclink_resolver_t cbm_doclink_jvm_resolver;extern const cbm_doclink_resolver_t cbm_doclink_rs_resolver;+extern const cbm_doclink_resolver_t cbm_doclink_perl_resolver;/* True when `rel_path` is a scope input of some language (scope_input). */bool cbm_doclinks_is_scope_input(const char *rel_path);diff --git a/src/pipeline/doc_links_perl.c b/src/pipeline/doc_links_perl.cnew file mode 100644index 000000000..8736ce506--- /dev/null+++ b/src/pipeline/doc_links_perl.c@@ -0,0 +1,489 @@+/*+ * doc_links_perl.c — resolving Perl POD L<> references (doclink_perl.c).+ *+ * A page is a module. L<Mojo::Base> binds the module whose file declares+ * `package Mojo::Base;` (the scope blob's P records). When several files+ * declare it, the one the library layout names (…/Mojo/Base.pm) is the+ * module; more than one such file, or none among several, is ambiguous. A page+ * the repository does not declare (CPAN, the Perl core, a .pod page:+ * discovery keeps no .pod file, so nothing can say it is in the repository)+ * is external, and so is a man page (L<crontab(5)>).+ *+ * The target of a module is its File node: a POD page is the file it is+ * written in (the field test's audited rule). Its Module node would do for+ * most, but not where a same-named Folder holds the module's qualified name+ * (lib/Mojo.pm next to lib/Mojo/).+ *+ * A section, L<Module/section>: when a heading of the module's file reads+ * `section` (POD text as it renders, cbm_doclink_perl_plain_text) and names a+ * sub that has a definition in that file, the target is the sub; headings+ * that name two subs are ambiguous. A section that names no sub is a place in+ * the module's documentation: the target is the module. L</section> is the+ * same page: a sub its heading names binds; a heading that names no sub is a+ * place in the source's own page, no reference worth an edge or a row+ * (local); a section the page has no heading for is missing (doc rot).+ *+ * Test code (t/, xt/, *.t, and cbm_is_test_file) is bound only from test code.+ * Every edge is exact: a module name and a heading are spelled out in full.+ *+ * The scope blob carries no lines (doclink_perl.c), and without a scope_delta+ * hook every change of a blob is a full re-resolution: a change that adds or+ * drops a package, a sub or a heading; an edit inside a sub changes no blob.+ */+#include "pipeline/doc_links.h"+#include "pipeline/pipeline_internal.h" /* cbm_pipeline_file_node */+#include "cbm.h"+#include "doclink.h"+#include "helpers.h" /* cbm_fqn_module_source_lang, cbm_is_test_file */+#include "foundation/arena.h"+#include "foundation/constants.h"+#include "foundation/hash_table.h"+#include "foundation/log.h"+#include "foundation/mem_core.h"+#include "graph_buffer/graph_buffer.h"++#include <stdbool.h>+#include <stddef.h>+#include <stdint.h>+#include <stdio.h>+#include <stdlib.h>+#include <string.h>++/* ── The index ───────────────────────────────────────────────────── */++typedef struct {+ const char *sub; /* the sub the heading names; NULL: none */+ const char *key; /* the heading as it renders */+} pr_head_t;++typedef struct {+ const char *path; /* rel_path */+ const char *module_qn; /* the file's module qualified name */+ bool test;+ int nsubs;+ const char **subs; /* subs with a definition in the file */+ int nheads;+ pr_head_t *heads;+} pr_file_t;++typedef struct {+ const char *name;+ int file;+} pr_decl_t;++typedef struct {+ int first; /* into decls */+ int count;+} pr_range_t;++typedef struct {+ CBMArena arena;+ const char *project;+ pr_file_t *files;+ int nfiles;+ int *run_to_file; /* run_file -> files index, -1: none */+ int run_count;+ pr_decl_t *decls; /* every package declaration, by name, then path */+ int ndecls;+ CBMHashTable *pkg; /* package name -> pr_range_t */+ bool oom;+} pr_index_t;++static bool pr_test_path(const char *path) {+ if (cbm_is_test_file(path, CBM_LANG_PERL)) {+ return true;+ }+ size_t n = strlen(path);+ if (n >= PAIR_LEN && strcmp(path + n - PAIR_LEN, ".t") == 0) {+ return true;+ }+ return strncmp(path, "t/", PAIR_LEN) == 0 || strncmp(path, "xt/", CBM_SZ_3) == 0 ||+ strstr(path, "/t/") != NULL || strstr(path, "/xt/") != NULL;+}++/* One record line of a blob: its fields, split at tabs (at most `cap`). */+static int pr_fields(const char *b, const char *e, const char **f, size_t *fl, int cap) {+ int n = 0;+ const char *s = b;+ for (const char *p = b; p <= e && n < cap; p++) {+ if (p == e || *p == '\t') {+ f[n] = s;+ fl[n] = (size_t)(p - s);+ n++;+ s = p + SKIP_ONE;+ }+ }+ return n;+}++enum { PR_MAX_FIELDS = 4, PR_F_TAG = 0, PR_F_A = 1, PR_F_B = 2 };++static const char *pr_copy(pr_index_t *ix, const char *s, size_t n) {+ char *c = cbm_arena_strndup(&ix->arena, s, n);+ ix->oom = ix->oom || !c;+ return c;+}++/* Count, then fill: the records of one file's blob. */+static void pr_read_blob(pr_index_t *ix, int fi, const char *blob, bool fill) {+ pr_file_t *f = &ix->files[fi];+ int np = 0;+ int ns = 0;+ int nh = 0;+ const char *line = strchr(blob, '\n'); /* the tag line */+ while (line && !ix->oom) {+ const char *b = line + SKIP_ONE;+ const char *e = strchr(b, '\n');+ if (!e) {+ e = b + strlen(b);+ }+ const char *fld[PR_MAX_FIELDS];+ size_t fln[PR_MAX_FIELDS];+ int n = pr_fields(b, e, fld, fln, PR_MAX_FIELDS);+ if (n >= PAIR_LEN && fln[PR_F_TAG] == SKIP_ONE) {+ char tag = fld[PR_F_TAG][0];+ if (tag == 'P') {+ if (fill) {+ ix->decls[ix->ndecls++] =+ (pr_decl_t){pr_copy(ix, fld[PR_F_A], fln[PR_F_A]), fi};+ }+ np++;+ } else if (tag == 'S' && n >= CBM_SZ_3) {+ if (fill) {+ f->subs[f->nsubs++] = pr_copy(ix, fld[PR_F_B], fln[PR_F_B]);+ }+ ns++;+ } else if (tag == 'H' && n >= CBM_SZ_3) {+ if (fill) {+ bool none = fln[PR_F_A] == SKIP_ONE && fld[PR_F_A][0] == '-';+ f->heads[f->nheads++] = (pr_head_t){+ none ? NULL : pr_copy(ix, fld[PR_F_A], fln[PR_F_A]),+ pr_copy(ix, fld[PR_F_B], fln[PR_F_B]),+ };+ }+ nh++;+ }+ }+ line = *e ? e : NULL;+ }+ if (!fill) {+ ix->ndecls += np;+ f->subs =+ ns ? (const char **)cbm_arena_alloc(&ix->arena, (size_t)ns * sizeof(char *)) : NULL;+ f->heads =+ nh ? (pr_head_t *)cbm_arena_alloc(&ix->arena, (size_t)nh * sizeof(pr_head_t)) : NULL;+ ix->oom = ix->oom || (ns && !f->subs) || (nh && !f->heads);+ }+}++static int pr_decl_cmp(const void *a, const void *b) {+ const pr_decl_t *x = (const pr_decl_t *)a;+ const pr_decl_t *y = (const pr_decl_t *)b;+ int c = strcmp(x->name, y->name);+ return c != 0 ? c : (x->file > y->file) - (x->file < y->file);+}++static void pr_destroy(void *index) {+ pr_index_t *ix = (pr_index_t *)index;+ if (!ix) {+ return;+ }+ cbm_ht_free(ix->pkg);+ cbm_free(CBM_MEM_CLASS_OTHER, ix->run_to_file);+ cbm_arena_destroy(&ix->arena);+ cbm_free(CBM_MEM_CLASS_OTHER, ix);+}++static bool pr_index_files(pr_index_t *ix, const cbm_doclink_build_in_t *in) {+ ix->nfiles = in->file_count;+ ix->files =+ in->file_count+ ? (pr_file_t *)cbm_arena_calloc(&ix->arena, (size_t)in->file_count * sizeof(pr_file_t))+ : NULL;+ ix->run_count = in->run_file_count;+ ix->run_to_file = (int *)cbm_calloc(CBM_MEM_CLASS_OTHER,+ (size_t)(in->run_file_count + SKIP_ONE) * sizeof(int));+ if ((in->file_count && !ix->files) || !ix->run_to_file) {+ return false;+ }+ for (int r = 0; r < in->run_file_count; r++) {+ ix->run_to_file[r] = CBM_NOT_FOUND;+ }+ for (int i = 0; i < in->file_count && !ix->oom; i++) {+ const cbm_doclink_file_t *src = &in->files[i];+ pr_file_t *f = &ix->files[i];+ f->path = src->rel_path; /* valid until destroy */+ f->module_qn =+ cbm_fqn_module_source_lang(&ix->arena, ix->project, src->rel_path, CBM_LANG_PERL);+ f->test = pr_test_path(src->rel_path);+ ix->oom = ix->oom || !f->module_qn;+ if (src->run_file >= 0 && src->run_file < in->run_file_count) {+ ix->run_to_file[src->run_file] = i;+ }+ if (src->scope) {+ pr_read_blob(ix, i, src->scope, false);+ }+ }+ return !ix->oom;+}++static bool pr_index_packages(pr_index_t *ix, const cbm_doclink_build_in_t *in) {+ int total = ix->ndecls;+ ix->ndecls = 0;+ ix->decls =+ total ? (pr_decl_t *)cbm_arena_alloc(&ix->arena, (size_t)total * sizeof(pr_decl_t)) : NULL;+ if (total && !ix->decls) {+ return false;+ }+ for (int i = 0; i < in->file_count && !ix->oom; i++) {+ if (in->files[i].scope) {+ pr_read_blob(ix, i, in->files[i].scope, true);+ }+ }+ if (ix->oom) {+ return false;+ }+ qsort(ix->decls, (size_t)ix->ndecls, sizeof(pr_decl_t), pr_decl_cmp);+ ix->pkg = cbm_ht_create_in(CBM_MEM_CLASS_OTHER, (uint32_t)(ix->ndecls + SKIP_ONE));+ if (!ix->pkg) {+ return false;+ }+ for (int i = 0; i < ix->ndecls;) {+ int j = i;+ while (j < ix->ndecls && strcmp(ix->decls[j].name, ix->decls[i].name) == 0) {+ j++;+ }+ pr_range_t *r = (pr_range_t *)cbm_arena_alloc(&ix->arena, sizeof(pr_range_t));+ if (!r) {+ return false;+ }+ *r = (pr_range_t){i, j - i};+ cbm_ht_set(ix->pkg, ix->decls[i].name, r);+ i = j;+ }+ return true;+}++static void *pr_build(const cbm_doclink_build_in_t *in) {+ pr_index_t *ix = (pr_index_t *)cbm_calloc(CBM_MEM_CLASS_OTHER, sizeof(*ix));+ if (!ix) {+ return NULL;+ }+ cbm_arena_init(&ix->arena);+ ix->project = in->ctx->project_name;+ if (!pr_index_files(ix, in) || !pr_index_packages(ix, in)) {+ cbm_log_error("doc_links.perl.error", "step", "index", "reason", "alloc");+ pr_destroy(ix);+ return NULL;+ }+ char b[PAIR_LEN][CBM_SZ_32];+ snprintf(b[0], sizeof(b[0]), "%d", ix->nfiles);+ snprintf(b[SKIP_ONE], sizeof(b[SKIP_ONE]), "%u", cbm_ht_count(ix->pkg));+ cbm_log_info("doc_links.perl.index", "files", b[0], "packages", b[SKIP_ONE]);+ return ix;+}++/* ── Resolution ──────────────────────────────────────────────────── */++typedef struct {+ const pr_index_t *ix;+ const cbm_gbuf_t *g;+ const pr_file_t *src;+ cbm_doclink_outcome_t *out;+} pr_ctx_t;++static void pr_row(const pr_ctx_t *c, int reason) {+ c->out->kind = CBM_DOCLINK_UNRESOLVED;+ c->out->reason = reason;+}++static void pr_edge(const pr_ctx_t *c, const pr_file_t *f, const cbm_gbuf_node_t *node) {+ if (!node) {+ pr_row(c, CBM_DOCLINK_REASON_GRAPH_GAP);+ return;+ }+ if (f->test && !c->src->test) {+ pr_row(c, CBM_DOCLINK_REASON_TEST_ONLY);+ return;+ }+ c->out->kind = CBM_DOCLINK_EDGE;+ c->out->target = node;+ c->out->exact = true;+}++static bool pr_node_is(const cbm_gbuf_node_t *n, const pr_file_t *f, const char *label) {+ return n && n->label && n->file_path && strcmp(n->label, label) == 0 &&+ strcmp(n->file_path, f->path) == 0;+}++/* The module's node: its File node. */+static const cbm_gbuf_node_t *pr_module_node(const pr_ctx_t *c, const pr_file_t *f) {+ return cbm_pipeline_file_node(c->g, c->ix->project, f->path);+}++/* The node of sub `name` of file f; NULL when it has none of its own. */+static const cbm_gbuf_node_t *pr_sub_node(const pr_ctx_t *c, const pr_file_t *f, const char *name) {+ size_t ql = strlen(f->module_qn);+ size_t nl = strlen(name);+ char stack[CBM_SZ_512];+ char *qn = ql + nl + PAIR_LEN <= sizeof(stack)+ ? stack+ : (char *)cbm_alloc(CBM_MEM_CLASS_OTHER, ql + nl + PAIR_LEN);+ if (!qn) {+ return NULL;+ }+ memcpy(qn, f->module_qn, ql);+ qn[ql] = '.';+ memcpy(qn + ql + SKIP_ONE, name, nl + SKIP_ONE);+ const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(c->g, qn);+ if (qn != stack) {+ cbm_free(CBM_MEM_CLASS_OTHER, qn);+ }+ return (pr_node_is(n, f, "Function") || pr_node_is(n, f, "Method")) ? n : NULL;+}++static bool pr_has_sub(const pr_file_t *f, const char *name) {+ for (int i = 0; i < f->nsubs; i++) {+ if (strcmp(f->subs[i], name) == 0) {+ return true;+ }+ }+ return false;+}++/* The one sub a heading `key` of file f names (it has a definition there):+ * 1 found, 0 none, 2 several. */+static int pr_heading_sub(const pr_file_t *f, const char *key, const char **sub) {+ *sub = NULL;+ for (int i = 0; i < f->nheads; i++) {+ const pr_head_t *h = &f->heads[i];+ if (!h->sub || strcmp(h->key, key) != 0 || !pr_has_sub(f, h->sub)) {+ continue;+ }+ if (*sub && strcmp(*sub, h->sub) != 0) {+ return PAIR_LEN;+ }+ *sub = h->sub;+ }+ return *sub ? SKIP_ONE : 0;+}++static bool pr_has_heading(const pr_file_t *f, const char *key) {+ for (int i = 0; i < f->nheads; i++) {+ if (strcmp(f->heads[i].key, key) == 0) {+ return true;+ }+ }+ return false;+}++static void pr_section(const pr_ctx_t *c, const pr_file_t *f, const char *section, bool same_page) {+ char key[CBM_DOCLINK_PERL_KEY_MAX];+ cbm_doclink_perl_plain_text(section, strlen(section), key, sizeof(key));+ const char *sub = NULL;+ int found = pr_heading_sub(f, key, &sub);+ if (found > SKIP_ONE) {+ pr_row(c, CBM_DOCLINK_REASON_AMBIGUOUS);+ } else if (found == SKIP_ONE) {+ pr_edge(c, f, pr_sub_node(c, f, sub));+ } else if (same_page && pr_has_heading(f, key)) {+ c->out->kind = CBM_DOCLINK_LOCAL; /* a place in the source's own page */+ } else if (same_page) {+ pr_row(c, CBM_DOCLINK_REASON_MISSING); /* a section the page does not have */+ } else {+ pr_edge(c, f, pr_module_node(c, f));+ }+}++/* True when `path` is the file the library layout gives module `page`. */+static bool pr_layout_names(const char *path, const char *page) {+ char want[CBM_DOCLINK_PERL_KEY_MAX + CBM_SZ_8];+ size_t w = 0;+ for (const char *p = page; *p && w + CBM_SZ_4 < sizeof(want); p++) {+ if (p[0] == ':' && p[SKIP_ONE] == ':') {+ want[w++] = '/';+ p++;+ } else {+ want[w++] = *p;+ }+ }+ memcpy(want + w, ".pm", CBM_SZ_4);+ w += CBM_SZ_3;+ size_t n = strlen(path);+ return n >= w && strcmp(path + n - w, want) == 0 && (n == w || path[n - w - SKIP_ONE] == '/');+}++/* The file of module `page`: NULL with *ambiguous false when the repository+ * declares no such package. */+static const pr_file_t *pr_page_file(const pr_index_t *ix, const char *page, bool *ambiguous) {+ *ambiguous = false;+ const pr_range_t *r = (const pr_range_t *)cbm_ht_get(ix->pkg, page);+ if (!r || r->count == 0) {+ return NULL;+ }+ if (r->count == SKIP_ONE) {+ return &ix->files[ix->decls[r->first].file];+ }+ const pr_file_t *hit = NULL;+ for (int i = r->first; i < r->first + r->count; i++) {+ const pr_file_t *f = &ix->files[ix->decls[i].file];+ if (f == hit || !pr_layout_names(f->path, page)) {+ continue;+ }+ if (hit) {+ *ambiguous = true;+ return NULL;+ }+ hit = f;+ }+ *ambiguous = hit == NULL;+ return hit;+}++static void pr_resolve(const void *index, void *state, int run_file, const CBMDocLink *link,+ const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {+ (void)state; /* Perl keeps no per-file working state */+ const pr_index_t *ix = (const pr_index_t *)index;+ out->kind = CBM_DOCLINK_UNRESOLVED;+ out->reason = CBM_DOCLINK_REASON_MISSING;+ out->target = NULL;+ out->exact = false;+ if (!ix || !link->raw || run_file < 0 || run_file >= ix->run_count ||+ ix->run_to_file[run_file] < 0) {+ return;+ }+ pr_ctx_t c = {.ix = ix, .g = graph, .src = &ix->files[ix->run_to_file[run_file]], .out = out};+ CBMPerlLink pl;+ if (!cbm_doclink_perl_parse_link(link->raw, &pl)) {+ pr_row(&c, CBM_DOCLINK_REASON_UNPARSEABLE);+ return;+ }+ if (pl.kind == CBM_PERL_LINK_MAN) {+ pr_row(&c, CBM_DOCLINK_REASON_EXTERNAL);+ return;+ }+ if (pl.kind == CBM_PERL_LINK_SECTION) {+ pr_section(&c, c.src, pl.section, true);+ return;+ }+ bool ambiguous = false;+ const pr_file_t *f = pr_page_file(ix, pl.page, &ambiguous);+ if (!f) {+ pr_row(&c, ambiguous ? CBM_DOCLINK_REASON_AMBIGUOUS : CBM_DOCLINK_REASON_EXTERNAL);+ return;+ }+ if (pl.section[0]) {+ pr_section(&c, f, pl.section, false);+ return;+ }+ pr_edge(&c, f, pr_module_node(&c, f));+}++const cbm_doclink_resolver_t cbm_doclink_perl_resolver = {+ .langs = {CBM_LANG_PERL},+ .lang_count = 1,+ .scope_tag = CBM_DOCLINK_PERL_SCOPE_TAG,+ .build = pr_build,+ .destroy = pr_destroy,+ .resolve = pr_resolve,+};diff --git a/tests/test_doc_mentions_helpers.h b/tests/test_doc_mentions_helpers.hindex e37ee9368..f0e2312e1 100644--- a/tests/test_doc_mentions_helpers.h+++ b/tests/test_doc_mentions_helpers.h@@ -439,7 +439,7 @@ static const int DM_HELD_FAMILIES[] = {CBM_DOCLINK_JAVA_VALUE, CBM_DOCLINK_KT_KDOC_LINK,CBM_DOCLINK_KT_SEE, CBM_DOCLINK_KT_THROWS,CBM_DOCLINK_KT_SAMPLE, CBM_DOCLINK_RS_INTRA_DOC,- CBM_DOCLINK_RS_LINK_DEF,+ CBM_DOCLINK_RS_LINK_DEF, CBM_DOCLINK_PERL_POD_L,};static inline void dm_ship_held_families(void) {diff --git a/tests/test_doc_mentions_perl.c b/tests/test_doc_mentions_perl.cnew file mode 100644index 000000000..177d4a9d5--- /dev/null+++ b/tests/test_doc_mentions_perl.c@@ -0,0 +1,292 @@+/*+ * test_doc_mentions_perl.c -- Perl POD L<> codes as doc-comment references.+ *+ * A sub's doc is the POD section that names it; the file's module doc (its+ * File node's docstring) is the POD no sub holds. The L<> codes of both are+ * the references: module-level ones come from the File node.+ */+#include "../src/foundation/compat.h"+#include "test_framework.h"+#include "test_helpers.h"+#include "test_doc_mentions_helpers.h"++#include "cbm.h"+#include "doclink.h"++#include <stdio.h>+#include <string.h>++/* ── extraction ──────────────────────────────────────────────────── */++static const char *const PL_KNOB =+ "package Knob;\n" /* 1 */+ "\n" /* 2 */+ "=head1 NAME\n" /* 3 */+ "\n" /* 4 */+ "Knob - see L<Dial> and L<the knob|Knob::Turn/turning>.\n" /* 5 */+ "\n" /* 6 */+ "=cut\n" /* 7 */+ "\n" /* 8 */+ "sub turn { return 1; }\n" /* 9 */+ "1;\n" /* 10 */+ "__END__\n" /* 11 */+ "\n" /* 12 */+ "=head1 METHODS\n" /* 13 */+ "\n" /* 14 */+ "Methods, see L</turn> and L<https://example.org/k>.\n" /* 15 */+ "\n" /* 16 */+ "=head2 turn\n" /* 17 */+ "\n" /* 18 */+ "Turns, like L<Knob::Spin>.\n" /* 19 */+ "\n" /* 20 */+ "=head2 spin\n" /* 21 */+ "\n" /* 22 */+ "About L<perlfunc/open> and L<crontab(5)>.\n" /* 23 */+ "\n" /* 24 */+ "=cut\n"; /* 25 */++/* The one token `raw`: its line, whether it is the file's, its family. */+static bool pl_token_is(const CBMFileResult *r, const char *raw, uint32_t line, bool file,+ int syntax) {+ if (dm_count_tokens(r, raw) != 1) {+ printf(" token %s: %d found\n", raw, dm_count_tokens(r, raw));+ return false;+ }+ const CBMDocLink *t = dm_find_token(r, raw);+ bool is_file = (t->flags & CBM_DOCLINK_FLAG_FILE) != 0;+ if (t->line != line || is_file != file || t->syntax != syntax) {+ printf(" token %s: line %u file %d syntax %d\n", raw, t->line, is_file, t->syntax);+ return false;+ }+ return true;+}++TEST(doc_mentions_perl_tokens) {+ CBMFileResult *r = dm_extract(PL_KNOB, CBM_LANG_PERL, "lib/Knob.pm");+ ASSERT_NOT_NULL(r);+ /* the module doc's references come from the file, each on its own line */+ ASSERT_TRUE(pl_token_is(r, "Dial", 5, true, CBM_DOCLINK_PERL_POD_L));+ ASSERT_TRUE(pl_token_is(r, "the knob|Knob::Turn/turning", 5, true, CBM_DOCLINK_PERL_POD_L));+ ASSERT_TRUE(pl_token_is(r, "/turn", 15, true, CBM_DOCLINK_PERL_POD_L));+ ASSERT_TRUE(pl_token_is(r, "https://example.org/k", 15, true, CBM_DOCLINK_HREF));+ ASSERT_TRUE(pl_token_is(r, "perlfunc/open", 23, true, CBM_DOCLINK_PERL_POD_L));+ ASSERT_TRUE(pl_token_is(r, "crontab(5)", 23, true, CBM_DOCLINK_PERL_POD_L));+ /* a sub's section is the sub's, and only the sub's */+ ASSERT_TRUE(pl_token_is(r, "Knob::Spin", 19, false, CBM_DOCLINK_PERL_POD_L));+ const CBMDocLink *t = dm_find_token(r, "Knob::Spin");+ ASSERT_NOT_NULL(strstr(t->source_qn, "turn"));+ ASSERT_EQ(r->doc_links.count, 7);+ cbm_free_result(r);+ PASS();+}++/* ── resolution ──────────────────────────────────────────────────── */++static void pl_write_repo(const char *repo) {+ th_write_file(TH_PATH(repo, "lib/Knob.pm"),+ "package Knob;\n"+ "\n"+ "=head1 NAME\n"+ "\n"+ "Knob - L<Knob::Dial>, L<Knob::Dial/spin>, L<Knob::Dial/OVERVIEW>.\n"+ "\n"+ "=head1 SEE ALSO\n"+ "\n"+ "L</turn>, L</NOTES>, L</GONE>, L<Mojo::Base>, L<crontab(5)>, L<TestHelper>,\n"+ "L<Dup>.\n"+ "\n"+ "=head1 NOTES\n"+ "\n"+ "Nothing.\n"+ "\n"+ "=cut\n"+ "\n"+ "sub turn { return 1; }\n"+ "\n"+ "=head2 turn\n"+ "\n"+ "Turns, see L<Knob::Dial/spin>.\n"+ "\n"+ "=cut\n"+ "\n"+ "1;\n");+ th_write_file(TH_PATH(repo, "lib/Knob/Dial.pm"), "package Knob::Dial;\n"+ "\n"+ "=head1 OVERVIEW\n"+ "\n"+ "The dial of L<Knob>.\n"+ "\n"+ "=cut\n"+ "\n"+ "sub spin { return 2; }\n"+ "\n"+ "=head2 spin\n"+ "\n"+ "Spins.\n"+ "\n"+ "=cut\n"+ "\n"+ "1;\n");+ /* a second declaration of Knob::Dial, not where the library layout puts it */+ th_write_file(TH_PATH(repo, "lib/Extra.pm"), "package Knob::Dial;\nsub extra { 3 }\n1;\n");+ /* Dup twice, neither at its layout path */+ th_write_file(TH_PATH(repo, "lib/A.pm"), "package Dup;\nsub a { 1 }\n1;\n");+ th_write_file(TH_PATH(repo, "lib/B.pm"), "package Dup;\nsub b { 1 }\n1;\n");+ th_write_file(TH_PATH(repo, "t/lib/TestHelper.pm"),+ "package TestHelper;\nsub help { 1 }\n1;\n");+}++static bool pl_edge(const char *db, const char *src, const char *tgt) {+ char props[512];+ int n = 0;+ dm_edge(db, src, tgt, props, sizeof(props), &n);+ if (n != 1 || !strstr(props, "\"tier\":\"exact\"")) {+ printf(" edge %s -> %s: %d found %s\n", src, tgt, n, props);+ return false;+ }+ return true;+}++static bool pl_row(const char *db, const char *rel, const char *raw, const char *reason) {+ char got[64];+ dm_row(db, rel, raw, got, sizeof(got), NULL, 0);+ if (strcmp(got, reason) != 0) {+ printf(" row %s [%s]: \"%s\", expected \"%s\"\n", rel, raw, got, reason);+ return false;+ }+ return true;+}++TEST(doc_mentions_perl_resolution) {+ char tmp[256];+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlperl_XXXXXX");+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));+ char repo[512];+ char db[512];+ snprintf(repo, sizeof(repo), "%s/repo", tmp);+ snprintf(db, sizeof(db), "%s/g.db", tmp);+ pl_write_repo(repo);+ ASSERT_EQ(dm_index(repo, db, NULL), 0);+ const char *knob = "lib/Knob.pm";+ /* a module the library layout names, though another file declares it too */+ ASSERT_TRUE(pl_edge(db, "lib.Knob.pm.__file__", "lib.Knob.Dial.pm.__file__"));+ /* a section whose heading names a sub of the module: the sub */+ ASSERT_TRUE(pl_edge(db, "lib.Knob.pm.__file__", "lib.Knob.Dial.spin"));+ ASSERT_TRUE(pl_edge(db, "lib.Knob.turn", "lib.Knob.Dial.spin"));+ /* the same page: a sub binds, a section that names none is local */+ ASSERT_TRUE(pl_edge(db, "lib.Knob.pm.__file__", "lib.Knob.turn"));+ ASSERT_TRUE(pl_row(db, knob, "/NOTES", ""));+ /* ... and one the page has no heading for is doc rot */+ ASSERT_TRUE(pl_row(db, knob, "/GONE", "missing"));+ /* outside the repository, a man page, test code, two declarations */+ ASSERT_TRUE(pl_row(db, knob, "Mojo::Base", "external"));+ ASSERT_TRUE(pl_row(db, knob, "crontab(5)", "external"));+ ASSERT_TRUE(pl_row(db, knob, "TestHelper", "test_only_target"));+ ASSERT_TRUE(pl_row(db, knob, "Dup", "ambiguous"));+ /* the page is the file, also where a Folder holds lib/Knob.pm's module name */+ ASSERT_TRUE(pl_edge(db, "lib.Knob.Dial.pm.__file__", "lib.Knob.pm.__file__"));+ th_cleanup(tmp);+ PASS();+}++/* ── incremental == full; one worker == several ──────────────────── */++#define PL_INC_DIAL \+ "package Knob::Dial;\n\n=head1 OVERVIEW\n\nThe dial.\n\n=cut\n\nsub spin { 2 }\n\n" \+ "=head2 spin\n\nSpins.\n\n=cut\n\n1;\n"++TEST(doc_mentions_perl_incremental_equals_full) {+ char tmp[256];+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlperl_inc_XXXXXX");+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));+ char repo[512];+ char inc_db[512];+ char full_db[512];+ snprintf(repo, sizeof(repo), "%s/repo", tmp);+ snprintf(inc_db, sizeof(inc_db), "%s/inc.db", tmp);+ snprintf(full_db, sizeof(full_db), "%s/full.db", tmp);+ th_write_file(TH_PATH(repo, "lib/Knob.pm"),+ "package Knob;\n\n=head1 NAME\n\nKnob - see L<Knob::Dial/spin>.\n\n=cut\n\n"+ "sub turn { 1 }\n1;\n");+ th_write_file(TH_PATH(repo, "lib/Knob/Dial.pm"), PL_INC_DIAL);+ ASSERT_EQ(dm_index(repo, inc_db, NULL), 0);+ ASSERT_TRUE(pl_edge(inc_db, "lib.Knob.pm.__file__", "lib.Knob.Dial.spin"));++ /* the module doc's text changes: the file is repaired alone */+ th_write_file(+ TH_PATH(repo, "lib/Knob.pm"),+ "package Knob;\n\n=head1 NAME\n\nKnob, a knob - see L<Knob::Dial/spin>.\n\n=cut\n\n"+ "sub turn { 1 }\n1;\n");+ ASSERT_EQ(+ dm_step(repo, inc_db, full_db, "module doc edit", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);+ ASSERT_TRUE(pl_edge(inc_db, "lib.Knob.pm.__file__", "lib.Knob.Dial.spin"));++ /* a reference added to the module doc: an edge from the File node */+ th_write_file(TH_PATH(repo, "lib/Knob.pm"),+ "package Knob;\n\n=head1 NAME\n\nKnob, a knob - see L<Knob::Dial/spin> and\n"+ "L<Knob::Dial>.\n\n=cut\n\nsub turn { 1 }\n1;\n");+ ASSERT_EQ(+ dm_step(repo, inc_db, full_db, "module doc link", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);+ ASSERT_TRUE(pl_edge(inc_db, "lib.Knob.pm.__file__", "lib.Knob.Dial.pm.__file__"));++ /* a new heading changes the file's scope blob: without a scope_delta hook+ * that is a full run */+ th_write_file(TH_PATH(repo, "lib/Knob.pm"),+ "package Knob;\n\n=head1 NAME\n\nKnob, a knob - see L<Knob::Dial/spin> and\n"+ "L<Knob::Dial>.\n\n=head1 SEE ALSO\n\nL<Knob::Dial/OVERVIEW>\n\n=cut\n\n"+ "sub turn { 1 }\n1;\n");+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "heading added", CBM_INCREMENTAL_ROUTE_FORCED_FULL),+ 0);++ /* the heading that named the sub goes: another file's section reference+ * now names a place in the module's documentation, the module */+ th_write_file(+ TH_PATH(repo, "lib/Knob/Dial.pm"),+ "package Knob::Dial;\n\n=head1 OVERVIEW\n\nThe dial.\n\n=cut\n\nsub spin { 2 }\n1;\n");+ ASSERT_EQ(dm_step(repo, inc_db, full_db, "heading removed", CBM_INCREMENTAL_ROUTE_FORCED_FULL),+ 0);+ char props[512];+ int n = 0;+ dm_edge(inc_db, "lib.Knob.pm.__file__", "lib.Knob.Dial.spin", props, sizeof(props), &n);+ ASSERT_EQ(n, 0);+ th_cleanup(tmp);+ PASS();+}++TEST(doc_mentions_perl_workers_agree) {+ char tmp[256];+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlperl_par_XXXXXX");+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));+ char repo[512];+ char par_db[512];+ char seq_db[512];+ snprintf(repo, sizeof(repo), "%s/repo", tmp);+ snprintf(par_db, sizeof(par_db), "%s/par.db", tmp);+ snprintf(seq_db, sizeof(seq_db), "%s/seq.db", tmp);+ enum { MODULES = 60 }; /* past the parallel threshold */+ for (int i = 0; i < MODULES; i++) {+ char rel[64];+ char src[1024];+ int next = (i + 1) % MODULES;+ snprintf(rel, sizeof(rel), "lib/Par/M%02d.pm", i);+ snprintf(src, sizeof(src),+ "package Par::M%02d;\n\n=head1 NAME\n\nPar::M%02d - see L<Par::M%02d>,\n"+ "L<Par::M%02d/run%02d>, L</run%02d>, L<Gone::Away> and L</GONE>.\n\n=cut\n\n"+ "sub run%02d { %d }\n\n=head2 run%02d\n\nRuns; also L<Par::M%02d/OVERVIEW>.\n\n"+ "=cut\n\n1;\n",+ i, i, next, next, next, i, i, i, i, next);+ th_write_file(TH_PATH(repo, rel), src);+ }+ ASSERT_EQ(dm_workers_agree(repo, par_db, seq_db), 0);+ ASSERT_TRUE(pl_edge(par_db, "lib.Par.M00.pm.__file__", "lib.Par.M01.run01"));+ th_cleanup(tmp);+ PASS();+}++SUITE(doc_mentions_perl) {+ dm_ship_held_families();+ RUN_TEST(doc_mentions_perl_tokens);+ RUN_TEST(doc_mentions_perl_resolution);+ RUN_TEST(doc_mentions_perl_incremental_equals_full);+ RUN_TEST(doc_mentions_perl_workers_agree);+}diff --git a/tests/test_main.c b/tests/test_main.cindex ae29520be..8c2c814d1 100644--- a/tests/test_main.c+++ b/tests/test_main.c@@ -1828,6 +1828,7 @@ extern void suite_doc_links_adoc(void);extern void suite_doc_mentions_go(void);extern void suite_doc_mentions_jvm(void);extern void suite_doc_mentions_rs(void);+extern void suite_doc_mentions_perl(void);extern void suite_infrascan(void);extern void suite_cli(void);extern void suite_agent_clients(void);@@ -2302,6 +2303,7 @@ int main(int argc, char **argv) {RUN_SELECTED_SUITE(doc_mentions_go);RUN_SELECTED_SUITE(doc_mentions_jvm);RUN_SELECTED_SUITE(doc_mentions_rs);+ RUN_SELECTED_SUITE(doc_mentions_perl);/* Infrastructure scanning */RUN_SELECTED_SUITE(infrascan);