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_jvm.c — Javadoc and KDoc reference resolution for doc_links.h.
*
* One index over the Java and the Kotlin files of a repository, built from
* their doc-link scopes (internal/cbm/doclink_jvm.c): on the JVM a package is
* one namespace whatever language declares into it, so a Kotlin import of a
* Java class and a Javadoc link to a Kotlin class must meet in one type table.
* The language of the SOURCE file decides the lookup order; where a target's
* node is comes from the target's own scope record (slot, own), never from a
* naming scheme assumed here. Graph nodes are looked up by qualified name
* only, and only their label and file path are read, so the closure-repair
* route (whose unchanged nodes are line-less proxies) resolves exactly as a
* full build does.
*
* Entities. A type entity is its binary-style name: package + '.' + the
* dotted logical path (com.acme.Outer.Inner). Several declarations of one
* name (source sets, expect/actual) are one entity. A member belongs to the
* declaration that holds it; overloads of one type share a node.
*
* Lookup (the first level with a visible candidate decides; more than one
* entity there is ambiguous, never a pick):
* Java type name (javac's order)
* the method's own type variables (local) -> the enclosing types,
* innermost first (the type and its member types, its type variables, the
* member types it inherits) -> the file's own top-level types and its
* single imports (a static import imports a member type too) -> the
* file's package -> on-demand imports, with java.lang among them.
* A qualified name: the head through those levels, the rest as member
* types; a head no level has is read from the root (packages, then a
* type). `Type.member` is no reference: Javadoc wants a '#'.
* Java METHOD, `#m` and `Type#m`: javadoc's own search (jr_walk, read in
* the JDK source), from the documented definition's type or the type
* named: the type's own methods -> its superclass, by the whole search
* (its superclass, its interfaces, the type around IT) -> its
* interfaces in the order written, likewise -> the type around it,
* likewise; each type once, the first method found. A type outside the
* repository on the way, or a method the language gives (Object's,
* Enum's, Annotation's, an enum's values/valueOf, a record's
* equals/hashCode/toString), ends it as `external`. Static imports are
* no step: javadoc does not search them for a member.
* Java FIELD, `#x` and `Type#x` without a parameter list: javadoc looks in
* the type, then the types around it, then the supertypes; an inherited
* field binds only when no type further out has one of that name, else
* it is ambiguous. ({@value Type#X}: the type and its supertypes.)
* Java kinds
* `#x` is the field when javadoc takes it over the method its search
* finds: the field's class is the method's class or below it, also for
* every type outside the repository the search passes (jr_java_field);
* else that method, when it is one of the repository with nothing
* unseen before it (javadoc links it), or external.
* A parameter list selects callables:
* the first type whose overloads have that signature, never another
* overload. A declared type variable matches its own name or its erasure.
* A method name without a list that has several signatures is ambiguous.
* A record's component declares an accessor of its name (no node).
* `#Type(..)` names the constructors of that type only. A bare
* identifier that is no type is javadoc's `#identifier`.
* Kotlin (the order KDoc resolves in)
* the definition's own parameters, type parameters and `this` (local) ->
* each enclosing type, innermost first: what it holds itself together
* with its companion (one scope), its type parameters and constructor
* parameters (local), then what it inherits and what its companion
* inherits -> explicit imports -> the file's package (types and top-level
* declarations) -> star imports -> default imports.
* A FUNCTION or PROPERTY found further out than an enclosing type binds
* only when that type is known not to have a member of the name: a type
* that has it from the language (kotlin.Any's members, an enum class's),
* or whose supertypes leave the repository, makes it `external`
* (jr_kotlin_simple). A type found further out binds.
* A dotted name: the qualifier is a type (through those levels, or from
* the root) and the last name what that type holds, inherits, or gets
* from an extension in scope whose receiver it is (an extension only
* where the type's supertypes all lie in the repository: a member comes
* before an extension); or the qualifier is a
* package and the last name one of its types or top-level declarations.
* Kotlin kinds
* a type and a function of one name at one level (a class and its factory
* function) are the type: KDoc resolves a classifier before a function
* (jr_kl_result). A type without a node of its own is then a graph gap,
* never the function. A property and a function of one name are
* ambiguous, and so is an overload group.
* A `[name]` that resolves to nothing is plain text to KDoc (Markdown):
* no reference at all. @see, @throws and @sample name their subject and
* keep a row.
* Visibility: product code never binds a declaration that only test code
* holds (test_only_target, no fallback to it); `@sample` is exempt.
* External: a name a single import brings from a package the repository does
* not declare; a qualified `pkg.Type` whose package it does not declare; a
* name only an on-demand import of such a package can supply; java.lang and
* the Kotlin default imports (the languages' own implicit imports, the only
* name lists here, and consulted after the repository's own declarations); an
* all-lower-case path under `java`, `javax` or `kotlin` (the platforms' own
* namespaces; no library family is one), or under a package the file imports
* from and the repository does not declare; a
* member that a supertype outside the repository may declare; the members
* every type has without declaring them (Object's, an enum's).
* Not indexed: a package below one the repository owns, in a directory the
* indexer skips by name (discovery's own rule, no file system access here).
* Graph gaps: a declaration without a definition (slot '-'), one whose
* qualified name another declaration took (own 0), a node of another kind or
* file, a package (it has no node), a member a parse error hides, a name the
* scan could not place, a definition in a part of its file it could not
* place -- and a reference that resolves, written on a definition that has
* no node of its own to leave from.
*/
#include "pipeline/doc_links.h"
#include "doclink.h"
#include "helpers.h" /* cbm_fqn_module_source_lang */
#include "discover/discover.h" /* cbm_should_skip_dir */
#include "foundation/arena.h"
#include "foundation/constants.h"
#include "foundation/hash_table.h"
#include "foundation/log.h"
#include "foundation/mem_core.h"
#include <ctype.h>
#include <stdatomic.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
enum {
JR_KEY_BUF = 2048,
JR_MAX_SEGS = 32, /* dotted segments of one reference; more is unparseable */
JR_MAX_PARAMS = 32, /* written parameters of one reference; more is unparseable */
JR_PARAM_BUF = 160,
JR_T_FIELDS = 10,
JR_M_FIELDS = 12,
JR_NONE = -1,
};
/* ── Index data ──────────────────────────────────────────────────── */
typedef struct {
char kind; /* s single, w on-demand, m static single, n static on-demand */
const char *alias;
const char *target;
} jr_import_t;
typedef struct {
uint32_t from;
uint32_t to;
} jr_lines_t;
/* Line numbers are meaningful only in a file re-extracted by this run: the
* persisted scope of every other file carries zeros. They are read for the
* SOURCE file's own context, never for a target. */
typedef struct {
uint32_t start;
uint32_t end;
char kind; /* c i e r a o C t */
bool incomplete;
bool own; /* its definition is the one the graph keeps for the slot */
const char *path; /* logical path */
const char *name;
const char *tparams;
const char *supers;
const char
*slot; /* NULL: no definition; "=": the logical path; else the name below the module */
const char *pnames; /* run files only */
int outer; /* the enclosing type of this file, or JR_NONE */
int entity;
} jr_type_t;
typedef struct {
uint32_t start;
char kind; /* c callable, v value */
bool ctor; /* K */
bool component; /* p: a record component or constructor property */
bool own;
int owner; /* its type in this file; JR_NONE: a Kotlin top-level declaration */
int order; /* position in the scope */
int shares; /* the member of this file whose node it shares; JR_NONE: it has none */
int recv_entity; /* a Kotlin extension's receiver type, when the repository declares it */
const char *name;
const char *tparams;
const char *sig;
const char *recv;
const char *slot;
const char *pnames;
} jr_member_t;
typedef struct {
const char *rel_path;
const char *module_qn;
const char *package;
bool kotlin;
bool is_test;
bool scoped; /* its scope was read: without one nothing in it resolves */
jr_import_t *imports; /* single imports, sorted by alias then target */
int nimports;
jr_import_t *wild; /* on-demand imports, scope order */
int nwild;
jr_type_t *types; /* scope order: an outer type before its nested ones */
int ntypes;
jr_member_t *members; /* sorted by (owner, name, order) */
int nmembers;
int *by_start; /* member indices sorted by (start, order) */
jr_lines_t *unplaced;
int nunplaced;
} jr_file_t;
typedef struct {
int file;
int type;
} jr_decl_t;
/* A step of javadoc's search for a method (jr_walk) that is no type of the
* repository. */
enum {
JR_W_NONE = JR_NONE, /* no step: an interface has no superclass */
JR_W_OBJECT = -2, /* java.lang.Object */
JR_W_ENUM = -3, /* java.lang.Enum, then Object */
JR_W_ANNOTATION = -4, /* java.lang.annotation.Annotation */
JR_W_OUTSIDE = -5, /* a type outside the repository, or a step whose place
in the order the index cannot tell */
};
typedef struct {
const char *fqn;
const char *name;
char kind;
jr_decl_t *decls; /* sorted by file (path order), then scope order */
int ndecls;
int dcap;
int *bases; /* the supertypes its declarations name, as far as the repository declares them */
int nbases;
int *closure; /* every supertype the repository declares, nearest first */
int nclosure;
int companion; /* Kotlin: its companion object, or JR_NONE */
bool open; /* a supertype outside the repository, or one that could not be bound */
bool incomplete; /* a declaration of it has members a parse error hides */
bool any_prod;
/* javadoc's search for a method at this type (jr_walk): the superclass
* step (a type, or JR_W_*), the interface steps in the order written,
* and the type around it */
int wsuper;
int *wifaces;
int nwifaces;
int encl;
} jr_entity_t;
typedef struct {
int *items;
int count;
int cap;
} jr_ilist_t;
/* What the resolve phase counts for the run's log line. The index itself is
* read-only then; these are the only words it writes. */
typedef struct {
_Atomic int64_t source_gaps; /* resolved, but the documented definition has no node */
_Atomic int64_t plain_text; /* KDoc `[name]` that names nothing: plain text */
_Atomic int64_t type_and_function; /* KDoc name that is a type and a function at one
* level: resolved as the type */
_Atomic int64_t type_and_function_node; /* ... where the type has a node (an edge) */
/* Members further on that a lookup did not take, because something
* before them may have the member unseen (javadoc's search, jr_walk; the
* guards of jr_kotlin_simple and jr_kotlin_in_type): `external`. */
_Atomic int64_t java_given; /* Javadoc method: the language gives one first */
_Atomic int64_t java_open; /* ... or a type outside the repository comes first */
_Atomic int64_t kotlin_given; /* KDoc name: the same two cases */
_Atomic int64_t kotlin_open;
_Atomic int64_t kotlin_extension; /* KDoc `Type.name`: an extension, the type's
* hierarchy leaving the repository */
/* Javadoc fields not taken, because a method that javadoc's search may
* reach first, outside the repository, may be what it links
* (jr_java_field). */
_Atomic int64_t java_field; /* `#x` */
_Atomic int64_t java_field_named; /* `Type#x` */
} jr_stats_t;
typedef struct {
CBMArena arena;
bool oom;
jr_stats_t *stats;
int mode; /* the run's index mode: which directories discovery skips */
const char *project;
jr_file_t *files;
int nfiles;
int *run_to_file;
int run_count;
jr_entity_t *ents;
int nents;
int ecap;
CBMHashTable *ent_by_fqn; /* fqn -> entity + 1 */
CBMHashTable *pkg_types; /* "package\x1f name" -> entity + 1 (top-level types) */
CBMHashTable *packages; /* every package a file declares */
CBMHashTable *pkg_prefixes; /* ... and every prefix of one */
CBMHashTable *pkg_members; /* "package\x1f name" -> jr_ilist_t* of files (Kotlin top level) */
CBMHashTable *extensions; /* "<entity>\x1f name" -> jr_ilist_t* of (file, member) pairs */
CBMHashTable *quarantine; /* names of types declared where no scope is known */
CBMHashTable *quarantine_test; /* the same, declared by test code only */
} jr_index_t;
/* ── Small helpers ───────────────────────────────────────────────── */
/* Index memory. A failed allocation is remembered: whatever a caller does
* with its NULL, the build as a whole reports failure instead of handing out
* an index that silently lacks a declaration. */
static void *jr_alloc(jr_index_t *ix, size_t n) {
void *p = cbm_arena_alloc(&ix->arena, n ? n : SKIP_ONE);
ix->oom = ix->oom || !p;
return p;
}
static char *jr_strdup(jr_index_t *ix, const char *s) {
char *p = cbm_arena_strdup(&ix->arena, s ? s : "");
ix->oom = ix->oom || !p;
return p;
}
static bool jr_ilist_push(jr_index_t *ix, jr_ilist_t *l, int v) {
if (l->count >= l->cap) {
int ncap = l->cap ? l->cap * PAIR_LEN : CBM_SZ_4;
int *grown = (int *)jr_alloc(ix, (size_t)ncap * sizeof(int));
if (!grown) {
return false;
}
if (l->count > 0) {
memcpy(grown, l->items, (size_t)l->count * sizeof(int));
}
l->items = grown;
l->cap = ncap;
}
l->items[l->count++] = v;
return true;
}
static jr_ilist_t *jr_ht_ilist(jr_index_t *ix, CBMHashTable *ht, const char *key, bool create) {
jr_ilist_t *l = (jr_ilist_t *)cbm_ht_get(ht, key);
if (l || !create) {
return l;
}
l = (jr_ilist_t *)jr_alloc(ix, sizeof(*l));
char *k = jr_strdup(ix, key);
if (!l || !k) {
return NULL;
}
memset(l, 0, sizeof(*l));
cbm_ht_set(ht, k, l);
return l;
}
/* Add `key` to a name set; false when memory ran out. */
static bool jr_mark(jr_index_t *ix, CBMHashTable *ht, const char *key) {
if (cbm_ht_get(ht, key)) {
return true;
}
char *k = jr_strdup(ix, key);
if (!k) {
return false;
}
cbm_ht_set(ht, k, (void *)k);
return true;
}
static bool jr_ci_equal(const char *s, size_t n, const char *word) {
if (strlen(word) != n) {
return false;
}
for (size_t i = 0; i < n; i++) {
if (tolower((unsigned char)s[i]) != word[i]) {
return false;
}
}
return true;
}
static bool jr_ci_contains(const char *s, size_t n, const char *word) {
size_t wl = strlen(word);
for (size_t i = 0; i + wl <= n; i++) {
size_t k = 0;
while (k < wl && tolower((unsigned char)s[i + k]) == word[k]) {
k++;
}
if (k == wl) {
return true;
}
}
return false;
}
/* True when one word of the directory name s[0, n) says test code: the name
* is split at '-', '_', '.' and at a lower-to-upper case step (`commonTest`,
* `json-tests`, `testFixtures`, `smoke-test-http`), and a word is compared
* whole, so `latest` and `attestation` say nothing. */
static bool jr_test_dir_name(const char *s, size_t n) {
static const char *const words[] = {"test", "tests", "fixture", "fixtures",
"sample", "samples", "example", "examples"};
size_t start = 0;
for (size_t i = 0; i <= n; i++) {
bool sep = i == n || s[i] == '-' || s[i] == '_' || s[i] == '.';
bool step = !sep && i > start && isupper((unsigned char)s[i]) &&
!isupper((unsigned char)s[i - SKIP_ONE]);
if (!sep && !step) {
continue;
}
for (size_t w = 0; w < sizeof(words) / sizeof(words[0]); w++) {
if (jr_ci_equal(s + start, i - start, words[w])) {
return true;
}
}
start = sep ? i + SKIP_ONE : i;
}
return false;
}
/* Test code, by where a build puts it:
* - the source set after the last `src` directory holds "test" (`src/test`,
* `src/jvmTest`, `src/testFixtures`, `src/internalClusterTest`), or
* - a directory above that source root (any directory, when there is no
* `src`) has a word test, fixture, sample or example in its name: a test
* project, a `commonTest/src` source set, a samples tree.
* Directories below a source set are packages: `src/main/java/org/acme/test/
* Tool.java` is product code. A file name decides nothing. */
static bool jr_is_test_path(const char *rel) {
const char *src_set = NULL; /* the segment after the last `src` directory */
size_t src_set_len = 0;
const char *last_src = NULL;
for (const char *p = rel;;) {
const char *slash = strchr(p, '/');
if (!slash) {
break;
}
if (slash - p == 3 && memcmp(p, "src", 3) == 0) {
const char *next = slash + SKIP_ONE;
const char *end = strchr(next, '/');
last_src = p;
src_set = end ? next : NULL; /* a file right under src is no source set */
src_set_len = end ? (size_t)(end - next) : 0;
}
p = slash + SKIP_ONE;
}
if (src_set && jr_ci_contains(src_set, src_set_len, "test")) {
return true;
}
for (const char *p = rel; !last_src || p < last_src;) {
const char *slash = strchr(p, '/');
if (!slash) {
break;
}
if (jr_test_dir_name(p, (size_t)(slash - p))) {
return true;
}
p = slash + SKIP_ONE;
}
return false;
}
/* Split `s` in place at tabs into at most `max` fields; returns the count. */
static int jr_split(char *s, char **out, int max) {
int n = 0;
out[n++] = s;
for (char *p = s; *p && n < max; p++) {
if (*p == '\t') {
*p = '\0';
out[n++] = p + SKIP_ONE;
}
}
return n;
}
/* True when name[0, nl) is one of the ','-joined names of `list`. An entry may
* carry a bound (`T:Comparable`, a Java type variable's): *bound / *blen are
* set to it (length 0 when it has none). */
static bool jr_listed_n(const char *list, const char *name, size_t nl, const char **bound,
size_t *blen) {
for (const char *p = list; p && *p;) {
const char *e = strchr(p, ',');
size_t n = e ? (size_t)(e - p) : strlen(p);
const char *colon = (const char *)memchr(p, ':', n);
size_t name_len = colon ? (size_t)(colon - p) : n;
if (name_len == nl && memcmp(p, name, nl) == 0) {
if (bound) {
*bound = colon ? colon + SKIP_ONE : p + n;
*blen = colon ? n - name_len - SKIP_ONE : 0;
}
return true;
}
p = e ? e + SKIP_ONE : NULL;
}
return false;
}
static bool jr_listed(const char *list, const char *name) {
return jr_listed_n(list, name, strlen(name), NULL, NULL);
}
/* ── Scope parsing ───────────────────────────────────────────────── */
static int jr_import_cmp(const void *a, const void *b) {
const jr_import_t *x = (const jr_import_t *)a;
const jr_import_t *y = (const jr_import_t *)b;
int c = strcmp(x->alias, y->alias);
return c ? c : strcmp(x->target, y->target);
}
static int jr_member_cmp(const void *a, const void *b) {
const jr_member_t *x = (const jr_member_t *)a;
const jr_member_t *y = (const jr_member_t *)b;
if (x->owner != y->owner) {
return x->owner < y->owner ? -1 : 1;
}
int c = strcmp(x->name, y->name);
if (c) {
return c;
}
return (x->order > y->order) - (x->order < y->order);
}
typedef struct {
uint32_t start;
int order;
int idx;
} jr_start_key_t;
static int jr_start_cmp(const void *a, const void *b) {
const jr_start_key_t *x = (const jr_start_key_t *)a;
const jr_start_key_t *y = (const jr_start_key_t *)b;
if (x->start != y->start) {
return x->start < y->start ? -1 : 1;
}
return (x->order > y->order) - (x->order < y->order);
}
static int jr_lines_cmp(const void *a, const void *b) {
const jr_lines_t *x = (const jr_lines_t *)a;
const jr_lines_t *y = (const jr_lines_t *)b;
if (x->from != y->from) {
return x->from < y->from ? -1 : 1;
}
return (x->to > y->to) - (x->to < y->to);
}
static void jr_parse_type(jr_file_t *f, char **fld, int *stack, int *sp) {
jr_type_t *t = &f->types[f->ntypes];
memset(t, 0, sizeof(*t));
t->start = (uint32_t)strtoul(fld[1], NULL, 10);
t->end = (uint32_t)strtoul(fld[2], NULL, 10);
t->kind = fld[3][0];
t->incomplete = fld[3][0] && fld[3][1] == '!';
t->path = fld[4];
const char *dot = strrchr(t->path, '.');
t->name = dot ? dot + SKIP_ONE : t->path;
t->tparams = fld[5];
t->supers = fld[6];
t->slot = strcmp(fld[7], "-") == 0 ? NULL : fld[7];
t->own = fld[8][0] == '1';
t->pnames = fld[9];
t->entity = JR_NONE;
/* the enclosing type: the nearest earlier type whose path is this path
* without its last name (a nested type follows its outer type) */
size_t outer_len = dot ? (size_t)(dot - t->path) : 0;
while (*sp > 0) {
const char *op = f->types[stack[*sp - SKIP_ONE]].path;
if (dot && strlen(op) == outer_len && memcmp(op, t->path, outer_len) == 0) {
break;
}
(*sp)--;
}
t->outer = (dot && *sp > 0) ? stack[*sp - SKIP_ONE] : JR_NONE;
stack[(*sp)++] = f->ntypes;
f->ntypes++;
}
static bool jr_parse_member(jr_file_t *f, char **fld) {
jr_member_t *m = &f->members[f->nmembers];
memset(m, 0, sizeof(*m));
m->start = (uint32_t)strtoul(fld[1], NULL, 10);
m->kind = fld[2][0];
m->ctor = strchr(fld[3], 'K') != NULL;
m->component = strchr(fld[3], 'p') != NULL;
m->owner = strcmp(fld[4], "-") == 0 ? JR_NONE : atoi(fld[4]);
if (m->owner >= f->ntypes || (m->owner < 0 && m->owner != JR_NONE) || !fld[5][0] ||
(m->kind != 'c' && m->kind != 'v')) {
return false; /* not a record this code wrote */
}
m->name = fld[5];
m->tparams = fld[6];
m->sig = fld[7];
m->recv = fld[8];
m->slot = strcmp(fld[9], "-") == 0 ? NULL : fld[9];
m->own = fld[10][0] == '1';
m->pnames = fld[11];
m->order = f->nmembers;
m->shares = JR_NONE;
m->recv_entity = JR_NONE;
f->nmembers++;
return true;
}
/* Which member's node each member shares. A value has its own or none.
* Callables of one name in one type (overloads) share the node of the one
* that owns their slot. */
static void jr_link_shared_nodes(jr_file_t *f) {
for (int i = 0; i < f->nmembers;) {
int j = i;
int owner = JR_NONE; /* the callable of this run that owns the node */
while (j < f->nmembers && f->members[j].owner == f->members[i].owner &&
strcmp(f->members[j].name, f->members[i].name) == 0) {
jr_member_t *m = &f->members[j];
if (m->kind == 'c' && m->slot && m->own) {
owner = j;
}
j++;
}
for (int k = i; k < j; k++) {
jr_member_t *m = &f->members[k];
if (!m->slot) {
continue;
}
if (m->own) {
m->shares = k;
} else if (m->kind == 'c' && owner != JR_NONE &&
strcmp(f->members[owner].slot, m->slot) == 0 &&
f->members[owner].ctor == m->ctor) {
m->shares = owner;
}
}
i = j;
}
}
/* Parse one file's scope. false when it is not a scope this code wrote, or
* memory ran out. */
static bool jr_parse_scope(jr_index_t *ix, jr_file_t *f, const char *blob) {
char *buf = jr_strdup(ix, blob);
if (!buf) {
return false;
}
int ni = 0;
int nt = 0;
int nm = 0;
int nx = 0;
for (const char *p = buf; *p;) {
ni += *p == 'I';
nt += *p == 'T';
nm += *p == 'M';
nx += *p == 'X';
const char *nl = strchr(p, '\n');
if (!nl) {
break;
}
p = nl + SKIP_ONE;
}
f->imports = (jr_import_t *)jr_alloc(ix, (size_t)ni * sizeof(jr_import_t));
f->wild = (jr_import_t *)jr_alloc(ix, (size_t)ni * sizeof(jr_import_t));
f->types = (jr_type_t *)jr_alloc(ix, (size_t)nt * sizeof(jr_type_t));
f->members = (jr_member_t *)jr_alloc(ix, (size_t)nm * sizeof(jr_member_t));
f->unplaced = (jr_lines_t *)jr_alloc(ix, (size_t)nx * sizeof(jr_lines_t));
int *stack = (int *)cbm_alloc(CBM_MEM_CLASS_OTHER, (size_t)(nt + SKIP_ONE) * sizeof(int));
if (!f->imports || !f->wild || !f->types || !f->members || !f->unplaced || !stack) {
cbm_free(CBM_MEM_CLASS_OTHER, stack);
ix->oom = true;
return false;
}
int sp = 0;
bool first = true;
bool ok = true;
for (char *line = buf; ok && line && *line;) {
char *nl = strchr(line, '\n');
if (nl) {
*nl = '\0';
}
char *fld[JR_M_FIELDS];
if (first) {
first = false;
ok = strcmp(line, CBM_DOCLINK_JVM_SCOPE_TAG) == 0;
} else if (line[0] == 'L') {
f->kotlin = jr_split(line, fld, PAIR_LEN) == PAIR_LEN && fld[1][0] == 'k';
} else if (line[0] == 'P') {
if (jr_split(line, fld, PAIR_LEN) == PAIR_LEN) {
f->package = fld[1];
}
} else if (line[0] == 'I') {
if (jr_split(line, fld, CBM_SZ_4) == CBM_SZ_4 && fld[1][0] && fld[3][0]) {
jr_import_t imp = {.kind = fld[1][0], .alias = fld[2], .target = fld[3]};
if (imp.kind == 'w' || imp.kind == 'n') {
f->wild[f->nwild++] = imp;
} else {
f->imports[f->nimports++] = imp;
}
}
} else if (line[0] == 'T') {
/* a member names its type by position: a type record that cannot
* be read spoils the whole scope */
ok = jr_split(line, fld, JR_T_FIELDS) == JR_T_FIELDS && fld[4][0];
if (ok) {
jr_parse_type(f, fld, stack, &sp);
}
} else if (line[0] == 'M') {
ok = jr_split(line, fld, JR_M_FIELDS) == JR_M_FIELDS && jr_parse_member(f, fld);
} else if (line[0] == 'X') {
if (jr_split(line, fld, 3) == 3) {
f->unplaced[f->nunplaced++] =
(jr_lines_t){.from = (uint32_t)strtoul(fld[1], NULL, 10),
.to = (uint32_t)strtoul(fld[2], NULL, 10)};
}
} else if (line[0] == 'Q') {
if (jr_split(line, fld, PAIR_LEN) == PAIR_LEN && fld[1][0]) {
ok = jr_mark(ix, f->is_test ? ix->quarantine_test : ix->quarantine, fld[1]);
}
}
line = nl ? nl + SKIP_ONE : NULL;
}
cbm_free(CBM_MEM_CLASS_OTHER, stack);
if (!ok || first) {
return false;
}
if (f->nimports > 1) {
qsort(f->imports, (size_t)f->nimports, sizeof(jr_import_t), jr_import_cmp);
}
if (f->nmembers > 1) {
qsort(f->members, (size_t)f->nmembers, sizeof(jr_member_t), jr_member_cmp);
}
jr_link_shared_nodes(f);
/* the unplaced line ranges: sorted and disjoint, for a binary search */
if (f->nunplaced > 1) {
qsort(f->unplaced, (size_t)f->nunplaced, sizeof(jr_lines_t), jr_lines_cmp);
int w = 0;
for (int i = SKIP_ONE; i < f->nunplaced; i++) {
if (f->unplaced[i].from <= f->unplaced[w].to) {
if (f->unplaced[i].to > f->unplaced[w].to) {
f->unplaced[w].to = f->unplaced[i].to;
}
} else {
f->unplaced[++w] = f->unplaced[i];
}
}
f->nunplaced = w + SKIP_ONE;
}
f->by_start = (int *)jr_alloc(ix, (size_t)f->nmembers * sizeof(int));
jr_start_key_t *keys =
f->nmembers > 0
? (jr_start_key_t *)cbm_alloc(CBM_MEM_CLASS_OTHER, (size_t)f->nmembers * sizeof(*keys))
: NULL;
if (f->nmembers > 0 && (!f->by_start || !keys)) {
cbm_free(CBM_MEM_CLASS_OTHER, keys);
ix->oom = true;
return false;
}
for (int i = 0; i < f->nmembers; i++) {
keys[i] =
(jr_start_key_t){.start = f->members[i].start, .order = f->members[i].order, .idx = i};
}
if (f->nmembers > 1) {
qsort(keys, (size_t)f->nmembers, sizeof(*keys), jr_start_cmp);
}
for (int i = 0; i < f->nmembers; i++) {
f->by_start[i] = keys[i].idx;
}
cbm_free(CBM_MEM_CLASS_OTHER, keys);
return true;
}
/* ── Entities ────────────────────────────────────────────────────── */
enum { JR_ENT_FAIL = -1, JR_ENT_SKIP = -2 };
/* "package.path", or "path" in the default package. false when it does not
* fit (a name longer than any real one). */
static bool jr_fqn(const char *package, const char *path, char *out, size_t cap) {
int n = (package && package[0]) ? snprintf(out, cap, "%s.%s", package, path)
: snprintf(out, cap, "%s", path);
return n >= 0 && (size_t)n < cap;
}
static bool jr_pair_key(const char *a, const char *b, char *out, size_t cap) {
int n = snprintf(out, cap, "%s\x1f%s", a ? a : "", b);
return n >= 0 && (size_t)n < cap;
}
static int jr_ent(const jr_index_t *ix, const char *fqn) {
intptr_t v = (intptr_t)cbm_ht_get(ix->ent_by_fqn, fqn);
return v > 0 ? (int)(v - SKIP_ONE) : JR_NONE;
}
/* The entity `fqn`, created on first sight. */
static int jr_entity_get(jr_index_t *ix, const char *fqn, const char *name, char kind) {
int found = jr_ent(ix, fqn);
if (found != JR_NONE) {
return found;
}
if (ix->nents >= ix->ecap) {
int ncap = ix->ecap ? ix->ecap * PAIR_LEN : CBM_SZ_1K;
jr_entity_t *grown =
(jr_entity_t *)cbm_alloc(CBM_MEM_CLASS_OTHER, (size_t)ncap * sizeof(jr_entity_t));
if (!grown) {
return JR_ENT_FAIL;
}
if (ix->nents > 0) {
memcpy(grown, ix->ents, (size_t)ix->nents * sizeof(jr_entity_t));
}
cbm_free(CBM_MEM_CLASS_OTHER, ix->ents);
ix->ents = grown;
ix->ecap = ncap;
}
int id = ix->nents;
jr_entity_t *e = &ix->ents[id];
memset(e, 0, sizeof(*e));
e->fqn = jr_strdup(ix, fqn);
e->name = name;
e->kind = kind;
e->companion = JR_NONE;
e->wsuper = JR_W_OUTSIDE; /* until jr_resolve_supers has read its declarations */
e->encl = JR_NONE;
if (!e->fqn) {
return JR_ENT_FAIL;
}
ix->nents++;
cbm_ht_set(ix->ent_by_fqn, e->fqn, (void *)(intptr_t)(id + SKIP_ONE));
return id;
}
static bool jr_entity_add_decl(jr_index_t *ix, jr_entity_t *e, int file, int type) {
if (e->ndecls >= e->dcap) {
int ncap = e->dcap ? e->dcap * PAIR_LEN : CBM_SZ_2;
jr_decl_t *grown = (jr_decl_t *)jr_alloc(ix, (size_t)ncap * sizeof(jr_decl_t));
if (!grown) {
return false;
}
if (e->ndecls > 0) {
memcpy(grown, e->decls, (size_t)e->ndecls * sizeof(jr_decl_t));
}
e->decls = grown;
e->dcap = ncap;
}
e->decls[e->ndecls++] = (jr_decl_t){.file = file, .type = type};
e->any_prod = e->any_prod || !ix->files[file].is_test;
e->incomplete = e->incomplete || ix->files[file].types[type].incomplete;
return true;
}
static bool jr_mark_package(jr_index_t *ix, const char *package) {
if (!package || !package[0]) {
return true;
}
if (!jr_mark(ix, ix->packages, package)) {
return false;
}
char buf[JR_KEY_BUF];
if (snprintf(buf, sizeof(buf), "%s", package) >= (int)sizeof(buf)) {
return true;
}
for (char *dot = strrchr(buf, '.'); dot; dot = strrchr(buf, '.')) {
*dot = '\0';
if (!jr_mark(ix, ix->pkg_prefixes, buf)) {
return false;
}
}
return true;
}
/* The entities of every declared type and the package tables. Files come in
* path order and types in scope order, so every declaration list is in that
* order too. *skipped counts declarations whose name is too long to index;
* their names are quarantined, so a reference to one binds nothing else. */
static bool jr_build_entities(jr_index_t *ix, int *skipped) {
for (int fi = 0; fi < ix->nfiles; fi++) {
jr_file_t *f = &ix->files[fi];
if (!jr_mark_package(ix, f->package)) {
return false;
}
for (int ti = 0; ti < f->ntypes; ti++) {
jr_type_t *t = &f->types[ti];
char fqn[JR_KEY_BUF];
char key[JR_KEY_BUF];
int id = jr_fqn(f->package, t->path, fqn, sizeof(fqn)) &&
jr_pair_key(f->package, t->name, key, sizeof(key))
? jr_entity_get(ix, fqn, t->name, t->kind)
: JR_ENT_SKIP;
if (id == JR_ENT_SKIP) {
(*skipped)++;
if (!jr_mark(ix, f->is_test ? ix->quarantine_test : ix->quarantine, t->name)) {
return false;
}
continue;
}
if (id < 0 || !jr_entity_add_decl(ix, &ix->ents[id], fi, ti)) {
return false;
}
t->entity = id;
if (t->kind == 'C' && t->outer != JR_NONE && f->types[t->outer].entity >= 0) {
ix->ents[f->types[t->outer].entity].companion = id;
}
if (t->outer == JR_NONE && !cbm_ht_get(ix->pkg_types, key)) {
char *k = jr_strdup(ix, key);
if (!k) {
return false;
}
cbm_ht_set(ix->pkg_types, k, (void *)(intptr_t)(id + SKIP_ONE));
}
}
/* Kotlin top-level declarations: the files of a package that declare
* a name (each file once: its members of one name are one run) */
for (int mi = 0; mi < f->nmembers && f->members[mi].owner == JR_NONE; mi++) {
const jr_member_t *m = &f->members[mi];
if (mi > 0 && strcmp(f->members[mi - SKIP_ONE].name, m->name) == 0) {
continue;
}
char key[JR_KEY_BUF];
if (!jr_pair_key(f->package, m->name, key, sizeof(key))) {
continue;
}
jr_ilist_t *l = jr_ht_ilist(ix, ix->pkg_members, key, true);
if (!l || !jr_ilist_push(ix, l, fi)) {
return false;
}
}
}
return true;
}
/* ── The languages' own implicit imports ─────────────────────────────
*
* java.lang (Java and Kotlin/JVM) and the Kotlin default imports are part of
* the lookup order of every file. They are consulted last, after everything
* the repository declares, and only say "this simple name is the language's":
* external. Nothing else here is a list of names. */
static const char *const JR_JAVA_LANG[] = {
"AbstractMethodError",
"Appendable",
"ArithmeticException",
"ArrayIndexOutOfBoundsException",
"ArrayStoreException",
"AssertionError",
"AutoCloseable",
"Boolean",
"BootstrapMethodError",
"Byte",
"CharSequence",
"Character",
"Class",
"ClassCastException",
"ClassCircularityError",
"ClassFormatError",
"ClassLoader",
"ClassNotFoundException",
"ClassValue",
"CloneNotSupportedException",
"Cloneable",
"Comparable",
"Compiler",
"Deprecated",
"Double",
"Enum",
"EnumConstantNotPresentException",
"Error",
"Exception",
"ExceptionInInitializerError",
"Float",
"FunctionalInterface",
"IllegalAccessError",
"IllegalAccessException",
"IllegalArgumentException",
"IllegalCallerException",
"IllegalMonitorStateException",
"IllegalStateException",
"IllegalThreadStateException",
"IncompatibleClassChangeError",
"IndexOutOfBoundsException",
"InheritableThreadLocal",
"InstantiationError",
"InstantiationException",
"Integer",
"InternalError",
"InterruptedException",
"Iterable",
"LayerInstantiationException",
"LinkageError",
"Long",
"MatchException",
"Math",
"Module",
"ModuleLayer",
"NegativeArraySizeException",
"NoClassDefFoundError",
"NoSuchFieldError",
"NoSuchFieldException",
"NoSuchMethodError",
"NoSuchMethodException",
"NullPointerException",
"Number",
"NumberFormatException",
"Object",
"OutOfMemoryError",
"Override",
"Package",
"Process",
"ProcessBuilder",
"ProcessHandle",
"Readable",
"Record",
"ReflectiveOperationException",
"Runnable",
"Runtime",
"RuntimeException",
"RuntimePermission",
"SafeVarargs",
"ScopedValue",
"SecurityException",
"SecurityManager",
"Short",
"StackOverflowError",
"StackTraceElement",
"StackWalker",
"StrictMath",
"String",
"StringBuffer",
"StringBuilder",
"StringIndexOutOfBoundsException",
"StringTemplate",
"SuppressWarnings",
"System",
"Thread",
"ThreadDeath",
"ThreadGroup",
"ThreadLocal",
"Throwable",
"TypeNotPresentException",
"UnknownError",
"UnsatisfiedLinkError",
"UnsupportedClassVersionError",
"UnsupportedOperationException",
"VerifyError",
"VirtualMachineError",
"Void",
"WrongThreadException",
};
/* kotlin.*, kotlin.annotation.*, kotlin.collections.*, kotlin.comparisons.*,
* kotlin.io.*, kotlin.ranges.*, kotlin.sequences.*, kotlin.text.* and
* kotlin.jvm.*: their types and the standard scope functions. */
static const char *const JR_KOTLIN_DEFAULT[] = {
"AbstractCollection",
"AbstractIterator",
"AbstractList",
"AbstractMap",
"AbstractMutableCollection",
"AbstractMutableList",
"AbstractMutableMap",
"AbstractMutableSet",
"AbstractSet",
"Annotation",
"AnnotationRetention",
"AnnotationTarget",
"Any",
"Array",
"ArrayDeque",
"ArrayList",
"Boolean",
"BooleanArray",
"BuilderInference",
"Byte",
"ByteArray",
"Char",
"CharArray",
"CharCategory",
"CharProgression",
"CharRange",
"CharSequence",
"Charsets",
"ClosedFloatingPointRange",
"ClosedRange",
"Collection",
"Comparable",
"Comparator",
"ConcurrentModificationException",
"DeepRecursiveFunction",
"Deprecated",
"DeprecationLevel",
"Double",
"DoubleArray",
"DslMarker",
"Enum",
"Float",
"FloatArray",
"Function",
"Grouping",
"HashMap",
"HashSet",
"IndexedValue",
"Int",
"IntArray",
"IntProgression",
"IntRange",
"Iterable",
"Iterator",
"JvmField",
"JvmInline",
"JvmName",
"JvmOverloads",
"JvmRecord",
"JvmStatic",
"JvmSuppressWildcards",
"JvmSynthetic",
"JvmWildcard",
"KotlinVersion",
"Lazy",
"LazyThreadSafetyMode",
"LinkedHashMap",
"LinkedHashSet",
"List",
"ListIterator",
"Long",
"LongArray",
"LongProgression",
"LongRange",
"Map",
"MatchGroup",
"MatchGroupCollection",
"MatchResult",
"Metadata",
"MustBeDocumented",
"MutableCollection",
"MutableIterable",
"MutableIterator",
"MutableList",
"MutableListIterator",
"MutableMap",
"MutableSet",
"NoSuchElementException",
"NotImplementedError",
"Nothing",
"Number",
"OpenEndRange",
"OptIn",
"Pair",
"ParameterName",
"PublishedApi",
"RandomAccess",
"Regex",
"RegexOption",
"Repeatable",
"ReplaceWith",
"RequiresOptIn",
"Result",
"Retention",
"Sequence",
"SequenceScope",
"Set",
"Short",
"ShortArray",
"SinceKotlin",
"String",
"StringBuilder",
"Strictfp",
"Suppress",
"Synchronized",
"Target",
"Throws",
"Transient",
"Triple",
"UByte",
"UByteArray",
"UInt",
"UIntArray",
"UIntRange",
"ULong",
"ULongArray",
"ULongRange",
"UShort",
"UShortArray",
"UninitializedPropertyAccessException",
"Unit",
"Volatile",
/* functions */
"TODO",
"also",
"apply",
"arrayListOf",
"arrayOf",
"arrayOfNulls",
"assert",
"buildList",
"buildMap",
"buildSet",
"buildString",
"check",
"checkNotNull",
"compareBy",
"compareValues",
"emptyArray",
"emptyList",
"emptyMap",
"emptySequence",
"emptySet",
"enumValueOf",
"enumValues",
"error",
"generateSequence",
"hashMapOf",
"hashSetOf",
"lazy",
"lazyOf",
"let",
"linkedMapOf",
"linkedSetOf",
"listOf",
"listOfNotNull",
"mapOf",
"maxOf",
"minOf",
"mutableListOf",
"mutableMapOf",
"mutableSetOf",
"print",
"println",
"readLine",
"readln",
"repeat",
"require",
"requireNotNull",
"run",
"runCatching",
"sequence",
"sequenceOf",
"setOf",
"synchronized",
"takeIf",
"takeUnless",
"to",
"use",
"with",
};
static const char *const JR_JAVA_PRIMITIVES[] = {"boolean", "byte", "char", "short", "int",
"long", "float", "double", "void"};
/* The members a type has without declaring them. These lists are defined by
* the two languages, not collected from a library: the methods of
* java.lang.Object with their parameter lists ('|'-joined, as a declared
* signature is normalized), the three members of kotlin.Any, and what an enum
* has in either language (the methods of java.lang.Enum with the two static
* ones the language declares; the Kotlin counterparts). Written from knowledge
* of the two language specifications; not checked online. */
typedef struct {
const char *name;
const char *sig;
} jr_given_t;
static const jr_given_t JR_OBJECT_METHODS[] = {
{"equals", "Object"}, {"hashCode", ""}, {"toString", ""}, {"clone", ""},
{"finalize", ""}, {"getClass", ""}, {"notify", ""}, {"notifyAll", ""},
{"wait", ""}, {"wait", "long"}, {"wait", "long|int"}};
static const char *const JR_ANY_MEMBERS[] = {"equals", "hashCode", "toString"};
static const char *const JR_JAVA_ENUM_MEMBERS[] = {
"values", "valueOf", "name", "ordinal", "compareTo", "getDeclaringClass", "describeConstable"};
static const char *const JR_KOTLIN_ENUM_MEMBERS[] = {"values", "valueOf", "entries",
"name", "ordinal", "compareTo"};
static bool jr_named(const char *const *table, size_t n, const char *name) {
for (size_t i = 0; i < n; i++) {
if (strcmp(table[i], name) == 0) {
return true;
}
}
return false;
}
#define JR_NAMED(table, name) jr_named(table, sizeof(table) / sizeof((table)[0]), name)
/* ── Resolution context ──────────────────────────────────────────── */
/* The scan nests types JV_MAX_DEPTH (128) deep at most; a chain is never
* longer. */
enum { JR_CHAIN_MAX = 136 };
enum { JR_OK = 0, JR_UNRES, JR_LOCAL };
typedef struct {
int st;
const cbm_gbuf_node_t *node;
bool exact;
int reason;
} jr_res_t;
typedef struct {
const jr_index_t *ix;
const cbm_gbuf_t *g;
int file;
const jr_file_t *f;
bool prod; /* test-only declarations are invisible */
bool sample; /* a `@sample` subject: it names a function */
bool inherit; /* false while supertypes are being bound */
int chain[JR_CHAIN_MAX]; /* enclosing types, innermost first */
const jr_type_t *chain_decl[JR_CHAIN_MAX]; /* ... and their declarations in this file */
int nchain;
const jr_member_t *member; /* the documented member, when the definition is one */
const jr_type_t *type; /* the documented type, when the definition is one */
} jr_ctx_t;
static jr_res_t jr_edge(const cbm_gbuf_node_t *n, bool exact) {
return (jr_res_t){.st = JR_OK, .node = n, .exact = exact};
}
static jr_res_t jr_unres(int reason) {
return (jr_res_t){.st = JR_UNRES, .reason = reason};
}
static bool jr_visible(const jr_ctx_t *c, int ent) {
return !c->prod || c->ix->ents[ent].any_prod;
}
/* The enclosing types of type `t` of the context's file, `t` first. */
static void jr_chain_from(jr_ctx_t *c, int t) {
while (t != JR_NONE && c->nchain < JR_CHAIN_MAX) {
const jr_type_t *ty = &c->f->types[t];
if (ty->entity >= 0) {
c->chain[c->nchain] = ty->entity;
c->chain_decl[c->nchain] = ty;
c->nchain++;
}
t = ty->outer;
}
}
/* ── Type candidates of one scope level ──────────────────────────── */
typedef struct {
char kind; /* 0 none; T a type, X a name outside the repository, G a name the
repository declares where no scope shows it, N a name in a
package of the repository that the indexer does not read */
int ent; /* T: the type */
int count; /* distinct candidates; 2 stands for "several" */
bool invisible; /* a candidate product code may not bind was passed over */
bool exact; /* named by an explicit import */
} jr_cands_t;
static void jr_cand(jr_cands_t *out, char kind, int ent) {
if (out->count > 0 && out->kind == kind && out->ent == ent) {
return;
}
if (out->count == 0) {
out->kind = kind;
out->ent = ent;
}
out->count += out->count < PAIR_LEN;
}
/* A type, unless the source may not name it: product code does not see what
* only test code declares, and Java does not see a Kotlin type alias. */
static void jr_cand_type(const jr_ctx_t *c, jr_cands_t *out, int ent) {
if (ent < 0 || (!c->f->kotlin && c->ix->ents[ent].kind == 't')) {
return;
}
if (!jr_visible(c, ent)) {
out->invisible = true;
return;
}
jr_cand(out, 'T', ent);
}
/* ── Types: lookup tables ────────────────────────────────────────── */
static int jr_pkg_type(const jr_index_t *ix, const char *package, const char *name) {
char key[JR_KEY_BUF];
if (!jr_pair_key(package, name, key, sizeof(key))) {
return JR_NONE;
}
intptr_t v = (intptr_t)cbm_ht_get(ix->pkg_types, key);
return v > 0 ? (int)(v - SKIP_ONE) : JR_NONE;
}
/* The type `name` nested directly in entity `ent`. */
static int jr_nested(const jr_index_t *ix, int ent, const char *name) {
char fqn[JR_KEY_BUF];
if (!jr_fqn(ix->ents[ent].fqn, name, fqn, sizeof(fqn))) {
return JR_NONE;
}
return jr_ent(ix, fqn);
}
/* The member type `name` of `ent`: its own, else the one of the nearest
* supertype that declares one. */
static int jr_member_type(const jr_ctx_t *c, int ent, const char *name) {
int own = jr_nested(c->ix, ent, name);
if (own != JR_NONE || !c->inherit) {
return own;
}
const jr_entity_t *e = &c->ix->ents[ent];
for (int i = 0; i < e->nclosure; i++) {
int n = jr_nested(c->ix, e->closure[i], name);
if (n != JR_NONE) {
return n;
}
}
return JR_NONE;
}
static bool jr_open(const jr_index_t *ix, int ent) {
const jr_entity_t *e = &ix->ents[ent];
if (e->open) {
return true;
}
for (int i = 0; i < e->nclosure; i++) {
if (ix->ents[e->closure[i]].open) {
return true;
}
}
return false;
}
/* True when `sup` is `ent` or one of its supertypes. */
static bool jr_is_or_extends(const jr_index_t *ix, int ent, int sup) {
if (ent == sup) {
return true;
}
const jr_entity_t *e = &ix->ents[ent];
for (int i = 0; i < e->nclosure; i++) {
if (e->closure[i] == sup) {
return true;
}
}
return false;
}
/* ── Node binding ────────────────────────────────────────────────── */
/* Representative ordering of the declarations of one entity, without node
* ids or lines: the source file itself, the longest common directory prefix
* with it, then path and declaration order. */
static int jr_common_dirs(const char *a, const char *b) {
int n = 0;
for (;;) {
const char *sa = strchr(a, '/');
const char *sb = strchr(b, '/');
if (!sa || !sb) {
return n;
}
size_t la = (size_t)(sa - a);
if (la != (size_t)(sb - b) || memcmp(a, b, la) != 0) {
return n;
}
n++;
a = sa + SKIP_ONE;
b = sb + SKIP_ONE;
}
}
static bool jr_decl_better(const jr_index_t *ix, int fa, int oa, int fb, int ob, const char *src) {
const char *ra = ix->files[fa].rel_path;
const char *rb = ix->files[fb].rel_path;
bool sa = strcmp(ra, src) == 0;
bool sb = strcmp(rb, src) == 0;
if (sa != sb) {
return sa;
}
int pa = jr_common_dirs(ra, src);
int pb = jr_common_dirs(rb, src);
if (pa != pb) {
return pa > pb;
}
int cmp = strcmp(ra, rb);
if (cmp != 0) {
return cmp < 0;
}
return oa < ob;
}
static bool jr_label_callable(const char *l) {
return l && (strcmp(l, "Method") == 0 || strcmp(l, "Function") == 0);
}
static bool jr_label_value(const char *l) {
return l && (strcmp(l, "Field") == 0 || strcmp(l, "Variable") == 0);
}
/* The node at "<module>.<tail>" when it is this file's own: one node per
* qualified name, and across files the graph keeps one file's. */
static const cbm_gbuf_node_t *jr_node_at(const jr_ctx_t *c, const jr_file_t *f, const char *tail) {
char qn[JR_KEY_BUF];
if (snprintf(qn, sizeof(qn), "%s.%s", f->module_qn, tail) >= (int)sizeof(qn)) {
return NULL;
}
const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(c->g, qn);
return (n && n->file_path && strcmp(n->file_path, f->rel_path) == 0) ? n : NULL;
}
/* The node of a type declaration; NULL when it has none of its own. */
static const cbm_gbuf_node_t *jr_type_node(const jr_ctx_t *c, jr_decl_t d) {
const jr_file_t *f = &c->ix->files[d.file];
const jr_type_t *t = &f->types[d.type];
if (!t->slot || !t->own) {
return NULL;
}
const cbm_gbuf_node_t *n = jr_node_at(c, f, strcmp(t->slot, "=") == 0 ? t->path : t->slot);
return (n && cbm_label_is_type_like(n->label)) ? n : NULL;
}
/* The node of a member: its own, or the one the overloads of its name share.
* NULL when it has none, or when the slot holds a node of the other kind. */
static const cbm_gbuf_node_t *jr_member_node(const jr_ctx_t *c, int file, const jr_member_t *m) {
const jr_file_t *f = &c->ix->files[file];
if (m->shares == JR_NONE) {
return NULL;
}
const jr_member_t *o = &f->members[m->shares];
char tail[JR_KEY_BUF];
const char *slot = o->slot;
if (strcmp(slot, "=") == 0) {
int n = o->owner == JR_NONE
? snprintf(tail, sizeof(tail), "%s", o->name)
: snprintf(tail, sizeof(tail), "%s.%s", f->types[o->owner].path, o->name);
if (n < 0 || n >= (int)sizeof(tail)) {
return NULL;
}
slot = tail;
}
const cbm_gbuf_node_t *n = jr_node_at(c, f, slot);
if (!n) {
return NULL;
}
return (o->kind == 'c' ? jr_label_callable(n->label) : jr_label_value(n->label)) ? n : NULL;
}
/* The entity's representative node: never a test declaration for product
* code. An entity none of whose eligible declarations has a node is a graph
* gap. */
static jr_res_t jr_type_result(const jr_ctx_t *c, int ent, bool exact) {
const jr_index_t *ix = c->ix;
const jr_entity_t *e = &ix->ents[ent];
const cbm_gbuf_node_t *best = NULL;
int bf = 0;
int bo = 0;
for (int d = 0; d < e->ndecls; d++) {
int file = e->decls[d].file;
if (c->prod && ix->files[file].is_test) {
continue;
}
const cbm_gbuf_node_t *n = jr_type_node(c, e->decls[d]);
if (n && (!best || jr_decl_better(ix, file, e->decls[d].type, bf, bo, c->f->rel_path))) {
best = n;
bf = file;
bo = e->decls[d].type;
}
}
return best ? jr_edge(best, exact) : jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
/* ── Reference syntax ────────────────────────────────────────────── */
typedef struct {
char text[CBM_DOCLINK_JVM_REF_MAX + CBM_SZ_8]; /* the segments point in here */
char *segs[JR_MAX_SEGS];
int nsegs;
char *member; /* Java: the name after '#' (or of a bare `name(..)`); NULL when none */
bool has_params;
char params[JR_MAX_PARAMS][JR_PARAM_BUF];
int nparams;
} jr_ref_t;
static bool jr_ident(const char *s) {
unsigned char first = (unsigned char)s[0];
if (!(isalpha(first) || first == '_' || first == '$' || first >= 0x80)) {
return false;
}
for (const char *p = s + SKIP_ONE; *p; p++) {
unsigned char u = (unsigned char)*p;
if (!(isalnum(u) || u == '_' || u == '$' || u >= 0x80)) {
return false;
}
}
return true;
}
/* Split a dotted path in place into identifiers; false when a part is none
* or there are more parts than a name has. */
static bool jr_split_path(char *s, jr_ref_t *r) {
r->nsegs = 0;
if (!s[0]) {
return true;
}
for (char *p = s;;) {
char *dot = strchr(p, '.');
if (dot) {
*dot = '\0';
}
if (r->nsegs >= JR_MAX_SEGS || !jr_ident(p)) {
return false;
}
r->segs[r->nsegs++] = p;
if (!dot) {
return true;
}
p = dot + SKIP_ONE;
}
}
/* The written parameter list s[0, n) of a Javadoc member reference:
* normalized like the declared signatures. false when it has more
* parameters than any method. */
static bool jr_parse_params(const char *s, size_t n, jr_ref_t *r) {
r->has_params = true;
r->nparams = 0;
bool any = false;
for (size_t i = 0; i < n; i++) {
any = any || !isspace((unsigned char)s[i]);
}
if (!any) {
return true;
}
size_t start = 0;
int depth = 0;
for (size_t i = 0; i <= n; i++) {
char ch = i < n ? s[i] : ',';
if (ch == '<' || ch == '(' || ch == '[') {
depth++;
} else if (ch == '>' || ch == ')' || ch == ']') {
depth--;
} else if (ch == ',' && depth <= 0) {
if (r->nparams >= JR_MAX_PARAMS) {
return false;
}
char *p = r->params[r->nparams];
cbm_doclink_java_norm_type(s + start, i - start, p, sizeof(r->params[0]));
if (p[0] == '?' && p[SKIP_ONE] == '\0') {
return false; /* no type, or one longer than any */
}
r->nparams++;
start = i + SKIP_ONE;
}
}
return true;
}
/* `[module/]Type[#member[(params)]]`, `#member[(params)]`, `member(params)`. */
static bool jr_parse_java(const char *raw, jr_ref_t *r) {
memset(r, 0, sizeof(*r));
size_t len = strlen(raw);
if (len == 0 || len > CBM_DOCLINK_JVM_REF_MAX) {
return false; /* over-long: never resolve a truncated prefix */
}
memcpy(r->text, raw, len + SKIP_ONE);
char *s = r->text;
char *hash = strchr(s, '#');
char *paren = strchr(s, '(');
char *slash = strchr(s, '/');
if (slash && (!hash || slash < hash) && (!paren || slash < paren)) {
s = slash + SKIP_ONE; /* a module prefix */
}
char *type = s;
char *member = NULL;
if (hash) {
*hash = '\0';
member = hash + SKIP_ONE;
} else if (paren) {
member = s; /* `name(..)`: a member of the documented type */
type = NULL;
}
if (member) {
char *mp = strchr(member, '(');
if (mp) {
size_t ml = strlen(mp);
if (mp[ml - SKIP_ONE] != ')' || !jr_parse_params(mp + SKIP_ONE, ml - PAIR_LEN, r)) {
return false; /* a list that does not close, or is longer than any */
}
*mp = '\0';
}
if (!jr_ident(member)) {
return false;
}
r->member = member;
}
if (type) {
/* without type arguments and array brackets */
char *lt = strchr(type, '<');
if (lt) {
*lt = '\0';
}
size_t tl = strlen(type);
while (tl >= PAIR_LEN && type[tl - PAIR_LEN] == '[' && type[tl - SKIP_ONE] == ']') {
tl -= PAIR_LEN;
type[tl] = '\0';
}
if (!jr_split_path(type, r)) {
return false;
}
}
return r->nsegs > 0 || r->member != NULL;
}
/* A KDoc name: dotted, a segment may be backticked. */
static bool jr_parse_kotlin(const char *raw, jr_ref_t *r) {
memset(r, 0, sizeof(*r));
size_t len = strlen(raw);
if (len == 0 || len > CBM_DOCLINK_JVM_REF_MAX) {
return false;
}
/* copy without backticks; a dot inside backticks is no separator, and a
* name that holds one cannot be a path segment here */
size_t w = 0;
bool quoted = false;
for (size_t i = 0; i < len; i++) {
if (raw[i] == '`') {
quoted = !quoted;
} else if (quoted && raw[i] == '.') {
return false;
} else {
r->text[w++] = raw[i];
}
}
r->text[w] = '\0';
if (quoted) {
return false;
}
if (w > PAIR_LEN && r->text[w - PAIR_LEN] == '(' && r->text[w - SKIP_ONE] == ')') {
r->text[w - PAIR_LEN] = '\0'; /* `@see name()` */
}
r->nsegs = 0;
for (char *p = r->text;;) {
char *dot = strchr(p, '.');
if (dot) {
*dot = '\0';
}
if (r->nsegs >= JR_MAX_SEGS || !p[0] || strpbrk(p, "\t()#<>[]{}/\\:;,\"'")) {
return false;
}
r->segs[r->nsegs++] = p;
if (!dot) {
break;
}
p = dot + SKIP_ONE;
}
return r->nsegs > 0;
}
/* ── Members of a type ───────────────────────────────────────────── */
enum {
JR_SEL_VALUES = 1, /* fields, properties, enum constants, components */
JR_SEL_CALLABLES = 2, /* methods and functions, no constructors */
JR_SEL_CTORS = 4, /* constructors only */
JR_SEL_SIG = 8, /* of the callables, those with the written signature */
};
typedef struct {
int count; /* the selected members */
bool several; /* ... are more than one thing: different signatures,
or members of different owners */
bool component; /* one is a record component or constructor property */
bool invisible; /* members left out because product code may not bind
what only test code declares */
bool uncompared; /* callables left out because a Javadoc signature cannot
be compared with a Kotlin declaration's */
const char *sig; /* the first one's */
const cbm_gbuf_node_t *node; /* the representative node of those that have one */
int node_file;
int node_order;
} jr_found_t;
/* Index of the first member of type `type` in `f` named `name` (the members
* are sorted by owner, name, order); f->nmembers when there is none before
* the end. */
static int jr_member_lower(const jr_file_t *f, int type, const char *name) {
int lo = 0;
int hi = f->nmembers;
while (lo < hi) {
int mid = lo + ((hi - lo) / PAIR_LEN);
const jr_member_t *m = &f->members[mid];
bool below = m->owner != type ? m->owner < type : strcmp(m->name, name) < 0;
if (below) {
lo = mid + SKIP_ONE;
} else {
hi = mid;
}
}
return lo;
}
/* The suffix of a normalized type that says how many array levels it has. */
static size_t jr_array_suffix(const char *s, size_t n) {
size_t e = n;
while (e >= PAIR_LEN && s[e - PAIR_LEN] == '[' && s[e - SKIP_ONE] == ']') {
e -= PAIR_LEN;
}
return e;
}
/* True when `name[0, n)` is a type variable in scope of a member of type
* `owner` whose own type parameters are `mtparams`: the member's, its type's
* or an enclosing type's. *bound / *blen: its first bound. */
static bool jr_is_tvar(const jr_file_t *f, const char *mtparams, int owner, const char *name,
size_t n, const char **bound, size_t *blen) {
if (n == 0) {
return false;
}
if (jr_listed_n(mtparams, name, n, bound, blen)) {
return true;
}
for (int t = owner; t != JR_NONE; t = f->types[t].outer) {
if (jr_listed_n(f->types[t].tparams, name, n, bound, blen)) {
return true;
}
}
return false;
}
/* One written parameter type against one declared type: the same name, or
* the erasure of a declared type variable (its first bound, Object when it
* has none) with the same array rank. Nothing else: javadoc matches a
* signature against the declared types and against their erasures. */
static bool jr_param_match(const jr_file_t *f, const char *mtparams, int owner, const char *written,
const char *declared, size_t dn) {
static const char object[] = "Object";
size_t wn = strlen(written);
if (wn == SKIP_ONE && written[0] == '?') {
return false; /* a written type that is no type */
}
if (wn == dn && memcmp(written, declared, wn) == 0) {
return true;
}
size_t wb = jr_array_suffix(written, wn);
size_t db = jr_array_suffix(declared, dn);
const char *bound = NULL;
size_t blen = 0;
if ((wn - wb) != (dn - db) || !jr_is_tvar(f, mtparams, owner, declared, db, &bound, &blen)) {
return false;
}
if (blen == 0) {
bound = object;
blen = sizeof(object) - SKIP_ONE;
}
return wb == blen && memcmp(written, bound, blen) == 0;
}
/* True when the written parameter list is the canonical one of the record
* `owner` declares: its components' types, in declaration order. The written
* list is at most JR_MAX_PARAMS long, which bounds the passes over the
* record's members. */
static bool jr_canonical_match(const jr_file_t *f, int owner, const jr_ref_t *r) {
int first = jr_member_lower(f, owner, "");
int components = 0;
for (int i = first; i < f->nmembers && f->members[i].owner == owner; i++) {
components += f->members[i].component;
}
if (components != r->nparams) {
return false;
}
int last_order = JR_NONE;
for (int k = 0; k < r->nparams; k++) {
const jr_member_t *next = NULL; /* the component with the next larger order */
for (int i = first; i < f->nmembers && f->members[i].owner == owner; i++) {
const jr_member_t *x = &f->members[i];
if (x->component && x->order > last_order && (!next || x->order < next->order)) {
next = x;
}
}
if (!next || !jr_param_match(f, "", owner, r->params[k], next->sig, strlen(next->sig))) {
return false;
}
last_order = next->order;
}
return true;
}
/* The written parameter types against a declared signature. */
static bool jr_sig_match(const jr_file_t *f, const jr_member_t *m, const jr_ref_t *r) {
if (m->ctor && strcmp(m->sig, "*") == 0) {
return jr_canonical_match(f, m->owner, r);
}
const char *p = m->sig;
for (int i = 0; i < r->nparams; i++) {
if (!p || !*p) {
return false; /* fewer declared than written */
}
const char *bar = strchr(p, '|');
size_t dn = bar ? (size_t)(bar - p) : strlen(p);
if (!jr_param_match(f, m->tparams, m->owner, r->params[i], p, dn)) {
return false;
}
p = bar ? bar + SKIP_ONE : NULL;
}
return r->nparams == 0 ? m->sig[0] == '\0' : p == NULL;
}
/* Count member `m` of `file` among the selected ones. */
static void jr_found_take(const jr_ctx_t *c, jr_found_t *out, int file, const jr_member_t *m) {
if (out->count == 0) {
out->sig = m->sig;
} else if (strcmp(out->sig, m->sig) != 0) {
out->several = true;
}
out->count++;
out->component = out->component || m->component;
const cbm_gbuf_node_t *n = jr_member_node(c, file, m);
if (n && (!out->node || jr_decl_better(c->ix, file, m->order, out->node_file, out->node_order,
c->f->rel_path))) {
out->node = n;
out->node_file = file;
out->node_order = m->order;
}
}
/* Add to `out` the members named `name` that `sel` selects among those `type`
* of `file` declares (JR_NONE: the file's top-level declarations). */
static void jr_members_in(const jr_ctx_t *c, int file, int type, const char *name, int sel,
const jr_ref_t *r, jr_found_t *out) {
const jr_file_t *f = &c->ix->files[file];
for (int i = jr_member_lower(f, type, name); i < f->nmembers; i++) {
const jr_member_t *m = &f->members[i];
if (m->owner != type || strcmp(m->name, name) != 0) {
break;
}
bool take = m->kind == 'v' ? (sel & JR_SEL_VALUES) != 0
: (sel & (m->ctor ? JR_SEL_CTORS : JR_SEL_CALLABLES)) != 0;
if (!take) {
continue;
}
if (c->prod && f->is_test) {
out->invisible = true;
continue;
}
if ((sel & JR_SEL_SIG) && m->kind == 'c') {
if (f->kotlin) {
out->uncompared = true; /* Kotlin writes its types another way */
continue;
}
if (!jr_sig_match(f, m, r)) {
continue;
}
}
jr_found_take(c, out, file, m);
}
}
/* The members of entity `ent` named `name` that `sel` selects, across its
* declarations. */
static jr_found_t jr_members(const jr_ctx_t *c, int ent, const char *name, int sel,
const jr_ref_t *r) {
const jr_entity_t *e = &c->ix->ents[ent];
jr_found_t out = {0};
for (int d = 0; d < e->ndecls; d++) {
jr_members_in(c, e->decls[d].file, e->decls[d].type, name, sel, r, &out);
}
return out;
}
/* The top-level declarations named `name` of package `pkg`, across its
* files. */
static jr_found_t jr_top_members(const jr_ctx_t *c, const char *pkg, const char *name, int sel) {
jr_found_t out = {0};
char key[JR_KEY_BUF];
if (!jr_pair_key(pkg, name, key, sizeof(key))) {
return out;
}
const jr_ilist_t *l = (const jr_ilist_t *)cbm_ht_get(c->ix->pkg_members, key);
for (int i = 0; l && i < l->count; i++) {
jr_members_in(c, l->items[i], JR_NONE, name, sel, NULL, &out);
}
return out;
}
/* Join the members found under one name in two places. Members of different
* owners are different things, whatever their signatures. */
static void jr_found_add(const jr_ctx_t *c, jr_found_t *into, const jr_found_t *add,
bool same_owner) {
into->invisible = into->invisible || add->invisible;
into->uncompared = into->uncompared || add->uncompared;
if (add->count == 0) {
return;
}
if (into->count == 0) {
bool invisible = into->invisible;
bool uncompared = into->uncompared;
*into = *add;
into->invisible = invisible;
into->uncompared = uncompared;
return;
}
into->several =
into->several || add->several || !same_owner || strcmp(into->sig, add->sig) != 0;
into->count += add->count;
into->component = into->component || add->component;
if (add->node &&
(!into->node || jr_decl_better(c->ix, add->node_file, add->node_order, into->node_file,
into->node_order, c->f->rel_path))) {
into->node = add->node;
into->node_file = add->node_file;
into->node_order = add->node_order;
}
}
/* The selected members as a result: their node, or a graph gap when the
* source declares them and the graph has no node for them. */
static jr_res_t jr_found_result(const jr_found_t *found, bool exact) {
return found->node ? jr_edge(found->node, exact) : jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
/* ── Type paths ──────────────────────────────────────────────────── */
typedef enum { JR_TP_OK = 0, JR_TP_PARTIAL, JR_TP_RES } jr_tp_kind_t;
typedef struct {
jr_tp_kind_t st;
int ent; /* OK: the type; PARTIAL: the last type reached */
int failed_seg; /* PARTIAL: index of the segment that is no member type */
bool exact;
bool unfound; /* RES: no scope level has the head (the result says why not) */
jr_res_t res; /* RES */
} jr_tp_t;
static jr_tp_t jr_tp_res(jr_res_t r) {
return (jr_tp_t){.st = JR_TP_RES, .res = r};
}
static bool jr_join(char *const *segs, int from, int to, char *out, size_t cap) {
size_t w = 0;
out[0] = '\0';
for (int i = from; i < to; i++) {
int k = snprintf(out + w, cap - w, "%s%s", w ? "." : "", segs[i]);
if (k < 0 || (size_t)k >= cap - w) {
return false;
}
w += (size_t)k;
}
return true;
}
/* Walk segs[from, to) as member types of `cur` (own, then inherited). */
static jr_tp_t jr_walk_nested(const jr_ctx_t *c, int cur, char *const *segs, int from, int to,
bool exact) {
for (int i = from; i < to; i++) {
int next = jr_member_type(c, cur, segs[i]);
if (next == JR_NONE) {
return (jr_tp_t){.st = JR_TP_PARTIAL, .ent = cur, .failed_seg = i, .exact = exact};
}
if (!jr_visible(c, next)) {
return jr_tp_res(jr_unres(CBM_DOCLINK_REASON_TEST_ONLY));
}
cur = next;
}
return (jr_tp_t){.st = JR_TP_OK, .ent = cur, .exact = exact};
}
/* The file's single import of the simple name `name` with one of `kinds`;
* the next one after `prev` (the imports are sorted by alias). */
static const jr_import_t *jr_import_next(const jr_file_t *f, const char *name,
const jr_import_t *prev) {
int i;
if (prev) {
i = (int)(prev - f->imports) + SKIP_ONE;
} else {
int lo = 0;
int hi = f->nimports;
while (lo < hi) {
int mid = lo + ((hi - lo) / PAIR_LEN);
if (strcmp(f->imports[mid].alias, name) < 0) {
lo = mid + SKIP_ONE;
} else {
hi = mid;
}
}
i = lo;
}
return (i < f->nimports && strcmp(f->imports[i].alias, name) == 0) ? &f->imports[i] : NULL;
}
/* True when the repository declares package `p`. */
static bool jr_is_package(const jr_index_t *ix, const char *p) {
return p[0] && cbm_ht_get(ix->packages, p) != NULL;
}
/* The package part of a qualified name: everything before its last name.
* false for a simple name. */
static bool jr_package_of(const char *fqn, char *out, size_t cap) {
const char *dot = strrchr(fqn, '.');
if (!dot || (size_t)(dot - fqn) >= cap) {
return false;
}
memcpy(out, fqn, (size_t)(dot - fqn));
out[dot - fqn] = '\0';
return true;
}
/* True when the file's scope is open: an on-demand import of a package the
* repository does not declare (or of a type it does not declare) can supply
* any simple name. */
static bool jr_scope_open(const jr_ctx_t *c) {
for (int i = 0; i < c->f->nwild; i++) {
const char *target = c->f->wild[i].target;
if (!jr_is_package(c->ix, target) && jr_ent(c->ix, target) == JR_NONE) {
return true;
}
}
return false;
}
/* True when package `pkg` lies in a directory the indexer never reads, below
* a package the repository owns. A JVM package is a directory path, and
* discovery skips some directory names wherever they occur (`env`, `target`,
* `tmp` ...): what is declared there is on disk, but not in the graph. */
static bool jr_not_indexed(const jr_index_t *ix, const char *pkg) {
char buf[JR_KEY_BUF];
size_t n = strlen(pkg);
if (n == 0 || n >= sizeof(buf)) {
return false;
}
memcpy(buf, pkg, n + SKIP_ONE);
bool owned = false; /* a prefix before this segment is the repository's */
size_t seg = 0;
for (size_t i = 0; i <= n; i++) {
if (buf[i] != '.' && buf[i] != '\0') {
continue;
}
char keep = buf[i];
buf[i] = '\0'; /* buf: the prefix through this segment; buf + seg: the segment */
if (owned && cbm_should_skip_dir(buf + seg, (cbm_index_mode_t)ix->mode)) {
return true;
}
owned = owned || cbm_ht_get(ix->packages, buf) || cbm_ht_get(ix->pkg_prefixes, buf);
buf[i] = keep;
seg = i + SKIP_ONE;
}
return false;
}
/* What a name that no scope shows is, by its package: declared by the
* repository without a scope record (G: generated code, a declaration the
* scan does not see), in a part of it the indexer does not read (N), or
* outside the repository (X). `pkg`: the package, or the type, the name is
* said to be in. */
static char jr_unseen_kind(const jr_index_t *ix, const char *pkg) {
if (pkg[0] && (jr_is_package(ix, pkg) || jr_ent(ix, pkg) != JR_NONE)) {
return 'G';
}
return jr_not_indexed(ix, pkg) ? 'N' : 'X';
}
static int jr_kind_reason(char kind) {
return kind == 'G' ? CBM_DOCLINK_REASON_GRAPH_GAP
: kind == 'N' ? CBM_DOCLINK_REASON_NOT_INDEXED
: CBM_DOCLINK_REASON_EXTERNAL;
}
/* What an explicit import of `fqn` names: the type, or what jr_unseen_kind
* says of its package. */
static void jr_cand_import_type(const jr_ctx_t *c, jr_cands_t *out, const char *fqn) {
int ent = jr_ent(c->ix, fqn);
if (ent != JR_NONE) {
jr_cand_type(c, out, ent);
return;
}
char pkg[JR_KEY_BUF];
if (!jr_package_of(fqn, pkg, sizeof(pkg))) {
pkg[0] = '\0';
}
jr_cand(out, jr_unseen_kind(c->ix, pkg), JR_NONE);
}
/* ── Why a name was not found ────────────────────────────────────── */
/* A simple name no scope level has: the scope can still explain it. */
static jr_res_t jr_unfound_simple(const jr_ctx_t *c, const char *name) {
if (!c->f->kotlin && JR_NAMED(JR_JAVA_PRIMITIVES, name)) {
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
if (jr_scope_open(c)) {
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
for (int i = 0; c->inherit && i < c->nchain; i++) {
if (jr_open(c->ix, c->chain[i])) {
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL); /* a supertype outside may declare it */
}
}
return jr_unres(CBM_DOCLINK_REASON_MISSING);
}
/* True when the file imports something of package `pkg` (or the package
* itself on demand) and the repository does not declare that package. */
static bool jr_imports_outside(const jr_ctx_t *c, const char *pkg) {
if (jr_is_package(c->ix, pkg)) {
return false;
}
size_t pl = strlen(pkg);
for (int i = 0; i < c->f->nwild; i++) {
if (strcmp(c->f->wild[i].target, pkg) == 0) {
return true;
}
}
for (int i = 0; i < c->f->nimports; i++) {
const char *t = c->f->imports[i].target;
if (strncmp(t, pkg, pl) == 0 && t[pl] == '.') {
return true;
}
}
return false;
}
/* A qualified name that is no type, no member and no top-level declaration.
* - a package of the repository (or the start of one): packages have no node
* - `pkg.Type..` (a capitalized name after the package part): the type is
* missing when the repository declares that package, else it is outside
* - all lower case: the languages' own namespaces and what the file imports
* from outside are external; anything else names nothing
* - `Type.x` with an unknown head: as the simple name
* The roots are the namespaces the two platforms define themselves (`java`,
* `javax`, `kotlin`). A library family is none, however common: a path under
* `kotlinx` or `org` is external only where the file imports from it. */
static jr_res_t jr_unfound_path(const jr_ctx_t *c, char *const *segs, int n) {
static const char *const roots[] = {"java", "javax", "kotlin"};
const jr_index_t *ix = c->ix;
char buf[JR_KEY_BUF];
if (!jr_join(segs, 0, n, buf, sizeof(buf))) {
return jr_unres(CBM_DOCLINK_REASON_UNPARSEABLE);
}
if (cbm_ht_get(ix->packages, buf) || cbm_ht_get(ix->pkg_prefixes, buf)) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
if (n == SKIP_ONE) {
return jr_unfound_simple(c, segs[0]);
}
int k = 0;
while (k < n && !isupper((unsigned char)segs[k][0])) {
k++;
}
if (k == 0) {
return jr_unfound_simple(c, segs[0]);
}
if (k < n) {
(void)jr_join(segs, 0, k, buf, sizeof(buf));
if (jr_is_package(ix, buf)) {
return jr_unres(CBM_DOCLINK_REASON_MISSING);
}
return jr_unres(jr_kind_reason(jr_unseen_kind(ix, buf)));
}
if (JR_NAMED(roots, segs[0])) {
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
if (jr_not_indexed(ix, buf)) {
return jr_unres(CBM_DOCLINK_REASON_NOT_INDEXED); /* a package the indexer skips */
}
for (int i = n; i >= SKIP_ONE; i--) {
(void)jr_join(segs, 0, i, buf, sizeof(buf));
if (jr_imports_outside(c, buf)) {
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
}
return jr_unres(CBM_DOCLINK_REASON_MISSING);
}
/* ── Members across supertypes ───────────────────────────────────── */
/* How many supertypes that declare a name are compared with the nearest one.
* Past that the name is ambiguous: an unresolved outcome with its reason,
* never a pick. */
enum { JR_CLASH_CHECKS = 16 };
typedef struct {
jr_found_t found; /* the fields of the first type that has any */
int ent; /* that type; JR_NONE when none has */
bool gap; /* a type with members a parse error hides was reached before
any was found: one of those may be the field */
bool open; /* nothing found, and a supertype outside the repository */
bool clash; /* a second type declares the name, and neither comes first */
bool invisible;
} jr_msearch_t;
/* The fields `name` of `ent` (enum constants and record components among
* them): its own, else those of the nearest supertype that declares any. A
* second supertype with the name must be one the first extends (hidden);
* else neither comes first: a clash. Methods are javadoc's search (jr_walk). */
static void jr_fields_in(const jr_ctx_t *c, int ent, const char *name, jr_msearch_t *out) {
const jr_index_t *ix = c->ix;
const jr_entity_t *e = &ix->ents[ent];
memset(out, 0, sizeof(*out));
out->ent = JR_NONE;
jr_found_t own = jr_members(c, ent, name, JR_SEL_VALUES, NULL);
out->invisible = own.invisible;
if (own.count > 0) {
out->found = own;
out->ent = ent;
return;
}
if (e->incomplete) {
out->gap = true;
return;
}
int checks = 0;
for (int k = 0; k < e->nclosure; k++) {
int sup = e->closure[k];
jr_found_t inh = jr_members(c, sup, name, JR_SEL_VALUES, NULL);
out->invisible = out->invisible || inh.invisible;
if (inh.count == 0) {
if (out->ent == JR_NONE && ix->ents[sup].incomplete) {
out->gap = true;
return;
}
continue;
}
if (out->ent == JR_NONE) {
out->found = inh;
out->ent = sup;
} else if (!out->clash &&
(++checks > JR_CLASH_CHECKS || !jr_is_or_extends(ix, out->ent, sup))) {
out->clash = true;
}
}
out->open = out->ent == JR_NONE && jr_open(ix, ent);
}
/* True when java.lang.Object has a method `name`. With `r`, a reference that
* writes a parameter list: one with exactly that list. */
static bool jr_object_method(const char *name, const jr_ref_t *r) {
for (size_t i = 0; i < sizeof(JR_OBJECT_METHODS) / sizeof(JR_OBJECT_METHODS[0]); i++) {
const char *p = JR_OBJECT_METHODS[i].sig;
bool same = strcmp(JR_OBJECT_METHODS[i].name, name) == 0;
for (int k = 0; same && r && k < r->nparams; k++) {
size_t n = strlen(r->params[k]);
same = n > 0 && strncmp(p, r->params[k], n) == 0 && (p[n] == '|' || p[n] == '\0');
p += same ? n + (p[n] == '|' ? SKIP_ONE : 0) : 0;
}
if (same && (!r || *p == '\0')) {
return true;
}
}
return false;
}
/* The members every type has without declaring them, in either language:
* Object's, an enum's, an annotation's. By name alone, and wider than any one
* language: it only tells `external` from `missing` once nothing was found. */
static bool jr_implicit_member(const jr_index_t *ix, int ent, const char *name) {
char kind = ix->ents[ent].kind;
if (jr_object_method(name, NULL)) {
return true;
}
if (kind == 'e') {
return JR_NAMED(JR_JAVA_ENUM_MEMBERS, name) || JR_NAMED(JR_KOTLIN_ENUM_MEMBERS, name);
}
return kind == 'a' && strcmp(name, "annotationType") == 0;
}
/* True when the type `ent`, a type around the documented definition of a
* Kotlin file, has a member `name` without declaring it: a member of
* kotlin.Any, at an enum class what an enum class has (the name alone
* decides). Java's counterpart is javadoc's own search (jr_walk). */
static bool jr_given_member(const jr_ctx_t *c, int ent, const char *name) {
char kind = c->ix->ents[ent].kind;
return JR_NAMED(JR_ANY_MEMBERS, name) ||
(kind == 'e' && JR_NAMED(JR_KOTLIN_ENUM_MEMBERS, name));
}
/* The fields `name` through the context's chain of types, innermost first: a
* type and what it inherits before the type around it. *level is the chain
* index of the hit. javadoc looks for a field in a type, then in the types
* around it, then in its supertypes; where the two orders find different
* fields, jr_java_member says ambiguous. */
static void jr_fields_around(const jr_ctx_t *c, const char *name, jr_msearch_t *out, int *level) {
bool open = false;
bool invisible = false;
memset(out, 0, sizeof(*out));
out->ent = JR_NONE;
*level = 0;
for (int i = 0; i < c->nchain; i++) {
jr_msearch_t one;
jr_fields_in(c, c->chain[i], name, &one);
open = open || one.open;
invisible = invisible || one.invisible;
if (one.ent != JR_NONE || one.gap) {
*out = one;
*level = i;
break;
}
}
out->open = out->ent == JR_NONE && !out->gap && open;
out->invisible = out->invisible || invisible;
}
/* ── Java: javadoc's search for a method ─────────────────────────── */
/* javadoc links `#m` and `Type#m` to the first method its own search finds
* (JavacTrees.searchMethod; read in the JDK 21 source on 2026-10-04, stated
* here in our words). It is not javac's scoping. From a type it looks at
* 1. the type's own methods of the name; with a written parameter list,
* one whose parameters match it;
* 2. the superclass, by this whole search: the superclass's own methods,
* its superclass, its interfaces and the type around the SUPERCLASS
* all come before step 3;
* 3. the interfaces, in the order written, each by this whole search;
* 4. the type around it, by this whole search;
* and at each type once. `#m` starts at the type of the documented
* definition, `Type#m` at the type named. The steps of each type come from
* its declarations (jr_walk_steps). java.lang.Object, java.lang.Enum and
* java.lang.annotation.Annotation are steps whose methods the language
* defines; an enum has values() and valueOf(String), a record equals,
* hashCode and toString without declaring them. A type outside the
* repository is a step the index cannot look into: a method there would be
* the one linked. These lists are the language's, written from knowledge of
* the Java SE API. */
static const char *const JR_ENUM_OWN_METHODS[] = {"values", "valueOf"};
static const char *const JR_RECORD_OWN_METHODS[] = {"equals", "hashCode", "toString"};
static const char *const JR_ENUM_CLASS_METHODS[] = {
"name", "ordinal", "compareTo", "getDeclaringClass", "describeConstable",
"valueOf", "equals", "hashCode", "toString", "clone",
"finalize"};
static const char *const JR_ANNOTATION_METHODS[] = {"annotationType", "equals", "hashCode",
"toString"};
/* How many types one search looks at, at most. A search that would look at
* more ends as ambiguous (JR_WK_LIMIT): never cut short into a result. */
enum { JR_WALK_MAX = 512, JR_WALK_SLOTS = 1024 /* a power of two above twice the max */ };
static const unsigned JR_WALK_MIX = 2654435761U; /* multiplicative hashing */
typedef enum {
JR_WK_NONE = 0, /* no type on the way has the method */
JR_WK_FOUND, /* a type of the repository declares it */
JR_WK_GIVEN, /* the language gives it */
JR_WK_OUTSIDE, /* a type outside the repository comes first */
JR_WK_GAP, /* a type whose members a parse error hides comes first */
JR_WK_UNCOMPARED, /* a Kotlin declaration of the name comes first, which a written
parameter list cannot be compared with: it may be the one */
JR_WK_LIMIT, /* more than JR_WALK_MAX types */
} jr_wk_t;
typedef struct {
jr_wk_t kind;
/* FOUND, GAP, UNCOMPARED: the type; OUTSIDE: the type whose supertype
* lies outside; GIVEN: the type that has the method without declaring
* it, or JR_W_OBJECT, JR_W_ENUM, JR_W_ANNOTATION */
int ent;
jr_found_t found; /* FOUND */
bool invisible; /* a declaration only test code holds was passed over */
bool passed_outside; /* for a field: a step outside was passed (jr_walk_ends) */
bool passed_gap; /* ... a type whose members a parse error hides */
} jr_walk_t;
enum { JR_WS_OWN = 0, JR_WS_SUPER, JR_WS_IFACES, JR_WS_DONE };
typedef struct {
int ent;
int stage; /* JR_WS_* */
int next; /* JR_WS_IFACES: the next interface step */
} jr_wframe_t;
/* Marks type `ent` as looked at (`slots` holds ent + 1); false when it was.
* The caller marks at most JR_WALK_MAX + 1 types, so a free slot is found. */
static bool jr_walk_mark(int *slots, int ent) {
unsigned mask = (unsigned)JR_WALK_SLOTS - SKIP_ONE;
unsigned h = ((unsigned)ent * JR_WALK_MIX) & mask;
for (int i = 0; i < JR_WALK_SLOTS; i++) {
if (slots[h] == ent + SKIP_ONE) {
return false;
}
if (slots[h] == 0) {
slots[h] = ent + SKIP_ONE;
return true;
}
h = (h + SKIP_ONE) & mask;
}
return false;
}
/* Step 1 at a type of the repository: what the type itself has under the
* name. True when that ends the step, as *out says. */
static bool jr_walk_own(const jr_ctx_t *c, int ent, const char *name, int sel, const jr_ref_t *r,
jr_walk_t *out) {
const jr_entity_t *e = &c->ix->ents[ent];
jr_found_t own = jr_members(c, ent, name, sel, r);
out->invisible = out->invisible || own.invisible;
out->ent = ent;
if (own.count > 0) {
out->kind = JR_WK_FOUND;
out->found = own;
return true;
}
if (own.uncompared) {
out->kind = JR_WK_UNCOMPARED;
return true;
}
if (e->kind == 'r' && (!(sel & JR_SEL_SIG) || r->nparams == 0)) {
jr_found_t comp = jr_members(c, ent, name, JR_SEL_VALUES, NULL);
if (comp.count > 0 && comp.component) {
/* a component's accessor: the record's own method, without a node */
memset(&out->found, 0, sizeof(out->found));
out->found.count = SKIP_ONE;
out->kind = JR_WK_FOUND;
return true;
}
}
if ((e->kind == 'e' && JR_NAMED(JR_ENUM_OWN_METHODS, name)) ||
(e->kind == 'r' && JR_NAMED(JR_RECORD_OWN_METHODS, name))) {
out->kind = JR_WK_GIVEN;
return true;
}
if (e->incomplete) {
out->kind = JR_WK_GAP;
return true;
}
out->ent = JR_NONE;
return false;
}
/* A step that is no type of the repository, taken from type `owner`. True
* when it ends the search, as *out says. With a written parameter list
* Object's methods are matched by it; an enum's and an annotation's by name. */
static bool jr_walk_marker(int step, int owner, const char *name, int sel, const jr_ref_t *r,
jr_walk_t *out) {
const jr_ref_t *sig = (sel & JR_SEL_SIG) ? r : NULL;
int given = JR_NONE;
if (step == JR_W_OUTSIDE) {
out->kind = JR_WK_OUTSIDE;
out->ent = owner;
return true;
}
if (step == JR_W_OBJECT && jr_object_method(name, sig)) {
given = JR_W_OBJECT;
} else if (step == JR_W_ENUM && JR_NAMED(JR_ENUM_CLASS_METHODS, name)) {
given = JR_W_ENUM;
} else if (step == JR_W_ENUM && jr_object_method(name, sig)) {
given = JR_W_OBJECT;
} else if (step == JR_W_ANNOTATION && JR_NAMED(JR_ANNOTATION_METHODS, name)) {
given = JR_W_ANNOTATION;
}
if (given == JR_NONE) {
return false;
}
out->kind = JR_WK_GIVEN;
out->ent = given;
return true;
}
/* Whether the search ends where *out says. A method is linked where it is
* found. For a field of class `cf` (jr_java_field) a step outside the
* repository, or a type whose members a parse error hides, does not end it
* when `cf` is below the type the step belongs to: whatever method is there,
* the field comes first, so the search goes on to what may come after it.
* `peek`, for a count only, passes everything but a method of the
* repository. */
static bool jr_walk_ends(const jr_index_t *ix, jr_walk_t *out, int cf, bool peek) {
bool pass = false;
if (peek) {
pass = out->kind != JR_WK_FOUND;
} else if (cf != JR_NONE && (out->kind == JR_WK_OUTSIDE || out->kind == JR_WK_GAP) &&
jr_is_or_extends(ix, cf, out->ent)) {
pass = true;
if (out->kind == JR_WK_OUTSIDE) {
out->passed_outside = true;
} else {
out->passed_gap = true;
}
}
if (pass) {
out->kind = JR_WK_NONE;
out->ent = JR_NONE;
}
return !pass;
}
/* javadoc's search for a method `name` (`sel`, `r`: a written parameter
* list) from type `start`, without recursion: an explicit stack, each type
* once. `cf` and `peek`: jr_walk_ends. */
static void jr_walk(const jr_ctx_t *c, int start, const char *name, int sel, const jr_ref_t *r,
int cf, bool peek, jr_walk_t *out) {
const jr_index_t *ix = c->ix;
int slots[JR_WALK_SLOTS];
jr_wframe_t stack[JR_WALK_MAX];
memset(slots, 0, sizeof(slots));
memset(out, 0, sizeof(*out));
out->ent = JR_NONE;
(void)jr_walk_mark(slots, start);
int marked = SKIP_ONE;
int depth = 0;
stack[depth++] = (jr_wframe_t){.ent = start, .stage = JR_WS_OWN, .next = 0};
while (depth > 0) {
jr_wframe_t *fr = &stack[depth - SKIP_ONE];
const jr_entity_t *e = &ix->ents[fr->ent];
int step = JR_W_NONE;
if (fr->stage == JR_WS_OWN) {
fr->stage = JR_WS_SUPER;
if (jr_walk_own(c, fr->ent, name, sel, r, out) && jr_walk_ends(ix, out, cf, peek)) {
return;
}
continue;
}
if (fr->stage == JR_WS_SUPER) {
fr->stage = JR_WS_IFACES;
step = e->wsuper;
} else if (fr->stage == JR_WS_IFACES && fr->next < e->nwifaces) {
step = e->wifaces[fr->next++];
} else if (fr->stage == JR_WS_IFACES) {
fr->stage = JR_WS_DONE;
step = e->encl;
} else {
depth--;
continue;
}
if (step < 0) {
if (jr_walk_marker(step, fr->ent, name, sel, r, out) &&
jr_walk_ends(ix, out, cf, peek)) {
return;
}
continue;
}
if (!jr_walk_mark(slots, step)) {
continue;
}
if (++marked > JR_WALK_MAX) {
out->kind = JR_WK_LIMIT;
out->ent = JR_NONE;
return;
}
stack[depth++] = (jr_wframe_t){.ent = step, .stage = JR_WS_OWN, .next = 0};
}
}
/* ── Java ────────────────────────────────────────────────────────── */
typedef enum { JR_LK_NONE = 0, JR_LK_FOUND, JR_LK_INVISIBLE, JR_LK_LOCAL } jr_lk_t;
/* Closes one scope level: true when it has a candidate, which then decides
* the lookup. */
static bool jr_level_done(jr_cands_t *lv, jr_cands_t *out, bool *invisible) {
if (lv->count > 0) {
*out = *lv;
return true;
}
*invisible = *invisible || lv->invisible;
memset(lv, 0, sizeof(*lv));
return false;
}
/* True when the type `ent` has a declaration in file `file`. */
static bool jr_declared_in(const jr_index_t *ix, int ent, int file) {
const jr_entity_t *e = &ix->ents[ent];
for (int d = 0; d < e->ndecls; d++) {
if (e->decls[d].file == file) {
return true;
}
}
return false;
}
/* The member types an on-demand import of `target` offers under `name`. */
static void jr_java_on_demand(const jr_ctx_t *c, jr_cands_t *lv, const jr_import_t *imp,
const char *name) {
const jr_index_t *ix = c->ix;
if (imp->kind == 'w' && jr_is_package(ix, imp->target)) {
jr_cand_type(c, lv, jr_pkg_type(ix, imp->target, name));
}
int type = jr_ent(ix, imp->target); /* `import a.Outer.*;`, `import static a.B.*;` */
if (type != JR_NONE) {
jr_cand_type(c, lv, jr_member_type(c, type, name));
}
}
/* A simple type name in a Java file, in javac's order. */
static jr_lk_t jr_java_type_lookup(const jr_ctx_t *c, const char *name, jr_cands_t *out) {
const jr_index_t *ix = c->ix;
const jr_file_t *f = c->f;
jr_cands_t lv = {0};
bool invisible = false;
memset(out, 0, sizeof(*out));
if (c->member && jr_listed(c->member->tparams, name)) {
return JR_LK_LOCAL; /* the method's own type variable */
}
/* enclosing types, innermost first: the type and its member types, its
* type variables, the member types it inherits */
for (int i = 0; i < c->nchain; i++) {
int ent = c->chain[i];
if (strcmp(ix->ents[ent].name, name) == 0) {
jr_cand_type(c, &lv, ent);
}
jr_cand_type(c, &lv, jr_nested(ix, ent, name));
if (jr_level_done(&lv, out, &invisible)) {
return JR_LK_FOUND;
}
if (jr_listed(c->chain_decl[i]->tparams, name)) {
return JR_LK_LOCAL;
}
const jr_entity_t *e = &ix->ents[ent];
for (int k = 0; c->inherit && k < e->nclosure && lv.count == 0; k++) {
jr_cand_type(c, &lv, jr_nested(ix, e->closure[k], name));
}
if (jr_level_done(&lv, out, &invisible)) {
return JR_LK_FOUND;
}
}
/* the file's own top-level types and its single imports */
int same = jr_pkg_type(ix, f->package, name);
if (same != JR_NONE && jr_declared_in(ix, same, c->file)) {
jr_cand_type(c, &lv, same);
}
for (const jr_import_t *imp = jr_import_next(f, name, NULL); imp;
imp = jr_import_next(f, name, imp)) {
if (imp->kind == 's') {
jr_cand_import_type(c, &lv, imp->target);
continue;
}
/* `import static a.B.name;` imports the member TYPE of that name too */
int owner = jr_ent(ix, imp->target);
if (owner != JR_NONE) {
jr_cand_type(c, &lv, jr_member_type(c, owner, name));
} else {
/* a member of a type no scope shows: whatever it is, it is not
* one of the repository's known declarations */
char pkg[JR_KEY_BUF];
if (!jr_package_of(imp->target, pkg, sizeof(pkg))) {
pkg[0] = '\0';
}
jr_cand(&lv, jr_unseen_kind(ix, pkg), JR_NONE);
}
}
if (lv.count > 0) {
lv.exact = true;
}
if (jr_level_done(&lv, out, &invisible)) {
return JR_LK_FOUND;
}
/* the file's package */
jr_cand_type(c, &lv, same);
if (jr_level_done(&lv, out, &invisible)) {
return JR_LK_FOUND;
}
/* on-demand imports; java.lang is one of them */
for (int i = 0; i < f->nwild; i++) {
jr_java_on_demand(c, &lv, &f->wild[i], name);
}
int lang = jr_pkg_type(ix, "java.lang", name);
if (lang != JR_NONE) {
jr_cand_type(c, &lv, lang);
} else if (JR_NAMED(JR_JAVA_LANG, name)) {
jr_cand(&lv, 'X', JR_NONE);
}
if (jr_level_done(&lv, out, &invisible)) {
return JR_LK_FOUND;
}
return invisible ? JR_LK_INVISIBLE : JR_LK_NONE;
}
/* A (qualified) type name in a Java file: the head through the scope, the
* rest as member types; a head no scope level has is read from the root, as
* packages and then a type. */
static jr_tp_t jr_java_type_path(const jr_ctx_t *c, char *const *segs, int n) {
const jr_index_t *ix = c->ix;
jr_cands_t cands;
jr_lk_t lk = jr_java_type_lookup(c, segs[0], &cands);
if (lk == JR_LK_LOCAL) {
return jr_tp_res((jr_res_t){.st = JR_LOCAL});
}
if (lk == JR_LK_INVISIBLE) {
return jr_tp_res(jr_unres(CBM_DOCLINK_REASON_TEST_ONLY));
}
if (lk == JR_LK_FOUND) {
if (cands.count > SKIP_ONE) {
return jr_tp_res(jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS));
}
if (cands.kind != 'T') {
return jr_tp_res(jr_unres(jr_kind_reason(cands.kind)));
}
return jr_walk_nested(c, cands.ent, segs, SKIP_ONE, n, cands.exact);
}
for (int i = SKIP_ONE; i < n; i++) {
char pkg[JR_KEY_BUF];
if (!jr_join(segs, 0, i, pkg, sizeof(pkg))) {
break;
}
int ent = jr_pkg_type(ix, pkg, segs[i]);
if (ent == JR_NONE || ix->ents[ent].kind == 't') {
continue;
}
if (!jr_visible(c, ent)) {
return jr_tp_res(jr_unres(CBM_DOCLINK_REASON_TEST_ONLY));
}
return jr_walk_nested(c, ent, segs, i + SKIP_ONE, n, true);
}
return jr_tp_res(jr_unfound_path(c, segs, n));
}
/* True when a record declaration of `ent` has exactly the written parameter
* list as its components. */
static bool jr_record_canonical(const jr_ctx_t *c, int ent, const jr_ref_t *r) {
const jr_index_t *ix = c->ix;
const jr_entity_t *e = &ix->ents[ent];
for (int d = 0; d < e->ndecls; d++) {
const jr_file_t *f = &ix->files[e->decls[d].file];
if (f->types[e->decls[d].type].kind == 'r' && !(c->prod && f->is_test) &&
jr_canonical_match(f, e->decls[d].type, r)) {
return true;
}
}
return false;
}
/* `Type#Type(..)` and `#Type(..)`: the constructors of that type alone; none
* is inherited. A constructor the type has without declaring it (the default
* one, a record's canonical one) has no node. */
static jr_res_t jr_java_ctor(const jr_ctx_t *c, int ent, const jr_ref_t *r, bool exact) {
const jr_entity_t *e = &c->ix->ents[ent];
bool params = r->has_params;
jr_found_t all = jr_members(c, ent, e->name, JR_SEL_CTORS, r);
if (!params && all.count > 0) {
return all.several ? jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS) : jr_found_result(&all, exact);
}
if (params) {
jr_found_t sel = jr_members(c, ent, e->name, JR_SEL_CTORS | JR_SEL_SIG, r);
if (sel.count > 0) {
return jr_found_result(&sel, exact);
}
if (sel.uncompared) {
return jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS);
}
}
if (e->incomplete) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
if (all.count == 0 && all.invisible) {
return jr_unres(CBM_DOCLINK_REASON_TEST_ONLY);
}
bool has_ctors = e->kind == 'c' || e->kind == 'e' || e->kind == 'r';
if (has_ctors && params && jr_record_canonical(c, ent, r)) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
if (has_ctors && all.count == 0 && (!params || (r->nparams == 0 && e->kind != 'r'))) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
return jr_unres(CBM_DOCLINK_REASON_MISSING);
}
/* A method reference's outcome from javadoc's search `w` from `base`; `vs`:
* the field search that came first, if any. A search that ended at a method
* javadoc would link that the repository does not show is external; when a
* method of the repository lies further on, the count says so. */
static jr_res_t jr_java_method(const jr_ctx_t *c, int base, const char *name, int sel,
const jr_ref_t *r, const jr_walk_t *w, const jr_msearch_t *vs,
bool exact) {
if (w->kind == JR_WK_FOUND) {
/* without a list, several signatures are an overload group */
return (!(sel & JR_SEL_SIG) && w->found.several) ? jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS)
: jr_found_result(&w->found, exact);
}
if (w->kind == JR_WK_GAP) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
if (w->invisible || (vs && vs->invisible)) {
return jr_unres(CBM_DOCLINK_REASON_TEST_ONLY);
}
if (w->kind == JR_WK_UNCOMPARED || w->kind == JR_WK_LIMIT) {
return jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS);
}
if (w->kind == JR_WK_GIVEN || w->kind == JR_WK_OUTSIDE) {
jr_walk_t further;
jr_walk(c, base, name, sel, r, JR_NONE, true, &further);
if (further.kind == JR_WK_FOUND) {
jr_stats_t *st = c->ix->stats;
atomic_fetch_add(w->kind == JR_WK_GIVEN ? &st->java_given : &st->java_open, 1);
}
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
if (jr_implicit_member(c->ix, base, name) || (vs && vs->open)) {
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
return jr_unres(CBM_DOCLINK_REASON_MISSING);
}
/* A field `vs` that javadoc's field search found for a reference without a
* parameter list, weighed against javadoc's search for a METHOD of the name
* from `start` (jr_walk). javadoc takes the field when no method is found, or
* when the field's class is the method's class or below it
* (JavacTrees.attributeDocReference, read in the JDK 21 source on
* 2026-10-04). So the field binds only when that holds whatever the steps the
* index cannot see hold:
* - a step outside the repository may hold the method; the field's class
* must be below the type the step belongs to (then it is below the
* outside type as well), and the search goes on past it;
* - a method the language gives is weighed like a declared one: Object's
* never stops the field; Enum's or Annotation's only an enum's or an
* annotation type's; a record's or an enum's own implicit one, a field
* of that type or below it;
* - against a method of the repository the field binds when its class is
* below the method's class. Otherwise, with nothing the index cannot see
* before that method, javadoc links the method, and so does the reference
* (the lead's ruling of 2026-10-04: a certain binding), with the tier of
* a member the search finds; an overload group without a list stays
* ambiguous, as for any method. If a step outside was passed, the method
* there may be the one: external;
* - a type whose members a parse error hides may hold the method: a graph
* gap, unless the field's class is below it (then it is passed, and only
* a field outcome survives it).
* *yielded: the field was not taken because of what lies outside. */
static jr_res_t jr_java_field(const jr_ctx_t *c, int start, const char *name, const jr_ref_t *r,
const jr_msearch_t *vs, bool exact, bool *yielded) {
const jr_index_t *ix = c->ix;
int cf = vs->ent;
char cf_kind = ix->ents[cf].kind;
jr_walk_t w;
jr_walk(c, start, name, JR_SEL_CALLABLES, r, cf, false, &w);
bool field = false;
int reason = CBM_DOCLINK_REASON_EXTERNAL;
switch (w.kind) {
case JR_WK_NONE:
field = true;
break;
case JR_WK_FOUND:
field = jr_is_or_extends(ix, cf, w.ent);
if (!field && !w.passed_outside && !w.passed_gap) {
return w.found.several ? jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS)
: jr_found_result(&w.found, exact);
}
break;
case JR_WK_GIVEN:
field = w.ent == JR_W_OBJECT || (w.ent == JR_W_ENUM && cf_kind == 'e') ||
(w.ent == JR_W_ANNOTATION && cf_kind == 'a') ||
(w.ent >= 0 && jr_is_or_extends(ix, cf, w.ent));
break;
case JR_WK_OUTSIDE:
break;
case JR_WK_GAP:
reason = CBM_DOCLINK_REASON_GRAPH_GAP;
break;
default: /* a Kotlin declaration (only with a list), or too many types */
reason = CBM_DOCLINK_REASON_AMBIGUOUS;
break;
}
if (field) {
return jr_found_result(&vs->found, exact);
}
if (w.passed_gap) {
reason = CBM_DOCLINK_REASON_GRAPH_GAP;
}
*yielded = reason == CBM_DOCLINK_REASON_EXTERNAL;
return jr_unres(reason);
}
/* The scope of `Type#x`: the type named and the types around it, innermost
* first. javadoc's field search goes through them as it does for `#x`. */
static void jr_ctx_named(jr_ctx_t *tc, const jr_ctx_t *c, int type) {
*tc = *c;
tc->nchain = 0;
for (int t = type; t != JR_NONE && tc->nchain < JR_CHAIN_MAX; t = c->ix->ents[t].encl) {
tc->chain[tc->nchain] = t;
tc->chain_decl[tc->nchain] = NULL;
tc->nchain++;
}
}
/* A Javadoc member reference. `type` is the type it names, or JR_NONE for
* `#member`, which starts at the type of the documented definition.
* - a METHOD is javadoc's search (jr_walk): the first method it finds is the
* one; a type outside the repository on the way, or a method the language
* gives, ends it as external; a parameter list selects the overloads with
* that signature, never another overload, and without one several
* signatures are ambiguous
* - without a list a FIELD comes first. javadoc looks for one in the type,
* then in the types around it, then in the supertypes; javac scoping
* takes the inherited one first: an inherited field binds only when no
* type further out has one of that name (else ambiguous). The field is
* then weighed against the method (jr_java_field)
* - {@value} names a field and nothing else; for `Type#x` it searches the
* type and its supertypes only, as before */
static jr_res_t jr_java_member(const jr_ctx_t *c, const char *name, const jr_ref_t *r, int type,
bool params, bool exact, bool values_only) {
const jr_index_t *ix = c->ix;
bool in_scope = type == JR_NONE;
int base = in_scope ? (c->nchain > 0 ? c->chain[0] : JR_NONE) : type;
if (base == JR_NONE) {
return jr_unres(CBM_DOCLINK_REASON_MISSING); /* no type to be a member of */
}
if (!values_only && strcmp(name, ix->ents[base].name) == 0) {
return jr_java_ctor(c, base, r, exact);
}
int sel = JR_SEL_CALLABLES | (params ? JR_SEL_SIG : 0);
jr_walk_t mw; /* the method, as javadoc searches for it */
memset(&mw, 0, sizeof(mw));
mw.ent = JR_NONE;
if (params) {
jr_walk(c, base, name, sel, r, JR_NONE, false, &mw);
return jr_java_method(c, base, name, sel, r, &mw, NULL, exact);
}
jr_ctx_t named;
const jr_ctx_t *fc = c; /* the chain the field is searched through */
if (!in_scope && !values_only) {
jr_ctx_named(&named, c, base);
fc = &named;
}
bool chain = in_scope || !values_only;
jr_msearch_t vs;
int vlevel = 0;
if (chain) {
jr_fields_around(fc, name, &vs, &vlevel);
} else {
jr_fields_in(c, base, name, &vs);
}
if (vs.ent != JR_NONE) {
for (int j = vlevel + SKIP_ONE;
chain && vs.ent != fc->chain[vlevel] && !vs.clash && j < fc->nchain; j++) {
jr_msearch_t outer;
jr_fields_in(fc, fc->chain[j], name, &outer);
vs.clash = outer.ent != JR_NONE || outer.gap;
}
if (vs.clash) {
return jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS);
}
if (values_only) {
return jr_found_result(&vs.found, exact);
}
bool yielded = false;
jr_res_t res = jr_java_field(c, base, name, r, &vs, exact, &yielded);
if (yielded) {
atomic_fetch_add(in_scope ? &ix->stats->java_field : &ix->stats->java_field_named, 1);
}
return res;
}
if (vs.gap) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP); /* a hidden field would come first */
}
if (!values_only) {
jr_walk(c, base, name, sel, r, JR_NONE, false, &mw);
}
return jr_java_method(c, base, name, sel, r, &mw, &vs, exact);
}
static jr_res_t jr_java_resolve(const jr_ctx_t *c, const jr_ref_t *r, bool values_only) {
if (r->nsegs == 0) {
return jr_java_member(c, r->member, r, JR_NONE, r->has_params, false, values_only);
}
jr_tp_t tp = jr_java_type_path(c, r->segs, r->nsegs);
if (r->member) {
if (tp.st == JR_TP_OK) {
return jr_java_member(c, r->member, r, tp.ent, r->has_params, tp.exact, values_only);
}
/* a member type the named type does not have: javadoc finds no type */
return tp.st == JR_TP_PARTIAL ? jr_unres(CBM_DOCLINK_REASON_MISSING) : tp.res;
}
if (tp.st == JR_TP_OK) {
return values_only ? jr_unres(CBM_DOCLINK_REASON_MISSING)
: jr_type_result(c, tp.ent, tp.exact);
}
if (tp.st == JR_TP_PARTIAL) {
return jr_unres(CBM_DOCLINK_REASON_MISSING); /* `Type.member`: Javadoc wants a '#' */
}
if (r->nsegs == SKIP_ONE && tp.res.st == JR_UNRES &&
tp.res.reason == CBM_DOCLINK_REASON_MISSING) {
/* javadoc's own fixup: a bare identifier that is no type is read as
* `#identifier`, a member in the enclosing types. Only where the scope
* is closed: an open one may hold a type of that name, which comes
* first. */
jr_res_t m = jr_java_member(c, r->segs[0], r, JR_NONE, false, false, values_only);
if (!(m.st == JR_UNRES && m.reason == CBM_DOCLINK_REASON_MISSING)) {
return m;
}
}
return tp.res;
}
/* ── Kotlin ──────────────────────────────────────────────────────── */
/* The packages every Kotlin file imports on demand. */
static const char *const JR_KOTLIN_DEFAULT_PKGS[] = {
"kotlin", "kotlin.annotation", "kotlin.collections", "kotlin.comparisons", "kotlin.io",
"kotlin.ranges", "kotlin.sequences", "kotlin.text", "java.lang", "kotlin.jvm"};
/* What one scope level holds under a name: types, properties, functions. */
typedef struct {
jr_cands_t types;
jr_found_t vals;
jr_found_t calls;
bool clash; /* two supertypes declare the name and neither comes first */
} jr_klevel_t;
static bool jr_kl_any(const jr_klevel_t *lv) {
return lv->types.count > 0 || lv->vals.count > 0 || lv->calls.count > 0;
}
static bool jr_kl_invisible(const jr_klevel_t *lv) {
return lv->types.invisible || lv->vals.invisible || lv->calls.invisible;
}
/* The members `name` of type `ent`, joined to the level. */
static void jr_kl_members(const jr_ctx_t *c, jr_klevel_t *lv, int ent, const char *name) {
jr_found_t v = jr_members(c, ent, name, JR_SEL_VALUES, NULL);
jr_found_t k = jr_members(c, ent, name, JR_SEL_CALLABLES, NULL);
jr_found_add(c, &lv->vals, &v, false);
jr_found_add(c, &lv->calls, &k, false);
}
/* The top-level declarations `name` of package `pkg`, joined to the level. */
static void jr_kl_top(const jr_ctx_t *c, jr_klevel_t *lv, const char *pkg, const char *name) {
jr_found_t v = jr_top_members(c, pkg, name, JR_SEL_VALUES);
jr_found_t k = jr_top_members(c, pkg, name, JR_SEL_CALLABLES);
jr_found_add(c, &lv->vals, &v, false);
jr_found_add(c, &lv->calls, &k, false);
}
/* The type `name` nested in `ent`; through a type alias, in the type it
* names. */
static int jr_kotlin_nested(const jr_index_t *ix, int ent, const char *name) {
int n = jr_nested(ix, ent, name);
const jr_entity_t *e = &ix->ents[ent];
if (n == JR_NONE && e->kind == 't' && e->nclosure > 0) {
n = jr_nested(ix, e->closure[0], name);
}
return n;
}
/* What type `ent` holds under `name` itself: a nested type, its members, and
* the same of its companion object. One level: a class's member scope and its
* companion's are one scope to a KDoc name. */
static void jr_kl_type_scope(const jr_ctx_t *c, jr_klevel_t *lv, int ent, const char *name,
bool members) {
const jr_index_t *ix = c->ix;
jr_cand_type(c, &lv->types, jr_kotlin_nested(ix, ent, name));
if (members) {
jr_kl_members(c, lv, ent, name);
}
int comp = ix->ents[ent].companion;
if (comp != JR_NONE) {
jr_cand_type(c, &lv->types, jr_nested(ix, comp, name));
if (members) {
jr_kl_members(c, lv, comp, name);
}
}
}
/* What the supertypes of `ent` hold under `name`: the nearest one that has
* anything (`types`: nested types, `members`: properties and functions). A
* further one that the nearest does not extend is a clash. *gap: a supertype
* with members a parse error hides came before any hit. */
static void jr_kl_inherited(const jr_ctx_t *c, jr_klevel_t *lv, int ent, const char *name,
bool types, bool members, bool *gap) {
const jr_index_t *ix = c->ix;
const jr_entity_t *e = &ix->ents[ent];
int first = JR_NONE;
int checks = 0;
bool invisible = false;
for (int k = 0; k < e->nclosure; k++) {
int sup = e->closure[k];
jr_klevel_t one;
memset(&one, 0, sizeof(one));
if (types) {
jr_cand_type(c, &one.types, jr_nested(ix, sup, name));
}
if (members) {
jr_kl_members(c, &one, sup, name);
}
if (!jr_kl_any(&one)) {
invisible = invisible || jr_kl_invisible(&one);
if (first == JR_NONE && members && ix->ents[sup].incomplete) {
*gap = true;
break;
}
continue;
}
if (first == JR_NONE) {
*lv = one;
first = sup;
} else if (++checks > JR_CLASH_CHECKS || !jr_is_or_extends(ix, first, sup)) {
lv->clash = true;
break;
}
}
lv->types.invisible = lv->types.invisible || invisible;
}
/* What an explicit import of `fqn` puts in scope: a type, the top-level
* declarations of that name, a member of an object or an enum. When no scope
* shows anything of that name it is either declared by the repository where
* no scope sees it (its package or type is the repository's), or outside. */
static void jr_kl_import(const jr_ctx_t *c, jr_klevel_t *lv, const char *fqn, bool members) {
const jr_index_t *ix = c->ix;
const char *dot = strrchr(fqn, '.');
const char *last = dot ? dot + SKIP_ONE : fqn;
char pkg[JR_KEY_BUF];
bool has_pkg = jr_package_of(fqn, pkg, sizeof(pkg));
if (!has_pkg) {
pkg[0] = '\0';
}
jr_klevel_t one;
memset(&one, 0, sizeof(one));
jr_cand_type(c, &one.types, jr_ent(ix, fqn));
jr_kl_top(c, &one, pkg, last);
int owner = has_pkg ? jr_ent(ix, pkg) : JR_NONE;
if (owner != JR_NONE) {
jr_kl_members(c, &one, owner, last);
}
if (!jr_kl_any(&one)) {
if (jr_kl_invisible(&one)) {
lv->types.invisible = true;
return;
}
jr_cand(&lv->types, jr_unseen_kind(ix, pkg), JR_NONE);
return;
}
if (one.types.count > 0) {
jr_cand(&lv->types, one.types.kind, one.types.ent);
}
if (members) {
jr_found_add(c, &lv->vals, &one.vals, false);
jr_found_add(c, &lv->calls, &one.calls, false);
}
}
/* True when the member scope of `ent` is not fully known: the type or its
* companion object has a supertype outside the repository, directly or
* further up. */
static bool jr_scope_unknown(const jr_index_t *ix, int ent) {
int comp = ix->ents[ent].companion;
return jr_open(ix, ent) || (comp != JR_NONE && jr_open(ix, comp));
}
/* Why a Kotlin lookup passed an enclosing type that may have the member
* unseen (jr_kotlin_lookup). */
enum { JR_STOP_NO = 0, JR_STOP_GIVEN, JR_STOP_OPEN };
/* A simple name in a Kotlin file, level by level:
* the documented definition's own parameters and type parameters, `this`
* each enclosing type, innermost first: what it holds itself (with its
* companion), its type parameters and constructor parameters, what it
* inherits, what its companion inherits
* explicit imports -> the file's package -> star imports -> default imports
* `members` false: types only (the head of a qualified name, a supertype).
* *gap: a type with members a parse error hides was passed without a hit; a
* member found after it may be shadowed by one of those.
* *stop (JR_STOP_*): an enclosing type was passed without a hit that may have
* a member of the name unseen (jr_kotlin_simple); what the lookup returns
* then lies further out than that type. */
static jr_lk_t jr_kotlin_lookup(const jr_ctx_t *c, const char *name, bool members, jr_klevel_t *out,
bool *exact, bool *gap, int *stop) {
const jr_index_t *ix = c->ix;
const jr_file_t *f = c->f;
jr_klevel_t lv;
bool invisible = false;
memset(out, 0, sizeof(*out));
*exact = false;
*gap = false;
*stop = JR_STOP_NO;
if (c->member &&
(jr_listed(c->member->tparams, name) || (members && jr_listed(c->member->pnames, name)))) {
return JR_LK_LOCAL;
}
/* a documented class: every parameter of its primary constructor is its
* own, a `val` one included (seen from a member's doc that one is a
* property of the class, further down) */
if (c->type &&
(jr_listed(c->type->tparams, name) || (members && jr_listed(c->type->pnames, name)))) {
return JR_LK_LOCAL;
}
if (members && strcmp(name, "this") == 0) {
return JR_LK_LOCAL;
}
for (int i = 0; i < c->nchain; i++) {
int ent = c->chain[i];
const jr_type_t *decl = c->chain_decl[i];
memset(&lv, 0, sizeof(lv));
if (strcmp(ix->ents[ent].name, name) == 0) {
jr_cand_type(c, &lv.types, ent);
}
jr_kl_type_scope(c, &lv, ent, name, members);
if (jr_kl_any(&lv)) {
*out = lv;
return JR_LK_FOUND;
}
invisible = invisible || jr_kl_invisible(&lv);
if (jr_listed(decl->tparams, name) || (members && jr_listed(decl->pnames, name))) {
return JR_LK_LOCAL;
}
if (members && ix->ents[ent].incomplete) {
*gap = true;
}
if (!c->inherit) {
continue;
}
memset(&lv, 0, sizeof(lv));
jr_kl_inherited(c, &lv, ent, name, true, members, gap);
if (jr_kl_any(&lv)) {
*out = lv;
return JR_LK_FOUND;
}
invisible = invisible || jr_kl_invisible(&lv);
if (!members) {
continue;
}
/* the companion's member scope is part of the class's, with what the
* companion inherits */
int comp = ix->ents[ent].companion;
if (comp != JR_NONE) {
memset(&lv, 0, sizeof(lv));
jr_kl_inherited(c, &lv, comp, name, false, true, gap);
if (jr_kl_any(&lv)) {
*out = lv;
return JR_LK_FOUND;
}
invisible = invisible || jr_kl_invisible(&lv);
}
if (*stop == JR_STOP_NO) {
*stop = jr_given_member(c, ent, name) ? JR_STOP_GIVEN
: jr_scope_unknown(ix, ent) ? JR_STOP_OPEN
: JR_STOP_NO;
}
}
/* explicit imports */
memset(&lv, 0, sizeof(lv));
for (const jr_import_t *imp = jr_import_next(f, name, NULL); imp;
imp = jr_import_next(f, name, imp)) {
jr_kl_import(c, &lv, imp->target, members);
}
if (jr_kl_any(&lv)) {
*out = lv;
*exact = true;
return JR_LK_FOUND;
}
invisible = invisible || jr_kl_invisible(&lv);
/* the file's package */
memset(&lv, 0, sizeof(lv));
jr_cand_type(c, &lv.types, jr_pkg_type(ix, f->package, name));
if (members) {
jr_kl_top(c, &lv, f->package, name);
}
if (jr_kl_any(&lv)) {
*out = lv;
return JR_LK_FOUND;
}
invisible = invisible || jr_kl_invisible(&lv);
/* star imports: of a package, or of a type (its nested types and members) */
memset(&lv, 0, sizeof(lv));
for (int i = 0; i < f->nwild; i++) {
const char *target = f->wild[i].target;
if (jr_is_package(ix, target)) {
jr_cand_type(c, &lv.types, jr_pkg_type(ix, target, name));
if (members) {
jr_kl_top(c, &lv, target, name);
}
}
int type = jr_ent(ix, target);
if (type != JR_NONE) {
jr_cand_type(c, &lv.types, jr_kotlin_nested(ix, type, name));
if (members) {
jr_kl_members(c, &lv, type, name);
}
}
}
if (jr_kl_any(&lv)) {
*out = lv;
return JR_LK_FOUND;
}
invisible = invisible || jr_kl_invisible(&lv);
/* default imports: the repository's own declarations there first */
memset(&lv, 0, sizeof(lv));
for (size_t i = 0; i < sizeof(JR_KOTLIN_DEFAULT_PKGS) / sizeof(JR_KOTLIN_DEFAULT_PKGS[0]);
i++) {
jr_cand_type(c, &lv.types, jr_pkg_type(ix, JR_KOTLIN_DEFAULT_PKGS[i], name));
if (members) {
jr_kl_top(c, &lv, JR_KOTLIN_DEFAULT_PKGS[i], name);
}
}
if (!jr_kl_any(&lv) && (JR_NAMED(JR_KOTLIN_DEFAULT, name) || JR_NAMED(JR_JAVA_LANG, name))) {
jr_cand(&lv.types, 'X', JR_NONE);
}
if (jr_kl_any(&lv)) {
*out = lv;
return JR_LK_FOUND;
}
invisible = invisible || jr_kl_invisible(&lv);
return invisible ? JR_LK_INVISIBLE : JR_LK_NONE;
}
/* What a level with candidates is: one type, one property or one function.
*
* A type and a function of one name at one level (the factory-function
* idiom, `class Json` beside `fun Json(..)`) are the TYPE. The order relied
* on: KDoc's link resolution asks a scope for the classifier of a name before
* it asks for functions and properties, and the documentation tool links the
* first answer. That is stated from knowledge of the Kotlin documentation
* tooling (the compiler's KDoc link resolver, which Dokka uses); it was not
* checked online. The type binds with the tier the lookup gave. A type whose
* node another declaration took (class and factory in one file share the
* file-based qualified name, and the later one owns it) is a graph gap: the
* function never stands in for it. However many overloads the function has
* makes no difference. `@sample` names a function, so that order says nothing
* about it: there a type and a function of one name stay ambiguous.
*
* Everything else with more than one candidate is ambiguous, never a pick: a
* property and a function, a type and a property, a second type, an overload
* group, members of two owners. */
static jr_res_t jr_kl_result(const jr_ctx_t *c, const jr_klevel_t *lv, bool exact) {
int kinds = (lv->types.count > 0) + (lv->vals.count > 0) + (lv->calls.count > 0);
if (!c->sample && lv->types.count == SKIP_ONE && lv->types.kind == 'T' && lv->calls.count > 0 &&
lv->vals.count == 0 && !lv->clash) {
jr_res_t type = jr_type_result(c, lv->types.ent, exact);
atomic_fetch_add(&c->ix->stats->type_and_function, 1);
if (type.st == JR_OK) {
atomic_fetch_add(&c->ix->stats->type_and_function_node, 1);
}
return type;
}
if (kinds > SKIP_ONE || lv->types.count > SKIP_ONE || lv->clash) {
return jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS);
}
if (lv->types.count == SKIP_ONE) {
if (lv->types.kind == 'T') {
return jr_type_result(c, lv->types.ent, exact);
}
return jr_unres(jr_kind_reason(lv->types.kind));
}
const jr_found_t *m = lv->vals.count > 0 ? &lv->vals : &lv->calls;
return m->several ? jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS) : jr_found_result(m, exact);
}
/* A simple KDoc name.
*
* A function or a property further out than an enclosing type binds only when
* that type is known not to have a member of the name. KDoc resolves a name
* in the member scope of each enclosing class, inherited members included,
* before it looks at the class around it, the file's imports or its package.
* So when the lookup passed a type
* - that has the name without declaring it (jr_given_member: a member of
* kotlin.Any, of an enum class), or
* - whose supertypes, or whose companion's, leave the repository
* (jr_scope_unknown): one of them may declare the name,
* a function or a property found further out is not taken: the reference is
* `external`, and so is a name found nowhere. The order relied on is stated
* from knowledge of the Kotlin documentation tooling (the compiler's KDoc
* link resolver); it was not checked online.
* A TYPE found further out binds as before: the guard is about the member
* functions and properties a type has, not about nested types a supertype
* outside the repository might lend. */
static jr_res_t jr_kotlin_simple(const jr_ctx_t *c, const char *name) {
jr_klevel_t lv;
bool exact = false;
bool gap = false;
int stop = JR_STOP_NO;
jr_lk_t lk = jr_kotlin_lookup(c, name, true, &lv, &exact, &gap, &stop);
if (lk == JR_LK_LOCAL) {
return (jr_res_t){.st = JR_LOCAL};
}
if (lk == JR_LK_INVISIBLE) {
return jr_unres(CBM_DOCLINK_REASON_TEST_ONLY);
}
if (lk == JR_LK_FOUND) {
/* a member found past a type with hidden members: one of those may
* be the one. A type is safe: a type declared where the scan lost its
* place is quarantined by name. */
if (gap && lv.types.count == 0) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
if (stop != JR_STOP_NO && lv.types.count == 0) {
jr_stats_t *st = c->ix->stats;
atomic_fetch_add(stop == JR_STOP_GIVEN ? &st->kotlin_given : &st->kotlin_open, 1);
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
return jr_kl_result(c, &lv, exact);
}
if (stop != JR_STOP_NO) {
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL); /* the member that type may have */
}
jr_res_t res = jr_unfound_simple(c, name);
return (gap && res.reason == CBM_DOCLINK_REASON_MISSING)
? jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP)
: res;
}
/* A (qualified) type name in a Kotlin file: the head through the scope or,
* when no level has it, from the root as packages and then a type; the rest
* as nested types. */
static jr_tp_t jr_kotlin_type_path(const jr_ctx_t *c, char *const *segs, int n) {
const jr_index_t *ix = c->ix;
jr_klevel_t lv;
bool exact = false;
bool gap = false;
int stop = JR_STOP_NO; /* types only: nothing to hold back */
jr_lk_t lk = jr_kotlin_lookup(c, segs[0], false, &lv, &exact, &gap, &stop);
if (lk == JR_LK_LOCAL) {
return jr_tp_res((jr_res_t){.st = JR_LOCAL});
}
if (lk == JR_LK_INVISIBLE) {
return jr_tp_res(jr_unres(CBM_DOCLINK_REASON_TEST_ONLY));
}
int cur = JR_NONE;
int from = SKIP_ONE;
if (lk == JR_LK_FOUND) {
if (lv.types.count > SKIP_ONE) {
return jr_tp_res(jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS));
}
if (lv.types.kind != 'T') {
return jr_tp_res(jr_unres(jr_kind_reason(lv.types.kind)));
}
cur = lv.types.ent;
}
for (int i = SKIP_ONE; cur == JR_NONE && i < n; i++) {
char pkg[JR_KEY_BUF];
if (!jr_join(segs, 0, i, pkg, sizeof(pkg))) {
break;
}
int ent = jr_pkg_type(ix, pkg, segs[i]);
if (ent == JR_NONE) {
continue;
}
if (!jr_visible(c, ent)) {
return jr_tp_res(jr_unres(CBM_DOCLINK_REASON_TEST_ONLY));
}
cur = ent;
from = i + SKIP_ONE;
exact = true;
}
if (cur == JR_NONE) {
jr_tp_t tp = jr_tp_res(jr_unfound_path(c, segs, n));
tp.unfound = true;
return tp;
}
for (int i = from; i < n; i++) {
int next = jr_kotlin_nested(ix, cur, segs[i]);
if (next == JR_NONE) {
return (jr_tp_t){.st = JR_TP_PARTIAL, .ent = cur, .failed_seg = i, .exact = exact};
}
if (!jr_visible(c, next)) {
return jr_tp_res(jr_unres(CBM_DOCLINK_REASON_TEST_ONLY));
}
cur = next;
}
return (jr_tp_t){.st = JR_TP_OK, .ent = cur, .exact = exact};
}
static bool jr_ext_key(int recv, const char *name, char *out, size_t cap) {
int n = recv == JR_NONE ? snprintf(out, cap, "?\x1f%s", name)
: snprintf(out, cap, "%d\x1f%s", recv, name);
return n >= 0 && (size_t)n < cap;
}
/* True when the extension `m` of `file` is in scope of the source under its
* simple name: declared in the source's package, imported, or a member of an
* enclosing type. KDoc finds an extension for `Type.name` among the callables
* in scope, nowhere else. */
static bool jr_ext_in_scope(const jr_ctx_t *c, int file, const jr_member_t *m) {
const jr_file_t *xf = &c->ix->files[file];
if (m->owner != JR_NONE) {
int owner = xf->types[m->owner].entity;
for (int i = 0; i < c->nchain; i++) {
if (c->chain[i] == owner) {
return true;
}
}
return false;
}
if (strcmp(xf->package, c->f->package) == 0) {
return true;
}
for (int i = 0; i < c->f->nwild; i++) {
if (strcmp(c->f->wild[i].target, xf->package) == 0) {
return true;
}
}
size_t pl = strlen(xf->package);
for (const jr_import_t *imp = jr_import_next(c->f, m->name, NULL); imp;
imp = jr_import_next(c->f, m->name, imp)) {
const char *t = imp->target;
if (pl == 0 ? strcmp(t, m->name) == 0
: (strncmp(t, xf->package, pl) == 0 && t[pl] == '.' &&
strcmp(t + pl + SKIP_ONE, m->name) == 0)) {
return true;
}
}
return false;
}
/* The extensions `name` in scope whose receiver is `ent`, else one of its
* supertypes (nearest first), else any type. false when there is none. */
static bool jr_kotlin_extension(const jr_ctx_t *c, int ent, const char *name, jr_res_t *res,
bool *invisible) {
const jr_index_t *ix = c->ix;
const jr_entity_t *e = &ix->ents[ent];
for (int k = -1; k <= e->nclosure; k++) {
int recv = k < 0 ? ent : (k < e->nclosure ? e->closure[k] : JR_NONE);
char key[JR_KEY_BUF];
if (!jr_ext_key(recv, name, key, sizeof(key))) {
return false;
}
const jr_ilist_t *l = (const jr_ilist_t *)cbm_ht_get(ix->extensions, key);
jr_found_t found = {0};
const char *package = NULL;
for (int i = 0; l && i + SKIP_ONE < l->count; i += PAIR_LEN) {
int file = l->items[i];
const jr_member_t *m = &ix->files[file].members[l->items[i + SKIP_ONE]];
if (!jr_ext_in_scope(c, file, m)) {
continue;
}
if (c->prod && ix->files[file].is_test) {
*invisible = true;
continue;
}
/* the same name and signature in two packages are two functions */
if (package && strcmp(package, ix->files[file].package) != 0) {
found.several = true;
}
package = ix->files[file].package;
jr_found_take(c, &found, file, m);
}
if (found.count > 0) {
*res = found.several ? jr_unres(CBM_DOCLINK_REASON_AMBIGUOUS)
: jr_found_result(&found, false);
return true;
}
}
return false;
}
/* `name` in the type `ent`, named explicitly: what the type holds itself
* (with its companion), then what it inherits and what its companion
* inherits, the members every type has, and the extensions in scope whose
* receiver it is.
*
* An extension is taken only when the type is known not to have a member of
* the name: a member comes before an extension. Where the supertypes of the
* type, or of its companion, leave the repository (jr_scope_unknown), one of
* them may declare the name: `external`, never the extension. Stated from
* knowledge of the language and of the KDoc link resolver, which asks the
* type's member scope before the extensions in scope; not checked online. */
static jr_res_t jr_kotlin_in_type(const jr_ctx_t *c, int ent, const char *name, bool exact) {
const jr_index_t *ix = c->ix;
jr_klevel_t lv;
bool gap = false;
memset(&lv, 0, sizeof(lv));
jr_kl_type_scope(c, &lv, ent, name, true);
if (jr_kl_any(&lv)) {
return jr_kl_result(c, &lv, exact);
}
bool invisible = jr_kl_invisible(&lv);
if (ix->ents[ent].incomplete) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
memset(&lv, 0, sizeof(lv));
jr_kl_inherited(c, &lv, ent, name, true, true, &gap);
if (jr_kl_any(&lv)) {
return jr_kl_result(c, &lv, exact);
}
invisible = invisible || jr_kl_invisible(&lv);
int comp = ix->ents[ent].companion;
if (comp != JR_NONE && !gap) {
memset(&lv, 0, sizeof(lv));
jr_kl_inherited(c, &lv, comp, name, false, true, &gap);
if (jr_kl_any(&lv)) {
return jr_kl_result(c, &lv, exact);
}
invisible = invisible || jr_kl_invisible(&lv);
}
if (gap) {
return jr_unres(CBM_DOCLINK_REASON_GRAPH_GAP);
}
if (jr_implicit_member(ix, ent, name)) {
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
jr_res_t ext;
bool has_ext = jr_kotlin_extension(c, ent, name, &ext, &invisible);
if (jr_scope_unknown(ix, ent)) {
if (has_ext) {
atomic_fetch_add(&ix->stats->kotlin_extension, 1);
return jr_unres(CBM_DOCLINK_REASON_EXTERNAL);
}
return jr_unres(invisible ? CBM_DOCLINK_REASON_TEST_ONLY : CBM_DOCLINK_REASON_EXTERNAL);
}
if (has_ext) {
return ext;
}
return jr_unres(invisible ? CBM_DOCLINK_REASON_TEST_ONLY : CBM_DOCLINK_REASON_MISSING);
}
/* True when `name` is a parameter or type parameter of the documented
* definition or of a type around it. */
static bool jr_kotlin_local(const jr_ctx_t *c, const char *name) {
if (c->member && (jr_listed(c->member->pnames, name) || jr_listed(c->member->tparams, name))) {
return true;
}
for (int i = 0; i < c->nchain; i++) {
if (jr_listed(c->chain_decl[i]->pnames, name) ||
jr_listed(c->chain_decl[i]->tparams, name)) {
return true;
}
}
return strcmp(name, "this") == 0;
}
/* A dotted KDoc name. The qualifier is a type (found through the scope, or
* from the root) and the last name what that type holds; or the qualifier is
* a package and the last name one of its types or top-level declarations. */
static jr_res_t jr_kotlin_qualified(const jr_ctx_t *c, const jr_ref_t *r) {
const jr_index_t *ix = c->ix;
int n = r->nsegs;
const char *last = r->segs[n - SKIP_ONE];
if (jr_kotlin_local(c, r->segs[0])) {
return (jr_res_t){.st = JR_LOCAL}; /* `param.member` names nothing elsewhere */
}
jr_tp_t qual = jr_kotlin_type_path(c, r->segs, n - SKIP_ONE);
if (qual.st == JR_TP_OK) {
return jr_kotlin_in_type(c, qual.ent, last, qual.exact);
}
if (qual.st == JR_TP_PARTIAL) {
return jr_unres(CBM_DOCLINK_REASON_MISSING); /* a type without that nested type */
}
if (!qual.unfound) {
return qual.res; /* the qualifier is known, and is no type of the repository */
}
char pkg[JR_KEY_BUF];
if (!jr_join(r->segs, 0, n - SKIP_ONE, pkg, sizeof(pkg))) {
return jr_unres(CBM_DOCLINK_REASON_UNPARSEABLE);
}
jr_klevel_t lv;
memset(&lv, 0, sizeof(lv));
jr_cand_type(c, &lv.types, jr_pkg_type(ix, pkg, last));
jr_kl_top(c, &lv, pkg, last);
if (jr_kl_any(&lv)) {
return jr_kl_result(c, &lv, true);
}
if (jr_kl_invisible(&lv)) {
return jr_unres(CBM_DOCLINK_REASON_TEST_ONLY);
}
return jr_unfound_path(c, r->segs, n);
}
static jr_res_t jr_kotlin_resolve(const jr_ctx_t *c, const jr_ref_t *r) {
return r->nsegs == SKIP_ONE ? jr_kotlin_simple(c, r->segs[0]) : jr_kotlin_qualified(c, r);
}
/* ── Context ─────────────────────────────────────────────────────── */
/* True when a declaration with `slot` (see jr_type_t) is the definition whose
* name below the module is `tail`. `path`: its logical path. */
static bool jr_slot_is(const char *slot, const char *owner_path, const char *name,
const char *tail) {
if (!slot) {
return false;
}
if (strcmp(slot, "=") != 0) {
return strcmp(slot, tail) == 0;
}
if (!owner_path) {
return strcmp(name, tail) == 0;
}
size_t ol = strlen(owner_path);
return strncmp(tail, owner_path, ol) == 0 && tail[ol] == '.' &&
strcmp(tail + ol + SKIP_ONE, name) == 0;
}
/* The scope of the definition a reference is written on: the documented
* member or type (found by its line and its name below the module), and the
* types around it. */
static void jr_ctx_init(jr_ctx_t *c, const jr_index_t *ix, const cbm_gbuf_t *g, int file,
const CBMDocLink *link) {
memset(c, 0, sizeof(*c));
c->ix = ix;
c->g = g;
c->file = file;
c->f = &ix->files[file];
c->prod = !c->f->is_test;
c->inherit = true;
if (link->flags & CBM_DOCLINK_FLAG_FILE) {
return; /* a file-level doc: the file's scope alone */
}
const jr_file_t *f = c->f;
uint32_t line = link->def_line;
size_t ml = strlen(f->module_qn);
const char *qn = link->source_qn;
const char *tail =
(qn && strncmp(qn, f->module_qn, ml) == 0 && qn[ml] == '.') ? qn + ml + SKIP_ONE : NULL;
int lo = 0;
int hi = f->nmembers;
while (lo < hi) {
int mid = lo + ((hi - lo) / PAIR_LEN);
if (f->members[f->by_start[mid]].start < line) {
lo = mid + SKIP_ONE;
} else {
hi = mid;
}
}
for (int i = lo; tail && i < f->nmembers; i++) {
const jr_member_t *m = &f->members[f->by_start[i]];
if (m->start != line) {
break;
}
if (jr_slot_is(m->slot, m->owner == JR_NONE ? NULL : f->types[m->owner].path, m->name,
tail)) {
c->member = m;
jr_chain_from(c, m->owner);
return;
}
}
/* types are in source order: the last one that starts at or before the line */
lo = 0;
hi = f->ntypes;
while (lo < hi) {
int mid = lo + ((hi - lo) / PAIR_LEN);
if (f->types[mid].start <= line) {
lo = mid + SKIP_ONE;
} else {
hi = mid;
}
}
int t = lo - SKIP_ONE;
for (int k = t; tail && k >= 0 && f->types[k].start == line; k--) {
if (jr_slot_is(f->types[k].slot, NULL, f->types[k].path, tail)) {
c->type = &f->types[k];
jr_chain_from(c, k);
return;
}
}
/* neither: a definition the scan has no record of. The innermost type
* around its line is its scope. */
while (t >= 0 && f->types[t].end < line) {
t = f->types[t].outer;
}
if (t >= 0) {
jr_chain_from(c, t);
}
}
/* The scope of a type DECLARATION, for the names its header writes
* (supertypes, an extension's receiver): the types around it. From structure
* alone, since a stored scope has no lines. */
static void jr_ctx_decl(jr_ctx_t *c, const jr_index_t *ix, const cbm_gbuf_t *g, int file, int outer,
bool inherit) {
memset(c, 0, sizeof(*c));
c->ix = ix;
c->g = g;
c->file = file;
c->f = &ix->files[file];
c->prod = false; /* a declared supertype is whatever the compiler bound */
c->inherit = inherit;
jr_chain_from(c, outer);
}
/* ── Supertypes, extensions ──────────────────────────────────────── */
/* Split a dotted name in place. Returns the number of names, 0 when there
* are more than a reference may have. */
static int jr_split_dots(char *s, char **segs) {
int n = 0;
for (char *p = s;;) {
char *dot = strchr(p, '.');
if (dot) {
*dot = '\0';
}
if (n >= JR_MAX_SEGS || !p[0]) {
return 0;
}
segs[n++] = p;
if (!dot) {
return n;
}
p = dot + SKIP_ONE;
}
}
/* The type a declaration header of `file` names with `name[0, len)`, in the
* scope `c`; JR_NONE when the repository declares no such type. */
static int jr_header_type(const jr_ctx_t *c, const char *name, size_t len) {
char buf[JR_KEY_BUF];
char *segs[JR_MAX_SEGS];
if (len == 0 || len >= sizeof(buf)) {
return JR_NONE;
}
memcpy(buf, name, len);
buf[len] = '\0';
int n = jr_split_dots(buf, segs);
if (n == 0) {
return JR_NONE;
}
jr_tp_t tp = c->f->kotlin ? jr_kotlin_type_path(c, segs, n) : jr_java_type_path(c, segs, n);
return tp.st == JR_TP_OK ? tp.ent : JR_NONE;
}
/* True when a declaration header of the context's file writes, with
* `name[0, len)`, the root type every type has anyway: java.lang.Object,
* kotlin.Any. Written out it adds no member (jr_given_member knows them), so
* it does not leave the hierarchy open. The simple name counts only where
* nothing else can supply it: no import of that name, no on-demand import of
* a package the repository does not declare. */
static bool jr_root_super(const jr_ctx_t *c, const char *name, size_t len) {
const char *full = c->f->kotlin ? "kotlin.Any" : "java.lang.Object";
const char *simple = strrchr(full, '.') + SKIP_ONE;
if (len == strlen(full) && memcmp(name, full, len) == 0) {
return true;
}
return len == strlen(simple) && memcmp(name, simple, len) == 0 &&
!jr_import_next(c->f, simple, NULL) && !jr_scope_open(c);
}
/* True when the repository's type `step` is an interface to javadoc (an
* annotation type is one). */
static bool jr_walk_iface(const jr_index_t *ix, int step) {
return step >= 0 && (ix->ents[step].kind == 'i' || ix->ents[step].kind == 'a');
}
/* The steps of javadoc's search for a method (jr_walk) at one declaration of
* kind `kind`, from the supertypes its header writes, in the order written
* (`steps[0, nd)`: types of the repository, JR_W_OBJECT for Object or Any
* written out, JR_W_OUTSIDE for any other). Returns the superclass step and
* leaves the interface steps, in order, in steps[0, *n).
* - An interface has no superclass; an annotation type has the interface
* java.lang.annotation.Annotation, an enum the superclass java.lang.Enum,
* a record java.lang.Record (which adds nothing to what the record has
* itself and Object's), any other class Object unless its header names
* another.
* - Java writes the superclass first: a first supertype that is no
* interface of the repository is it. One outside the repository may be
* the superclass or the first interface; it is taken as the superclass,
* the earlier of the two places.
* - Kotlin writes the superclass anywhere in the list: the one class of the
* repository there is it. Without one, a supertype outside the
* repository may be the superclass, which javadoc searches before every
* interface: the superclass step is then outside.
* - A Kotlin type alias is outside to this search. */
static int jr_walk_steps(const jr_index_t *ix, char kind, bool kotlin, int *steps, int nd, int *n) {
int sup = JR_W_OBJECT;
int skip = JR_NONE; /* the entry that is the superclass */
for (int i = 0; i < nd; i++) {
if (steps[i] >= 0 && ix->ents[steps[i]].kind == 't') {
steps[i] = JR_W_OUTSIDE;
}
}
*n = 0;
if (kind == 'i') {
sup = JR_W_NONE;
} else if (kind == 'a') {
sup = JR_W_ANNOTATION;
} else if (kind == 'e') {
sup = JR_W_ENUM;
} else if (kind == 't') {
return JR_W_OUTSIDE;
} else if (kind != 'r' && !kotlin) {
if (nd > 0 && steps[0] != JR_W_OBJECT && !jr_walk_iface(ix, steps[0])) {
sup = steps[0];
skip = 0;
}
} else if (kind != 'r') {
int classes = 0;
bool outside = false;
for (int i = 0; i < nd; i++) {
if (steps[i] >= 0 && !jr_walk_iface(ix, steps[i])) {
classes++;
skip = i;
}
outside = outside || steps[i] == JR_W_OUTSIDE;
}
if (classes > SKIP_ONE) {
return JR_W_OUTSIDE; /* two superclasses: no order to follow */
}
if (classes == SKIP_ONE) {
sup = steps[skip];
} else if (outside) {
sup = JR_W_OUTSIDE;
}
}
int w = 0;
for (int i = 0; i < nd; i++) {
if (i != skip && steps[i] != JR_W_OBJECT) {
steps[w++] = steps[i];
}
}
*n = w;
return sup;
}
/* One declaration's steps into its type's: the first declaration sets them,
* a later one that has other steps or another order leaves the type's place
* in javadoc's search unknown (its superclass step outside). */
static bool jr_walk_decl(jr_index_t *ix, jr_entity_t *e, const jr_type_t *t, bool kotlin,
int *steps, int nd, bool merge) {
int n = 0;
int sup = jr_walk_steps(ix, t->kind, kotlin, steps, nd, &n);
if (!merge) {
e->wsuper = sup;
if (n > 0) {
e->wifaces = (int *)jr_alloc(ix, (size_t)n * sizeof(int));
if (!e->wifaces) {
return false;
}
memcpy(e->wifaces, steps, (size_t)n * sizeof(int));
e->nwifaces = n;
}
return true;
}
if (sup != e->wsuper || n != e->nwifaces ||
(n > 0 && memcmp(steps, e->wifaces, (size_t)n * sizeof(int)) != 0)) {
e->wsuper = JR_W_OUTSIDE;
e->nwifaces = 0;
}
return true;
}
/* The type around declaration `t` of `f`, as the scope chain has it. */
static int jr_walk_encl(const jr_file_t *f, const jr_type_t *t) {
int o = t->outer;
while (o != JR_NONE && f->types[o].entity < 0) {
o = f->types[o].outer;
}
return o == JR_NONE ? JR_NONE : f->types[o].entity;
}
/* The direct supertypes of every type (each declaration's list, bound in that
* declaration's own scope), then every type's closure: breadth-first, the
* nearest first, each supertype once. A supertype that is no type of the
* repository leaves the hierarchy open. Alongside, each type's steps of
* javadoc's search for a method (jr_walk_steps). */
static bool jr_resolve_supers(jr_index_t *ix, const cbm_gbuf_t *g) {
size_t n = (size_t)(ix->nents ? ix->nents : SKIP_ONE);
int *seen = (int *)cbm_calloc(CBM_MEM_CLASS_OTHER, n * sizeof(int));
int *queue = (int *)cbm_alloc(CBM_MEM_CLASS_OTHER, n * sizeof(int));
int *steps = NULL; /* one declaration's supertypes, as javadoc's search sees them */
int scap = 0;
bool ok = seen && queue;
for (int ei = 0; ok && ei < ix->nents; ei++) {
jr_entity_t *e = &ix->ents[ei];
int stamp = ei + SKIP_ONE;
int nb = 0;
for (int d = 0; ok && d < e->ndecls; d++) {
int file = e->decls[d].file;
const jr_type_t *t = &ix->files[file].types[e->decls[d].type];
jr_ctx_t c;
if (t->supers[0]) {
jr_ctx_decl(&c, ix, g, file, t->outer, false);
}
int nd = 0;
for (const char *p = t->supers; ok && p && *p;) {
const char *bar = strchr(p, '|');
size_t len = bar ? (size_t)(bar - p) : strlen(p);
int base = jr_header_type(&c, p, len);
int step = base;
if (base == ei) {
e->open = true;
step = JR_W_OUTSIDE;
} else if (base == JR_NONE) {
bool root = jr_root_super(&c, p, len);
e->open = e->open || !root;
step = root ? JR_W_OBJECT : JR_W_OUTSIDE;
} else if (seen[base] != stamp) {
seen[base] = stamp;
queue[nb++] = base;
}
if (nd >= scap) {
int ncap = scap ? scap * PAIR_LEN : CBM_SZ_16;
int *grown = (int *)cbm_alloc(CBM_MEM_CLASS_OTHER, (size_t)ncap * sizeof(int));
ok = grown != NULL;
if (ok && nd > 0) {
memcpy(grown, steps, (size_t)nd * sizeof(int));
}
cbm_free(CBM_MEM_CLASS_OTHER, steps);
steps = grown;
scap = ok ? ncap : 0;
}
if (ok) {
steps[nd++] = step;
}
p = bar ? bar + SKIP_ONE : NULL;
}
ok = ok && jr_walk_decl(ix, e, t, ix->files[file].kotlin, steps, nd, d > 0);
if (d == 0) {
e->encl = jr_walk_encl(&ix->files[file], t);
}
}
if (ok && nb > 0) {
e->bases = (int *)jr_alloc(ix, (size_t)nb * sizeof(int));
ok = e->bases != NULL;
if (ok) {
memcpy(e->bases, queue, (size_t)nb * sizeof(int));
e->nbases = nb;
}
}
}
memset(seen, 0, ok ? n * sizeof(int) : 0);
for (int ei = 0; ok && ei < ix->nents; ei++) {
jr_entity_t *e = &ix->ents[ei];
int stamp = ei + SKIP_ONE;
int head = 0;
int tail = 0;
seen[ei] = stamp; /* a cycle does not come back to the type itself */
for (int b = 0; b < e->nbases; b++) {
if (seen[e->bases[b]] != stamp) {
seen[e->bases[b]] = stamp;
queue[tail++] = e->bases[b];
}
}
while (head < tail) {
const jr_entity_t *s = &ix->ents[queue[head++]];
for (int b = 0; b < s->nbases; b++) {
if (seen[s->bases[b]] != stamp) {
seen[s->bases[b]] = stamp;
queue[tail++] = s->bases[b];
}
}
}
if (tail > 0) {
e->closure = (int *)jr_alloc(ix, (size_t)tail * sizeof(int));
ok = e->closure != NULL;
if (ok) {
memcpy(e->closure, queue, (size_t)tail * sizeof(int));
e->nclosure = tail;
}
}
}
cbm_free(CBM_MEM_CLASS_OTHER, seen);
cbm_free(CBM_MEM_CLASS_OTHER, queue);
cbm_free(CBM_MEM_CLASS_OTHER, steps);
return ok;
}
/* The receiver of every Kotlin extension, bound in its file's scope, and the
* extensions of each receiver type by name. */
static bool jr_build_extensions(jr_index_t *ix, const cbm_gbuf_t *g) {
for (int fi = 0; fi < ix->nfiles; fi++) {
jr_file_t *f = &ix->files[fi];
for (int mi = 0; f->kotlin && mi < f->nmembers; mi++) {
jr_member_t *m = &f->members[mi];
if (!m->recv[0]) {
continue;
}
if (strcmp(m->recv, "?") != 0) {
jr_ctx_t c;
jr_ctx_decl(&c, ix, g, fi, m->owner, true);
m->recv_entity = jr_header_type(&c, m->recv, strlen(m->recv));
if (m->recv_entity == JR_NONE) {
continue; /* a receiver outside the repository: nobody names it */
}
}
char key[JR_KEY_BUF];
if (!jr_ext_key(m->recv_entity, m->name, key, sizeof(key))) {
continue;
}
jr_ilist_t *l = jr_ht_ilist(ix, ix->extensions, key, true);
if (!l || !jr_ilist_push(ix, l, fi) || !jr_ilist_push(ix, l, mi)) {
return false;
}
}
}
return true;
}
/* ── Index lifecycle and the resolver hooks ──────────────────────── */
static void jr_destroy(void *index) {
jr_index_t *ix = (jr_index_t *)index;
if (!ix) {
return;
}
if (ix->stats) {
const jr_stats_t *st = ix->stats;
const _Atomic int64_t *vals[] = {&st->source_gaps, &st->plain_text,
&st->type_and_function, &st->type_and_function_node,
&st->java_given, &st->java_open,
&st->kotlin_given, &st->kotlin_open,
&st->kotlin_extension, &st->java_field,
&st->java_field_named};
char b[sizeof(vals) / sizeof(vals[0])][CBM_SZ_32];
for (size_t i = 0; i < sizeof(vals) / sizeof(vals[0]); i++) {
snprintf(b[i], sizeof(b[i]), "%lld", (long long)atomic_load(vals[i]));
}
cbm_log_info("doc_links.jvm.done", "source_without_node", b[0], "kdoc_plain_text", b[1],
"type_and_function", b[2], "type_and_function_with_node", b[3],
"not_taken_java_given", b[4], "not_taken_java_open", b[5],
"not_taken_kotlin_given", b[6], "not_taken_kotlin_open", b[7],
"not_taken_kotlin_extension", b[8], "not_taken_java_field", b[9],
"not_taken_java_field_named", b[10]);
cbm_free(CBM_MEM_CLASS_OTHER, ix->stats);
}
cbm_ht_free(ix->ent_by_fqn);
cbm_ht_free(ix->pkg_types);
cbm_ht_free(ix->packages);
cbm_ht_free(ix->pkg_prefixes);
cbm_ht_free(ix->pkg_members);
cbm_ht_free(ix->extensions);
cbm_ht_free(ix->quarantine);
cbm_ht_free(ix->quarantine_test);
cbm_free(CBM_MEM_CLASS_OTHER, ix->ents);
cbm_free(CBM_MEM_CLASS_OTHER, ix->run_to_file);
cbm_arena_destroy(&ix->arena);
cbm_free(CBM_MEM_CLASS_OTHER, ix);
}
static void *jr_build_fail(jr_index_t *ix, const char *step) {
cbm_log_error("doc_links.jvm.error", "step", step, "reason", "alloc");
jr_destroy(ix);
return NULL;
}
static bool jr_has_suffix(const char *s, const char *sfx) {
size_t n = strlen(s);
size_t sl = strlen(sfx);
return n >= sl && strcmp(s + n - sl, sfx) == 0;
}
static void *jr_build(const cbm_doclink_build_in_t *in) {
jr_index_t *ix = (jr_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;
ix->mode = in->ctx->mode;
ix->ent_by_fqn = cbm_ht_create(CBM_SZ_4K);
ix->pkg_types = cbm_ht_create(CBM_SZ_4K);
ix->packages = cbm_ht_create(CBM_SZ_1K);
ix->pkg_prefixes = cbm_ht_create(CBM_SZ_1K);
ix->pkg_members = cbm_ht_create(CBM_SZ_1K);
ix->extensions = cbm_ht_create(CBM_SZ_256);
ix->quarantine = cbm_ht_create(CBM_SZ_64);
ix->quarantine_test = cbm_ht_create(CBM_SZ_64);
ix->nfiles = in->file_count;
ix->files = (jr_file_t *)jr_alloc(ix, (size_t)(in->file_count ? in->file_count : SKIP_ONE) *
sizeof(jr_file_t));
ix->run_count = in->run_file_count;
ix->run_to_file = (int *)cbm_alloc(
CBM_MEM_CLASS_OTHER,
(size_t)(in->run_file_count ? in->run_file_count : SKIP_ONE) * sizeof(int));
ix->stats = (jr_stats_t *)cbm_calloc(CBM_MEM_CLASS_OTHER, sizeof(*ix->stats));
if (!ix->ent_by_fqn || !ix->pkg_types || !ix->packages || !ix->pkg_prefixes ||
!ix->pkg_members || !ix->extensions || !ix->quarantine || !ix->quarantine_test ||
!ix->files || !ix->run_to_file || !ix->stats) {
return jr_build_fail(ix, "tables");
}
for (int i = 0; i < in->run_file_count; i++) {
ix->run_to_file[i] = JR_NONE;
}
int bad_scopes = 0;
for (int i = 0; i < in->file_count; i++) {
const cbm_doclink_file_t *src = &in->files[i];
jr_file_t *f = &ix->files[i];
memset(f, 0, sizeof(*f));
f->rel_path = src->rel_path; /* stays valid until destroy */
f->is_test = jr_is_test_path(src->rel_path);
f->scoped = src->scope && jr_parse_scope(ix, f, src->scope);
if (!f->scoped) {
bad_scopes += src->scope != NULL;
f->nimports = f->nwild = f->ntypes = f->nmembers = f->nunplaced = 0;
}
f->kotlin = !jr_has_suffix(src->rel_path, ".java");
if (!f->package) {
f->package = "";
}
f->module_qn = cbm_fqn_module_source_lang(&ix->arena, ix->project, src->rel_path,
f->kotlin ? CBM_LANG_KOTLIN : CBM_LANG_JAVA);
if (!f->module_qn) {
ix->oom = true;
}
if (src->run_file >= 0 && src->run_file < in->run_file_count) {
ix->run_to_file[src->run_file] = i;
}
}
if (ix->oom) {
return jr_build_fail(ix, "scopes");
}
if (bad_scopes > 0) {
char b[CBM_SZ_32];
snprintf(b, sizeof(b), "%d", bad_scopes);
cbm_log_warn("doc_links.jvm.bad_scope", "files", b);
}
int skipped = 0;
if (!jr_build_entities(ix, &skipped) || ix->oom) {
return jr_build_fail(ix, "entities");
}
if (!jr_resolve_supers(ix, in->graph) || ix->oom) {
return jr_build_fail(ix, "supertypes");
}
if (!jr_build_extensions(ix, in->graph) || ix->oom) {
return jr_build_fail(ix, "extensions");
}
int incomplete = 0;
for (int i = 0; i < ix->nents; i++) {
incomplete += ix->ents[i].incomplete;
}
char b[5][CBM_SZ_32];
snprintf(b[0], sizeof(b[0]), "%d", ix->nfiles);
snprintf(b[1], sizeof(b[1]), "%d", ix->nents);
snprintf(b[2], sizeof(b[2]), "%d", skipped);
snprintf(b[3], sizeof(b[3]), "%d", incomplete);
snprintf(b[4], sizeof(b[4]), "%u",
(unsigned)(cbm_ht_count(ix->quarantine) + cbm_ht_count(ix->quarantine_test)));
cbm_log_info("doc_links.jvm.index", "files", b[0], "types", b[1], "skipped_types", b[2],
"incomplete_types", b[3], "quarantined_names", b[4]);
return ix;
}
/* True when the documented definition has a node of its own (or shares the
* node of its overload group). One node per qualified name: a definition
* whose name another declaration took (a Kotlin class and the factory
* function named like it, two classes' properties of one name in one file)
* has none, and an edge written for it would leave from that other
* declaration. A definition the scan has no record of is checked against the
* node itself: the source file is extracted in this run, so its nodes carry
* their lines. */
static bool jr_source_has_node(const jr_ctx_t *c, const CBMDocLink *link) {
if (link->flags & CBM_DOCLINK_FLAG_FILE) {
return true; /* the File node: the core finds it */
}
if (c->member) {
return jr_member_node(c, c->file, c->member) != NULL;
}
if (c->type) {
jr_decl_t d = {.file = c->file, .type = (int)(c->type - c->f->types)};
return jr_type_node(c, d) != NULL;
}
const cbm_gbuf_node_t *n = link->source_qn ? cbm_gbuf_find_by_qn(c->g, link->source_qn) : NULL;
return n && n->file_path && strcmp(n->file_path, c->f->rel_path) == 0 &&
n->start_line == (int)link->def_line;
}
/* True when `line` lies in a part of the file the scan could not place. */
static bool jr_unplaced_line(const jr_file_t *f, uint32_t line) {
int lo = 0;
int hi = f->nunplaced;
while (lo < hi) {
int mid = lo + ((hi - lo) / PAIR_LEN);
if (f->unplaced[mid].to < line) {
lo = mid + SKIP_ONE;
} else {
hi = mid;
}
}
return lo < f->nunplaced && f->unplaced[lo].from <= line;
}
static void jr_resolve(const void *index, void *state, int run_file, const CBMDocLink *link,
const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {
(void)state; /* Java and Kotlin keep no per-file working state */
const jr_index_t *ix = (const jr_index_t *)index;
out->kind = CBM_DOCLINK_UNRESOLVED;
out->reason = CBM_DOCLINK_REASON_MISSING;
out->target = NULL;
out->exact = false;
if (!ix || !link || run_file < 0 || run_file >= ix->run_count ||
ix->run_to_file[run_file] < 0) {
return;
}
int file = ix->run_to_file[run_file];
const jr_file_t *f = &ix->files[file];
if (!f->scoped) {
out->reason = CBM_DOCLINK_REASON_GRAPH_GAP; /* no scope to resolve in: never a guess */
return;
}
jr_ref_t r;
if (!link->raw ||
!(f->kotlin ? jr_parse_kotlin(link->raw, &r) : jr_parse_java(link->raw, &r))) {
out->reason = CBM_DOCLINK_REASON_UNPARSEABLE;
return;
}
/* What could not be placed is not resolved around: a definition in a part
* of its file where the scan lost its place has no known scope, and a
* name some file declares at an unknown place could be that declaration.
* Both are declared-but-unplaced: graph gaps. */
bool sample = link->syntax == CBM_DOCLINK_KT_SAMPLE;
bool unplaced = !(link->flags & CBM_DOCLINK_FLAG_FILE) && jr_unplaced_line(f, link->def_line);
for (int i = 0; !unplaced && i < r.nsegs; i++) {
unplaced = cbm_ht_get(ix->quarantine, r.segs[i]) != NULL ||
((f->is_test || sample) && cbm_ht_get(ix->quarantine_test, r.segs[i]) != NULL);
}
if (unplaced) {
out->reason = CBM_DOCLINK_REASON_GRAPH_GAP;
return;
}
jr_ctx_t c;
jr_ctx_init(&c, ix, graph, file, link);
if (sample) {
c.prod = false; /* samples live in test sources */
c.sample = true;
}
jr_res_t res = f->kotlin ? jr_kotlin_resolve(&c, &r)
: jr_java_resolve(&c, &r, link->syntax == CBM_DOCLINK_JAVA_VALUE);
/* KDoc `[name]` is Markdown: a name that resolves to nothing is rendered
* as the plain text it is, so it is no reference. A block tag (@see,
* @throws, @sample) names its subject and keeps its row. */
bool plain_text = link->syntax == CBM_DOCLINK_KT_KDOC_LINK && res.st == JR_UNRES &&
res.reason == CBM_DOCLINK_REASON_MISSING;
if (res.st == JR_LOCAL || plain_text) {
if (plain_text) {
atomic_fetch_add(&ix->stats->plain_text, 1);
}
out->kind = CBM_DOCLINK_LOCAL;
return;
}
if (res.st == JR_OK && res.node) {
if (!jr_source_has_node(&c, link)) {
/* resolved, with nowhere to leave from: the documented definition
* is the one without a node */
atomic_fetch_add(&ix->stats->source_gaps, 1);
out->reason = CBM_DOCLINK_REASON_GRAPH_GAP;
return;
}
out->kind = CBM_DOCLINK_EDGE;
out->target = res.node;
out->exact = res.exact;
return;
}
out->reason = res.reason;
}
/* ── Incremental scope rules ─────────────────────────────────────── */
/* Scope record fields (0-based, the tag is field 0; internal/cbm/
* doclink_jvm.c): `I kind alias target`, `T .. supers(6) ..` and
* `M start kind flags(3) owner name(5) tparams sig recv(8) ..`. */
enum {
JR_F_I_KIND = 1,
JR_F_I_ALIAS = 2,
JR_F_T_SUPERS = 6,
JR_F_M_FLAGS = 3,
JR_F_M_NAME = 5,
JR_F_M_RECV = 8,
JR_DELTA_IMPORTS = 16, /* changed imports compared by name; more: any name */
};
typedef struct {
const char *p;
size_t n;
} jr_span_t;
static jr_span_t jr_delta_field(jr_span_t line, int idx) {
int f = 0;
size_t s = 0;
for (size_t i = 0; i <= line.n; i++) {
if (i == line.n || line.p[i] == '\t') {
if (f == idx) {
return (jr_span_t){.p = line.p + s, .n = i - s};
}
f++;
s = i + SKIP_ONE;
}
}
return (jr_span_t){0};
}
/* The next record; with `imports` the next import record, without it the
* next record that is none. false at the end. */
static bool jr_delta_next(const char **cursor, jr_span_t *line, bool imports) {
for (const char *p = *cursor; p && *p;) {
const char *nl = strchr(p, '\n');
size_t n = nl ? (size_t)(nl - p) : strlen(p);
const char *next = nl ? nl + SKIP_ONE : p + n;
if (n > 0 && (p[0] == 'I') == imports) {
*line = (jr_span_t){.p = p, .n = n};
*cursor = next;
return true;
}
p = next;
}
*cursor = NULL;
return false;
}
static bool jr_span_eq(jr_span_t a, jr_span_t b) {
return a.n == b.n && memcmp(a.p, b.p, a.n) == 0;
}
/* The import records of a scope, in order. Returns the count, -1 when memory
* ran out. */
static int jr_delta_imports(const char *scope, jr_span_t **out) {
int n = 0;
jr_span_t line;
for (const char *p = scope; jr_delta_next(&p, &line, true);) {
n++;
}
*out =
(jr_span_t *)cbm_alloc(CBM_MEM_CLASS_OTHER, (size_t)(n ? n : SKIP_ONE) * sizeof(jr_span_t));
if (!*out) {
return CBM_NOT_FOUND;
}
int w = 0;
for (const char *p = scope; jr_delta_next(&p, &line, true);) {
(*out)[w++] = line;
}
return n;
}
/* True when a changed import can change what the '|'-joined type names in
* `names` bind to: an on-demand import can supply any name, a single import
* the one it is known by. */
static bool jr_delta_names_hit(jr_span_t names, const jr_span_t *changed, int nchanged,
bool any_name) {
for (size_t i = 0; i < names.n;) {
size_t e = i;
while (e < names.n && names.p[e] != '|') {
e++;
}
size_t head = i;
while (head < e && names.p[head] != '.') {
head++;
}
bool named = head > i && !(head - i == SKIP_ONE && names.p[i] == '?');
if (named && any_name) {
return true;
}
for (int k = 0; named && k < nchanged; k++) {
jr_span_t alias = jr_delta_field(changed[k], JR_F_I_ALIAS);
if (alias.n == head - i && memcmp(alias.p, names.p + i, alias.n) == 0) {
return true;
}
}
i = e + SKIP_ONE;
}
return false;
}
/* Imports scope the file itself, which is re-extracted anyway -- except for
* the names its declaration headers write: a supertype and an extension's
* receiver are bound in the file's scope, and references in OTHER files
* resolve through them. A changed import that can re-bind one of those is not
* repairable file by file. */
static int jr_delta_import_change(const char *stored, const char *fresh) {
jr_span_t *si = NULL;
jr_span_t *fi = NULL;
int ns = jr_delta_imports(stored, &si);
int nf = jr_delta_imports(fresh, &fi);
int result = CBM_DOCLINK_DELTA_LOCAL;
if (ns < 0 || nf < 0) {
result = CBM_NOT_FOUND;
} else {
/* what is left between the common start and the common end changed */
int a = 0;
while (a < ns && a < nf && jr_span_eq(si[a], fi[a])) {
a++;
}
int es = ns;
int ef = nf;
while (es > a && ef > a && jr_span_eq(si[es - SKIP_ONE], fi[ef - SKIP_ONE])) {
es--;
ef--;
}
int nchanged = (es - a) + (ef - a);
bool any_name = nchanged > JR_DELTA_IMPORTS;
jr_span_t changed[JR_DELTA_IMPORTS];
int w = 0;
for (int i = a; !any_name && i < es; i++) {
changed[w++] = si[i];
}
for (int i = a; !any_name && i < ef; i++) {
changed[w++] = fi[i];
}
for (int i = 0; i < w; i++) {
jr_span_t kind = jr_delta_field(changed[i], JR_F_I_KIND);
any_name = any_name || (kind.n == SKIP_ONE && (kind.p[0] == 'w' || kind.p[0] == 'n'));
}
jr_span_t line;
for (const char *p = fresh; nchanged > 0 && result == CBM_DOCLINK_DELTA_LOCAL &&
jr_delta_next(&p, &line, false);) {
int field = line.p[0] == 'T' ? JR_F_T_SUPERS : (line.p[0] == 'M' ? JR_F_M_RECV : 0);
if (field && jr_delta_names_hit(jr_delta_field(line, field), changed, w, any_name)) {
result = CBM_DOCLINK_DELTA_GLOBAL;
}
}
}
cbm_free(CBM_MEM_CLASS_OTHER, si);
cbm_free(CBM_MEM_CLASS_OTHER, fi);
return result;
}
/* Compare a changed file's stored and fresh scopes record by record, in
* order. Two differences leave every other file's resolution alone:
* - a member the fresh scope no longer has (a method, a constructor, a
* field, a property, an enum constant): a reference that depended on it
* either bound it (an edge into this file) or names it in its unresolved
* row, so the name is reported;
* - the file's own imports, unless one can re-bind a supertype or an
* extension receiver the file declares (jr_delta_import_change).
* Everything else is GLOBAL: a new or changed record (a type, a member, a
* signature, the package), a removed type (it may be another type's
* supertype), a removed record component or constructor property (a record's
* canonical constructor is matched against them without naming them), a
* quarantined name or unplaced range that came or went, and a changed order
* (declarations of one name own their node by order). */
static int jr_scope_delta(const char *stored, const char *fresh, cbm_doclink_name_fn removed,
void *ud) {
const char *sp = stored;
const char *fp = fresh;
jr_span_t sl = {0};
jr_span_t fl = {0};
bool hs = jr_delta_next(&sp, &sl, false);
bool hf = jr_delta_next(&fp, &fl, false);
while (hs || hf) {
if (hs && hf && jr_span_eq(sl, fl)) {
hs = jr_delta_next(&sp, &sl, false);
hf = jr_delta_next(&fp, &fl, false);
continue;
}
if (!hs || sl.p[0] != 'M') {
return CBM_DOCLINK_DELTA_GLOBAL;
}
jr_span_t flags = jr_delta_field(sl, JR_F_M_FLAGS);
jr_span_t name = jr_delta_field(sl, JR_F_M_NAME);
if (!flags.p || !name.p || name.n == 0) {
return CBM_NOT_FOUND; /* not a member record this code wrote */
}
if (memchr(flags.p, 'p', flags.n)) {
return CBM_DOCLINK_DELTA_GLOBAL;
}
if (!removed || !removed(ud, name.p, name.n)) {
return CBM_NOT_FOUND;
}
hs = jr_delta_next(&sp, &sl, false);
}
return jr_delta_import_change(stored, fresh);
}
const cbm_doclink_resolver_t cbm_doclink_jvm_resolver = {
.langs = {CBM_LANG_JAVA, CBM_LANG_KOTLIN},
.lang_count = 2,
.scope_tag = CBM_DOCLINK_JVM_SCOPE_TAG,
.build = jr_build,
.destroy = jr_destroy,
.resolve = jr_resolve,
.scope_delta = jr_scope_delta,
};