Skip to content

Commit 3be5a02

Browse files
authored
Merge pull request DeusData#2601 from bline/fix/doc-link-missing-member
fix(doc-links): report a path::member reference to a missing member (DeusData#2587)
2 parents 59d6b52 + 9fe25c4 commit 3be5a02

3 files changed

Lines changed: 431 additions & 17 deletions

File tree

‎src/pipeline/doc_links_md.c‎

Lines changed: 136 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,23 @@
1010
* document says (the field tests' rule for bare file names).
1111
*
1212
* Into the file: a line range picks the innermost code definition that holds
13-
* the WHOLE range; a member (`path::Name`, `path::Owner::name`) picks the one
14-
* definition of that name in the file. Otherwise the edge goes to the file,
15-
* and the range stays on it ("target_lines"). Every edge is exact: the
16-
* document wrote the path.
13+
* the WHOLE range; a member (`path::Name`, `path::Owner::name`; a call form
14+
* `path::name()` reads as `path::name`) picks the one definition of that name
15+
* in the file. Otherwise the edge goes to the file, and the range stays on it
16+
* ("target_lines"); so does a member the code file writes without a
17+
* definition the graph binds (a macro, a prototype, an enum member, a class
18+
* attribute). Every edge is exact: the document wrote the path.
1719
*
1820
* Unresolved:
1921
* missing the path is not in the graph, but its directory is, or a
2022
* directory above it that the reference wrote is: the document
2123
* names something that is not there (doc rot; a moved or
22-
* renamed directory)
24+
* renamed directory); or a member whose name the code file
25+
* does not write at all
2326
* ambiguous a file name alone that is not next to the document but exists
24-
* elsewhere in the repository: the document does not say which
27+
* elsewhere in the repository: the document does not say which;
28+
* or a member name the file defines more than once, with no
29+
* owner to pick one
2530
* Not a reference to this repository at all (LOCAL: no edge, no row): a link
2631
* back into the same document; a path that is neither indexed nor of a type
2732
* the indexer reads (an image, an archive, an extensionless page); a path
@@ -35,11 +40,14 @@
3540
#include "discover/discover.h" /* cbm_language_for_filename */
3641
#include "doclink.h"
3742
#include "foundation/arena.h"
43+
#include "foundation/compat_fs.h" /* cbm_fopen */
3844
#include "foundation/constants.h"
3945
#include "foundation/hash_table.h"
46+
#include "foundation/limits.h" /* cbm_max_file_bytes */
4047
#include "foundation/mem_core.h"
4148
#include "graph_buffer/graph_buffer.h"
4249

50+
#include <ctype.h>
4351
#include <stdint.h>
4452
#include <stdio.h>
4553
#include <stdlib.h>
@@ -90,6 +98,7 @@ typedef struct {
9098
typedef struct {
9199
const char *project;
92100
size_t project_len;
101+
const char *repo; /* the repository root (NULL: unknown; no file is read) */
93102
const char **run_paths; /* run_file -> rel_path (NULL: not a Markdown file of this run) */
94103
int run_count;
95104
/* base name -> number of File nodes with it (a file name alone that is
@@ -287,6 +296,7 @@ static void *mdr_build(const cbm_doclink_build_in_t *in) {
287296
cbm_arena_init(&x->arena);
288297
x->project = in->ctx ? in->ctx->project_name : NULL;
289298
x->project_len = x->project ? strlen(x->project) : 0;
299+
x->repo = in->ctx ? in->ctx->repo_path : NULL;
290300
x->run_count = in->run_file_count;
291301
x->run_paths = in->run_file_count > 0
292302
? (const char **)cbm_calloc(CBM_MEM_CLASS_OTHER,
@@ -438,22 +448,39 @@ static bool mdr_code_label(const char *label) {
438448
return false;
439449
}
440450

451+
/* The length of the member text as a name: a call form (`name()`,
452+
* `Owner.name(a, b)`) ends before its first '('. */
453+
static size_t mdr_member_len(const char *member) {
454+
size_t n = strlen(member);
455+
if (n > 0 && member[n - SKIP_ONE] == ')') {
456+
const char *open = memchr(member, '(', n);
457+
if (open) {
458+
return (size_t)(open - member);
459+
}
460+
}
461+
return n;
462+
}
463+
441464
/* The member text's last segment (after "::" or "."), and the one before it. */
442465
static void mdr_member_names(const char *member, const char **name, size_t *name_len,
443466
const char **owner, size_t *owner_len) {
444467
const char *segs[PAIR_LEN] = {NULL, NULL};
445468
size_t lens[PAIR_LEN] = {0, 0};
446469
const char *s = member;
447-
while (*s) {
470+
const char *end = member + mdr_member_len(member);
471+
while (s < end) {
448472
size_t n = strcspn(s, ":.");
473+
if (n > (size_t)(end - s)) {
474+
n = (size_t)(end - s);
475+
}
449476
if (n > 0) {
450477
segs[0] = segs[SKIP_ONE];
451478
lens[0] = lens[SKIP_ONE];
452479
segs[SKIP_ONE] = s;
453480
lens[SKIP_ONE] = n;
454481
}
455482
s += n;
456-
while (*s == ':' || *s == '.') {
483+
while (s < end && (*s == ':' || *s == '.')) {
457484
s++;
458485
}
459486
}
@@ -499,12 +526,24 @@ static void mdr_file_defs(const mdr_index_t *x, const char *path, int *lo, int *
499526
*hi = e;
500527
}
501528

529+
/* How a member lookup ended: found, or why not. */
530+
typedef enum {
531+
MDR_MEMBER_FOUND = 0,
532+
MDR_MEMBER_MISSING, /* no definition of that name in the file */
533+
MDR_MEMBER_AMBIGUOUS, /* several, and the owner does not pick one */
534+
} mdr_member_t;
535+
502536
/* The code definition of file `path` that the range or the member names, or
503537
* NULL. Read from the index's definitions by file, never from DEFINES edges:
504538
* an incremental run's graph holds the edges of the files it re-extracts
505-
* only, while every node is there. */
539+
* only, while every node is there. *member_result (when not NULL) says how a
540+
* member lookup ended. */
506541
static const cbm_gbuf_node_t *mdr_segment(const mdr_index_t *x, const char *path, uint32_t first,
507-
uint32_t last, const char *member) {
542+
uint32_t last, const char *member,
543+
mdr_member_t *member_result) {
544+
if (member_result) {
545+
*member_result = MDR_MEMBER_FOUND;
546+
}
508547
int lo = 0;
509548
int hi = 0;
510549
mdr_file_defs(x, path, &lo, &hi);
@@ -537,6 +576,9 @@ static const cbm_gbuf_node_t *mdr_segment(const mdr_index_t *x, const char *path
537576
size_t owner_len;
538577
mdr_member_names(member, &name, &name_len, &owner, &owner_len);
539578
if (!name) {
579+
if (member_result) {
580+
*member_result = MDR_MEMBER_MISSING;
581+
}
540582
return NULL;
541583
}
542584
const cbm_gbuf_node_t *hit = NULL;
@@ -558,7 +600,70 @@ static const cbm_gbuf_node_t *mdr_segment(const mdr_index_t *x, const char *path
558600
if (owned_hits == SKIP_ONE) {
559601
return owned;
560602
}
561-
return owned_hits == 0 && hits == SKIP_ONE ? hit : NULL;
603+
if (owned_hits == 0 && hits == SKIP_ONE) {
604+
return hit;
605+
}
606+
if (member_result) {
607+
*member_result = hits == 0 ? MDR_MEMBER_MISSING : MDR_MEMBER_AMBIGUOUS;
608+
}
609+
return NULL;
610+
}
611+
612+
/* A byte of an identifier: a letter, a digit, '_', and every byte of a
613+
* multi-byte character (pipeline_incremental.c doc_row_ident_byte). */
614+
static bool mdr_ident_byte(unsigned char c) {
615+
return isalnum(c) || c == '_' || c >= CBM_SZ_128;
616+
}
617+
618+
/* Does text[0, n) hold name[0, len) as a whole identifier (case-sensitive)? */
619+
static bool mdr_writes_ident(const char *text, size_t n, const char *name, size_t len) {
620+
for (size_t i = 0; len > 0 && i + len <= n;) {
621+
const char *hit = memchr(text + i, name[0], n - len - i + SKIP_ONE);
622+
if (!hit) {
623+
return false;
624+
}
625+
size_t at = (size_t)(hit - text);
626+
if (memcmp(hit, name, len) == 0 && (at == 0 || !mdr_ident_byte((unsigned char)hit[-1])) &&
627+
(at + len == n || !mdr_ident_byte((unsigned char)hit[len]))) {
628+
return true;
629+
}
630+
i = at + SKIP_ONE;
631+
}
632+
return false;
633+
}
634+
635+
/* Does the code file `path` write the member's name at all? A name the graph
636+
* holds no definition for (a macro, a prototype, an enum member, a class
637+
* attribute) is still there when the file writes it. Read from the file,
638+
* never cached (resolvers run on worker threads). True -- no claim -- when
639+
* the file cannot be read whole: a member is missing only when the file was
640+
* read and does not write its name. */
641+
static bool mdr_file_writes(const mdr_index_t *x, const char *path, const char *member) {
642+
const char *name;
643+
const char *owner;
644+
size_t name_len;
645+
size_t owner_len;
646+
mdr_member_names(member, &name, &name_len, &owner, &owner_len);
647+
char abs_path[CBM_PATH_MAX];
648+
int w = name && x->repo ? snprintf(abs_path, sizeof(abs_path), "%s/%s", x->repo, path) : 0;
649+
if (w <= 0 || (size_t)w >= sizeof(abs_path)) {
650+
return true;
651+
}
652+
FILE *f = cbm_fopen(abs_path, "rb");
653+
if (!f) {
654+
return true;
655+
}
656+
long size = fseek(f, 0, SEEK_END) == 0 ? ftell(f) : CBM_NOT_FOUND;
657+
char *text = size >= 0 && size <= cbm_max_file_bytes() && fseek(f, 0, SEEK_SET) == 0
658+
? (char *)cbm_alloc(CBM_MEM_CLASS_OTHER, (size_t)size + SKIP_ONE)
659+
: NULL;
660+
bool writes = true;
661+
if (text && fread(text, SKIP_ONE, (size_t)size, f) == (size_t)size) {
662+
writes = mdr_writes_ident(text, (size_t)size, name, name_len);
663+
}
664+
(void)fclose(f);
665+
cbm_free(CBM_MEM_CLASS_OTHER, text);
666+
return writes;
562667
}
563668

564669
/* Is `path` of a file type the indexer reads? */
@@ -1183,9 +1288,24 @@ static void mdr_resolve_path(const mdr_index_t *x, const cbm_gbuf_t *graph, cons
11831288
out->kind = CBM_DOCLINK_LOCAL; /* a link into the same document */
11841289
return;
11851290
}
1186-
const cbm_gbuf_node_t *seg = (r->first > 0 || r->member)
1187-
? mdr_segment(x, t, r->first, r->last, r->member)
1188-
: NULL;
1291+
mdr_member_t member_result = MDR_MEMBER_FOUND;
1292+
const cbm_gbuf_node_t *seg =
1293+
(r->first > 0 || r->member)
1294+
? mdr_segment(x, t, r->first, r->last, r->member, &member_result)
1295+
: NULL;
1296+
/* A named member that a code file does not define is no coarser
1297+
* link to the file: it is a stale or unclear reference. One the
1298+
* file writes without a definition the graph binds (a macro, a
1299+
* prototype, an enum member) is there, and keeps the file edge.
1300+
* A document's own headings are not definitions, so members of
1301+
* other files keep the file edge too. */
1302+
if (!seg && r->member && member_result != MDR_MEMBER_FOUND && mdr_code_file(t) &&
1303+
(member_result == MDR_MEMBER_AMBIGUOUS || !mdr_file_writes(x, t, r->member))) {
1304+
out->kind = CBM_DOCLINK_UNRESOLVED;
1305+
out->reason = member_result == MDR_MEMBER_AMBIGUOUS ? CBM_DOCLINK_REASON_AMBIGUOUS
1306+
: CBM_DOCLINK_REASON_MISSING;
1307+
return;
1308+
}
11891309
mdr_edge(out, seg ? seg : file, r->first, r->last);
11901310
return;
11911311
}
@@ -1425,7 +1545,8 @@ static void mdr_resolve(const void *index, void *state, int run_file, const CBMD
14251545

14261546
const cbm_gbuf_node_t *cbm_doclink_md_segment(const void *md_index, const char *path,
14271547
uint32_t first, uint32_t last, const char *member) {
1428-
return md_index ? mdr_segment((const mdr_index_t *)md_index, path, first, last, member) : NULL;
1548+
return md_index ? mdr_segment((const mdr_index_t *)md_index, path, first, last, member, NULL)
1549+
: NULL;
14291550
}
14301551

14311552
/* ── A region of a file's text (the field test's H8 bind_range) ─────── */

‎src/pipeline/pipeline_incremental.c‎

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1582,7 +1582,12 @@ static int surface_added_names(const char *stored_json, const char *fresh_json,
15821582
* change to it is GLOBAL (it sets the global usings of a whole project);
15831583
* - a REMOVED name can make another file's unresolved reference resolve (an
15841584
* overload group shrinks) or change its reason: the files whose rows
1585-
* mention it re-resolve with the closure. */
1585+
* mention it re-resolve with the closure;
1586+
* - an unresolved `path::member` row (missing, ambiguous) depends on the
1587+
* member's file as a whole, its text included (a member the file writes
1588+
* without a definition is no missing member, doc_links_md.c) and the size
1589+
* of a same-named group: the files whose such rows name a changed or
1590+
* deleted file, by its base name, re-resolve with the closure. */
15861591

15871592
/* Add s[0..n) to a heap-keyed name set. false when it cannot be recorded (too
15881593
* long for a key, or out of memory): callers fail closed. */
@@ -1730,6 +1735,58 @@ static void doc_row_name_dependents(const cbm_doc_link_row_t *rows, int n,
17301735
}
17311736
}
17321737

1738+
/* Is an unresolved row's reason one a member lookup gives (doc_links_md.c)? */
1739+
static bool doc_row_member_reason(const char *reason) {
1740+
return reason && (strcmp(reason, "missing") == 0 || strcmp(reason, "ambiguous") == 0);
1741+
}
1742+
1743+
/* Files whose unresolved `path::member` rows name a member of one of `paths`
1744+
* (the changed and deleted files), and no edge leads from such a row to the
1745+
* file: a body edit can write or drop a missing member's name without
1746+
* changing a definition, and a same-named group can shrink to one without
1747+
* removing its name. Matched by the base name before "::", since a
1748+
* reference may be written relative to the document or to the root. When
1749+
* memory runs out every such row's file is added: re-resolving a file that did
1750+
* not need it costs time, keeping a stale row costs correctness. Keys are
1751+
* borrowed from `rows`. */
1752+
static void doc_row_member_dependents(const cbm_doc_link_row_t *rows, int n, char *const *paths,
1753+
int npaths, CBMHashTable *out_paths) {
1754+
if (npaths <= 0) {
1755+
return;
1756+
}
1757+
CBMHashTable *bases = cbm_ht_create(CBM_SZ_64); /* NULL: fail closed, every member row */
1758+
for (int i = 0; bases && i < npaths; i++) {
1759+
const char *slash = strrchr(paths[i], '/');
1760+
const char *base = slash ? slash + SKIP_ONE : paths[i];
1761+
cbm_ht_set(bases, base, (void *)base); /* borrowed from `paths` */
1762+
}
1763+
for (int i = 0; i < n; i++) {
1764+
const char *raw = rows[i].raw;
1765+
const char *rel = rows[i].rel_path;
1766+
const char *sep = raw ? strstr(raw, "::") : NULL;
1767+
if (!sep || !rel || !rel[0] || !doc_row_member_reason(rows[i].reason) ||
1768+
cbm_ht_get(out_paths, rel)) {
1769+
continue;
1770+
}
1771+
const char *base = sep;
1772+
while (base > raw && base[-1] != '/') {
1773+
base--;
1774+
}
1775+
char key[CBM_SZ_512];
1776+
size_t bl = (size_t)(sep - base);
1777+
bool hit = !bases || bl >= sizeof(key);
1778+
if (!hit && bl > 0) {
1779+
memcpy(key, base, bl);
1780+
key[bl] = '\0';
1781+
hit = cbm_ht_get(bases, key) != NULL;
1782+
}
1783+
if (hit) {
1784+
cbm_ht_set(out_paths, rel, (void *)rel);
1785+
}
1786+
}
1787+
cbm_ht_free(bases);
1788+
}
1789+
17331790
/* Doc-link carry-forward state of the legacy partial route: the previous
17341791
* rows, the stored scopes of the files it does not re-extract, and the set
17351792
* of re-extracted or deleted paths whose old rows it replaces. */
@@ -3178,8 +3235,11 @@ static int closure_try_plan(cbm_pipeline_t *p, cbm_store_t *store, const char *p
31783235
}
31793236
}
31803237
/* Files whose unresolved doc-link references name something a changed or
3181-
* deleted file no longer declares re-resolve too. */
3238+
* deleted file no longer declares re-resolve too, and so do the files
3239+
* whose unresolved `path::member` rows name a changed or deleted file. */
31823240
doc_row_name_dependents(plan->doc_rows, plan->doc_row_count, removed_names, row_deps);
3241+
doc_row_member_dependents(plan->doc_rows, plan->doc_row_count, changed_paths,
3242+
n_changed + n_deleted, row_deps);
31833243
{
31843244
row_dep_walk_t walk = {.closure = closure_set, .files = files_by_path, .added = 0};
31853245
cbm_ht_foreach(row_deps, row_dep_visitor, &walk);

0 commit comments

Comments
 (0)