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
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 {
9098typedef 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. */
442465static 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. */
506541static 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
14261546const 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) ─────── */
0 commit comments