Skip to content

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

139 KB
Raw Blame
/*
 * pass_pkgmap.c — Generic package/module manifest resolution.
 *
 * Scans discovered files for manifest files (package.json, go.mod, Cargo.toml,
 * pyproject.toml, composer.json, pubspec.yaml, pom.xml, build.gradle, mix.exs,
 * *.gemspec, Package.swift) and builds a hash table mapping bare package specifiers to resolved
 * module QNs. This enables IMPORTS edges for non-relative imports like
 * "@myorg/pkg", "github.com/foo/bar", "use my_crate::foo".
 *
 * Integration: called from parallel extract workers (per-worker local arrays)
 * and merged sequentially before registry build.
 */
#include "pipeline/pipeline.h"
#include "pipeline/pipeline_internal.h"
#include "pipeline/pass_lsp_cross.h"
#include "discover/discover.h"
#include "foundation/compat.h"
#include "foundation/compat_fs.h"
#include "foundation/constants.h"
#include "foundation/hash_table.h"
#include "foundation/log.h"
#include "foundation/mem_core.h"
#include "foundation/platform.h"
#include "foundation/str_util.h"
#include "foundation/win_utf8.h"
#include "foundation/yaml.h"

#include <yyjson/yyjson.h>

#include <ctype.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>

/* Read an entire file into a core-owned buffer (class extract; release with
 * cbm_free(CBM_MEM_CLASS_EXTRACT, ...)). Returns NULL on failure. */
static char *pkgmap_read_file(const char *path, int *out_len) {
    FILE *f = cbm_fopen(path, "rb");
    if (!f) {
        return NULL;
    }
    (void)fseek(f, 0, SEEK_END);
    long size = ftell(f);
    (void)fseek(f, 0, SEEK_SET);
    if (size <= 0 || size > (long)CBM_SZ_1K * CBM_SZ_1K) { /* 1MB cap for manifests */
        (void)fclose(f);
        return NULL;
    }
    char *buf = (char *)cbm_alloc(CBM_MEM_CLASS_EXTRACT, (size_t)size + SKIP_ONE);
    if (!buf) {
        (void)fclose(f);
        return NULL;
    }
    size_t nread = fread(buf, SKIP_ONE, (size_t)size, f);
    (void)fclose(f);
    buf[nread] = '\0';
    *out_len = (int)nread;
    return buf;
}

/* ── Constants ─────────────────────────────────────────────────── */

enum {
    PKGMAP_INIT_CAP = 16,
    PKGMAP_PATH_BUF = 1024,
    PKGMAP_LINE_BUF = 512,
    PKGMAP_HT_INIT = 64,
    PKGMAP_ITOA_BUF = 16,
    /* Hard ceiling on recursive directory descent. This is the
     * non-negotiable termination guarantee for the manifest walk: even
     * if the filesystem contains directory junctions / symlink cycles
     * (the documented reason the walk was once disabled on Windows),
     * descent stops at this depth so the walk can never hang. 64 is far
     * deeper than any real source tree. */
    PKGMAP_WALK_MAX_DEPTH = 64,
    /* String lengths for manifest parsing (avoid magic numbers in memcmp) */
    TOML_NAME_LEN = 4,      /* strlen("name") */
    TOML_NAME_SP = 5,       /* strlen("name ") */
    TOML_NAME_EQ = 5,       /* strlen("name=") */
    XML_PARENT_OPEN = 8,    /* strlen("<parent>") */
    XML_PARENT_CLOSE = 9,   /* strlen("</parent>") */
    XML_GROUP_OPEN = 9,     /* strlen("<groupId>") */
    XML_ARTIFACT_OPEN = 12, /* strlen("<artifactId>") */
};

/* Thread-local int→string for log key-value pairs */
static const char *pkgmap_itoa(int val) {
    static _Thread_local char buf[PKGMAP_ITOA_BUF];
    snprintf(buf, sizeof(buf), "%d", val);
    return buf;
}

/* Check if src at position p starts with literal str of known length. */
static bool at_prefix(const char *p, const char *end, const char *prefix, int prefix_len) {
    return p + prefix_len <= end && memcmp(p, prefix, (size_t)prefix_len) == 0;
}

/* ── Per-worker collection ─────────────────────────────────────── */

void cbm_pkg_entries_init(cbm_pkg_entries_t *e) {
    e->items = NULL;
    e->count = 0;
    e->cap = 0;
}

static void pkg_entries_push(cbm_pkg_entries_t *e, char *pkg_name, char *entry_rel) {
    if (e->count >= e->cap) {
        int new_cap = e->cap == 0 ? PKGMAP_INIT_CAP : e->cap * SKIP_ONE * PAIR_LEN;
        cbm_pkg_entry_t *tmp = realloc(e->items, new_cap * sizeof(cbm_pkg_entry_t));
        if (!tmp) {
            free(pkg_name);
            free(entry_rel);
            return;
        }
        e->items = tmp;
        e->cap = new_cap;
    }
    e->items[e->count].pkg_name = pkg_name;
    e->items[e->count].entry_rel = entry_rel;
    e->count++;
}

void cbm_pkg_entries_free(cbm_pkg_entries_t *e) {
    for (int i = 0; i < e->count; i++) {
        free(e->items[i].pkg_name);
        free(e->items[i].entry_rel);
    }
    free(e->items);
    e->items = NULL;
    e->count = 0;
    e->cap = 0;
}

/* ── Helpers ───────────────────────────────────────────────────── */

/* Get the basename from a relative path. Returns pointer into rel_path. */
static const char *path_basename(const char *rel_path) {
    const char *last = strrchr(rel_path, '/');
    return last ? last + SKIP_ONE : rel_path;
}

/* Get the directory part of a relative path (without trailing slash).
 * Returns heap-allocated string. For "foo.json" returns "". */
static char *path_dirname(const char *rel_path) {
    const char *last = strrchr(rel_path, '/');
    if (!last) {
        return strdup("");
    }
    return cbm_strndup(rel_path, (size_t)(last - rel_path));
}

/* Strip file extension from a path. Returns heap-allocated string.
 * "src/index.ts" → "src/index", "lib/main" → "lib/main" */
static char *strip_extension(const char *path) {
    size_t len = strlen(path);
    for (size_t i = len; i > 0; i--) {
        if (path[i - SKIP_ONE] == '.') {
            return cbm_strndup(path, i - SKIP_ONE);
        }
        if (path[i - SKIP_ONE] == '/') {
            break;
        }
    }
    return strdup(path);
}

/* Join directory + relative entry path, normalize.
 * "packages/foo" + "src/index.ts" → "packages/foo/src/index" (stripped ext) */
static char *join_and_strip(const char *dir, const char *entry) {
    if (!entry || entry[0] == '\0') {
        return NULL;
    }
    /* Skip leading ./ from entry */
    if (entry[0] == '.' && entry[SKIP_ONE] == '/') {
        entry += PAIR_LEN;
    }
    char buf[PKGMAP_PATH_BUF];
    if (dir[0] == '\0') {
        snprintf(buf, sizeof(buf), "%s", entry);
    } else {
        snprintf(buf, sizeof(buf), "%s/%s", dir, entry);
    }
    return strip_extension(buf);
}

/* Check if a string ends with a suffix. */
static bool ends_with(const char *s, const char *suffix) {
    size_t slen = strlen(s);
    size_t suflen = strlen(suffix);
    if (suflen > slen) {
        return false;
    }
    return strcmp(s + slen - suflen, suffix) == 0;
}

/* Find a line starting with a prefix in source. Returns pointer to first char
 * after prefix, or NULL. Handles leading whitespace. */
static const char *find_line_value(const char *src, int src_len, const char *prefix) {
    size_t plen = strlen(prefix);
    const char *p = src;
    const char *end = src + src_len;
    while (p < end) {
        /* Skip leading whitespace */
        while (p < end && (*p == ' ' || *p == '\t')) {
            p++;
        }
        if (p + plen <= end && memcmp(p, prefix, plen) == 0) {
            return p + plen;
        }
        /* Skip to next line */
        while (p < end && *p != '\n') {
            p++;
        }
        if (p < end) {
            p++; /* skip \n */
        }
    }
    return NULL;
}

/* Extract a quoted string value from position. Handles both "..." and '...'
 * Returns heap-allocated string, or NULL. */
static char *extract_quoted(const char *p, const char *end) {
    /* Skip whitespace and = sign */
    while (p < end && (*p == ' ' || *p == '\t' || *p == '=')) {
        p++;
    }
    if (p >= end) {
        return NULL;
    }
    char quote = *p;
    if (quote != '"' && quote != '\'') {
        return NULL;
    }
    p++;
    const char *start = p;
    while (p < end && *p != quote && *p != '\n') {
        p++;
    }
    if (p >= end || *p != quote) {
        return NULL;
    }
    return cbm_strndup(start, (size_t)(p - start));
}

/* ── Language-specific manifest parsers ────────────────────────── */

/* Resolve JS/TS entry point from exports["."] object. */
static const char *resolve_exports_dot(yyjson_val *dot) {
    if (yyjson_is_str(dot)) {
        return yyjson_get_str(dot);
    }
    if (!yyjson_is_obj(dot)) {
        return NULL;
    }
    static const char *keys[] = {"import", "default", "require"};
    for (int i = 0; i < (int)(sizeof(keys) / sizeof(keys[0])); i++) {
        yyjson_val *v = yyjson_obj_get(dot, keys[i]);
        if (yyjson_is_str(v)) {
            return yyjson_get_str(v);
        }
    }
    return NULL;
}

/* Resolve JS/TS entry point from package.json root. */
static const char *resolve_pkg_entry(yyjson_val *root) {
    yyjson_val *exports = yyjson_obj_get(root, "exports");
    if (yyjson_is_obj(exports)) {
        const char *e = resolve_exports_dot(yyjson_obj_get(exports, "."));
        if (e) {
            return e;
        }
    }
    static const char *fallback_keys[] = {"main", "module"};
    for (int i = 0; i < (int)(sizeof(fallback_keys) / sizeof(fallback_keys[0])); i++) {
        yyjson_val *v = yyjson_obj_get(root, fallback_keys[i]);
        if (yyjson_is_str(v)) {
            return yyjson_get_str(v);
        }
    }
    return "src/index.ts"; /* last resort default */
}

/* JS/TS: package.json — name + entry point resolution */
static void parse_package_json(const char *source, int source_len, const char *rel_path,
                               cbm_pkg_entries_t *entries) {
    yyjson_doc *doc = yyjson_read(source, (size_t)source_len, 0);
    if (!doc) {
        return;
    }
    yyjson_val *root = yyjson_doc_get_root(doc);
    if (!yyjson_is_obj(root)) {
        yyjson_doc_free(doc);
        return;
    }

    yyjson_val *name_val = yyjson_obj_get(root, "name");
    if (!yyjson_is_str(name_val)) {
        yyjson_doc_free(doc);
        return;
    }
    const char *name = yyjson_get_str(name_val);
    if (!name || name[0] == '\0') {
        yyjson_doc_free(doc);
        return;
    }

    const char *entry = resolve_pkg_entry(root);
    if (entry) {
        char *dir = path_dirname(rel_path);
        char *resolved = join_and_strip(dir, entry);
        if (resolved) {
            pkg_entries_push(entries, strdup(name), resolved);
        }
        free(dir);
    }

    yyjson_doc_free(doc);
}

/* Go: go.mod — module directive */
static void parse_go_mod(const char *source, int source_len, const char *rel_path,
                         cbm_pkg_entries_t *entries) {
    const char *end = source + source_len;
    const char *val = find_line_value(source, source_len, "module ");
    if (!val) {
        return;
    }
    /* Extract module path (rest of line, trimmed) */
    while (val < end && (*val == ' ' || *val == '\t')) {
        val++;
    }
    const char *start = val;
    while (val < end && *val != '\n' && *val != '\r' && *val != ' ') {
        val++;
    }
    if (val <= start) {
        return;
    }
    char *module_path = cbm_strndup(start, (size_t)(val - start));
    char *dir = path_dirname(rel_path);

    /* The module path maps to the directory containing go.mod.
     * For "." dir, use empty string. */
    pkg_entries_push(entries, module_path, strdup(dir));
    free(dir);
}

/* Extract "name" value from a TOML section. Scans from section_start until
 * the next [...] header or EOF. Returns heap string or NULL. */
static char *toml_extract_name(const char *section_start, const char *end) {
    const char *p = section_start;
    while (p < end) {
        while (p < end && (*p == ' ' || *p == '\t')) {
            p++;
        }
        if (p < end && *p == '[') {
            break;
        }
        if (at_prefix(p, end, "name ", TOML_NAME_SP)) {
            return extract_quoted(p + TOML_NAME_SP, end);
        }
        if (at_prefix(p, end, "name=", TOML_NAME_EQ)) {
            return extract_quoted(p + TOML_NAME_EQ, end);
        }
        while (p < end && *p != '\n') {
            p++;
        }
        if (p < end) {
            p++;
        }
    }
    return NULL;
}

/* Build entry path: dir/suffix or just suffix if dir is empty. */
static char *build_entry_path(const char *rel_path, const char *suffix) {
    char *dir = path_dirname(rel_path);
    char buf[PKGMAP_PATH_BUF];
    snprintf(buf, sizeof(buf), "%s%s%s", dir[0] ? dir : "", dir[0] ? "/" : "", suffix);
    free(dir);
    return strdup(buf);
}

/* Rust: Cargo.toml — [package] name */
static void parse_cargo_toml(const char *source, int source_len, const char *rel_path,
                             cbm_pkg_entries_t *entries) {
    const char *section = find_line_value(source, source_len, "[package]");
    if (!section) {
        return;
    }
    char *name = toml_extract_name(section, source + source_len);
    if (!name) {
        return;
    }
    char *entry = build_entry_path(rel_path, "src/lib");
    pkg_entries_push(entries, name, entry);
}

/* Python: pyproject.toml — [project] name */
/* Normalize Python package name: hyphens → underscores (PEP 503). */
static void py_normalize_name(char *name) {
    for (char *c = name; *c; c++) {
        if (*c == '-') {
            *c = '_';
        }
    }
}

static void parse_pyproject_toml(const char *source, int source_len, const char *rel_path,
                                 cbm_pkg_entries_t *entries) {
    const char *section = find_line_value(source, source_len, "[project]");
    if (!section) {
        return;
    }
    char *name = toml_extract_name(section, source + source_len);
    if (!name) {
        return;
    }
    py_normalize_name(name);

    /* Register src/<name>/__init__ as primary entry */
    char suffix[PKGMAP_PATH_BUF];
    snprintf(suffix, sizeof(suffix), "src/%s/__init__", name);
    char *entry = build_entry_path(rel_path, suffix);
    char *name_copy = strdup(name);
    pkg_entries_push(entries, name, entry);

    /* Also register <name>/__init__ as alternative (no src/ prefix) */
    char *alt_entry = NULL;
    if (name_copy) {
        snprintf(suffix, sizeof(suffix), "%s/__init__", name_copy);
        alt_entry = build_entry_path(rel_path, suffix);
    }

    if (name_copy && alt_entry) {
        pkg_entries_push(entries, name_copy, alt_entry);
    } else {
        free(name_copy);
        free(alt_entry);
    }
}

/* Extract PSR-4 entries from one composer.json autoload section ("autoload"
 * or "autoload-dev": composer registers both, so test namespaces such as
 * Tests\ map to their directory as well). */
static void extract_psr4(yyjson_val *root, const char *section, const char *dir,
                         cbm_pkg_entries_t *entries) {
    yyjson_val *autoload = yyjson_obj_get(root, section);
    if (!yyjson_is_obj(autoload)) {
        return;
    }
    yyjson_val *psr4 = yyjson_obj_get(autoload, "psr-4");
    if (!yyjson_is_obj(psr4)) {
        return;
    }
    yyjson_val *key = NULL;
    yyjson_obj_iter iter = yyjson_obj_iter_with(psr4);
    while ((key = yyjson_obj_iter_next(&iter)) != NULL) {
        yyjson_val *val = yyjson_obj_iter_get_val(key);
        if (!yyjson_is_str(key) || !yyjson_is_str(val)) {
            continue;
        }
        const char *ns_prefix = yyjson_get_str(key);
        const char *ns_dir = yyjson_get_str(val);
        while (ns_dir[0] == '.' && ns_dir[SKIP_ONE] == '/') {
            ns_dir += PAIR_LEN; /* "./src/" names src/ */
        }
        if (strcmp(ns_dir, ".") == 0) {
            ns_dir = ""; /* "." names the manifest's own directory */
        }
        char ns_entry[PKGMAP_PATH_BUF];
        if (dir[0]) {
            snprintf(ns_entry, sizeof(ns_entry), "%s/%s", dir, ns_dir);
        } else {
            snprintf(ns_entry, sizeof(ns_entry), "%s", ns_dir);
        }
        size_t nelen = strlen(ns_entry);
        if (nelen > 0 && ns_entry[nelen - SKIP_ONE] == '/') {
            ns_entry[nelen - SKIP_ONE] = '\0';
        }
        pkg_entries_push(entries, strdup(ns_prefix), strdup(ns_entry));
    }
}

/* PHP: composer.json — name + PSR-4 autoload */
static void parse_composer_json(const char *source, int source_len, const char *rel_path,
                                cbm_pkg_entries_t *entries) {
    yyjson_doc *doc = yyjson_read(source, (size_t)source_len, 0);
    if (!doc) {
        return;
    }
    yyjson_val *root = yyjson_doc_get_root(doc);
    if (!yyjson_is_obj(root)) {
        yyjson_doc_free(doc);
        return;
    }

    char *dir = path_dirname(rel_path);

    /* Register package name → directory */
    yyjson_val *name_val = yyjson_obj_get(root, "name");
    if (yyjson_is_str(name_val)) {
        const char *name = yyjson_get_str(name_val);
        if (name && name[0] != '\0') {
            pkg_entries_push(entries, strdup(name), strdup(dir));
        }
    }

    extract_psr4(root, "autoload", dir, entries);
    extract_psr4(root, "autoload-dev", dir, entries);

    free(dir);
    yyjson_doc_free(doc);
}

/* Dart: pubspec.yaml — name */
static void parse_pubspec_yaml(const char *source, int source_len, const char *rel_path,
                               cbm_pkg_entries_t *entries) {
    cbm_yaml_node_t *root = cbm_yaml_parse(source, source_len);
    if (!root) {
        return;
    }
    const char *name = cbm_yaml_get_str(root, "name");
    if (name && name[0] != '\0') {
        char *dir = path_dirname(rel_path);
        char entry[PKGMAP_PATH_BUF];
        snprintf(entry, sizeof(entry), "%s%slib", dir[0] ? dir : "", dir[0] ? "/" : "");
        pkg_entries_push(entries, strdup(name), strdup(entry));
        free(dir);
    }
    cbm_yaml_free(root);
}

/* Extract text content of an XML tag at position p. Returns heap string or NULL.
 * p must point to the char after the opening tag's '>'. */
static char *xml_tag_content(const char *p, const char *end) {
    const char *s = p;
    while (p < end && *p != '<') {
        p++;
    }
    if (p <= s) {
        return NULL;
    }
    return cbm_strndup(s, (size_t)(p - s));
}

/* Java: pom.xml — <groupId> + <artifactId> */
/* Scan pom.xml for a top-level XML tag (outside <parent>). Returns heap string or NULL. */
static char *pom_find_tag(const char *source, const char *end, const char *tag, int tag_len) {
    const char *p = source;
    bool in_parent = false;
    while (p < end) {
        if (at_prefix(p, end, "<parent>", XML_PARENT_OPEN)) {
            in_parent = true;
        }
        if (at_prefix(p, end, "</parent>", XML_PARENT_CLOSE)) {
            in_parent = false;
        }
        if (!in_parent && at_prefix(p, end, tag, tag_len)) {
            return xml_tag_content(p + tag_len, end);
        }
        p++;
    }
    return NULL;
}

static void parse_pom_xml(const char *source, int source_len, const char *rel_path,
                          cbm_pkg_entries_t *entries) {
    const char *end = source + source_len;
    char *group_id = pom_find_tag(source, end, "<groupId>", XML_GROUP_OPEN);
    char *artifact_id = pom_find_tag(source, end, "<artifactId>", XML_ARTIFACT_OPEN);

    if (group_id && artifact_id) {
        /* Map: "com.myorg.myapp" → src/main/java directory */
        char pkg_name[PKGMAP_PATH_BUF];
        snprintf(pkg_name, sizeof(pkg_name), "%s.%s", group_id, artifact_id);
        char *dir = path_dirname(rel_path);
        char entry[PKGMAP_PATH_BUF];
        snprintf(entry, sizeof(entry), "%s%ssrc/main/java", dir[0] ? dir : "", dir[0] ? "/" : "");
        pkg_entries_push(entries, strdup(pkg_name), strdup(entry));

        /* Also register just the groupId for package-level imports */
        char grp_entry[PKGMAP_PATH_BUF];
        snprintf(grp_entry, sizeof(grp_entry), "%s%ssrc/main/java", dir[0] ? dir : "",
                 dir[0] ? "/" : "");
        pkg_entries_push(entries, strdup(group_id), strdup(grp_entry));
        free(dir);
    }

    free(group_id);
    free(artifact_id);
}

/* Gradle: build.gradle / build.gradle.kts — group = '...' */
static void parse_build_gradle(const char *source, int source_len, const char *rel_path,
                               cbm_pkg_entries_t *entries) {
    const char *end = source + source_len;
    /* Look for group = '...' or group '...' or group = "..." */
    const char *val = find_line_value(source, source_len, "group");
    if (!val) {
        return;
    }
    char *group = extract_quoted(val, end);
    if (!group) {
        return;
    }
    char *dir = path_dirname(rel_path);
    /* Check for src/main/java or src/main/kotlin */
    char entry[PKGMAP_PATH_BUF];
    snprintf(entry, sizeof(entry), "%s%ssrc/main/java", dir[0] ? dir : "", dir[0] ? "/" : "");
    pkg_entries_push(entries, group, strdup(entry));
    free(dir);
}

/* Elixir: mix.exs — app: :name */
static void parse_mix_exs(const char *source, int source_len, const char *rel_path,
                          cbm_pkg_entries_t *entries) {
    const char *end = source + source_len;
    /* Look for app: :app_name */
    const char *val = find_line_value(source, source_len, "app:");
    if (!val) {
        return;
    }
    while (val < end && (*val == ' ' || *val == '\t')) {
        val++;
    }
    if (val >= end || *val != ':') {
        return;
    }
    val++; /* skip : */
    const char *start = val;
    while (val < end && *val != ',' && *val != '\n' && *val != ' ' && *val != ')') {
        val++;
    }
    if (val <= start) {
        return;
    }
    char *app_name = cbm_strndup(start, (size_t)(val - start));
    char *dir = path_dirname(rel_path);
    char entry[PKGMAP_PATH_BUF];
    snprintf(entry, sizeof(entry), "%s%slib/%s", dir[0] ? dir : "", dir[0] ? "/" : "", app_name);
    /* Register with colon prefix as Elixir uses :atom syntax */
    char atom_name[PKGMAP_PATH_BUF];
    snprintf(atom_name, sizeof(atom_name), "%s", app_name);
    pkg_entries_push(entries, strdup(atom_name), strdup(entry));
    free(app_name);
    free(dir);
}

/* Ruby: *.gemspec — spec.name = '...' */
static void parse_gemspec(const char *source, int source_len, const char *rel_path,
                          cbm_pkg_entries_t *entries) {
    const char *end = source + source_len;
    /* Try spec.name, s.name, gem.name patterns */
    static const char *patterns[] = {".name", NULL};
    for (int i = 0; patterns[i]; i++) {
        const char *p = source;
        while (p < end) {
            const char *found = strstr(p, patterns[i]);
            if (!found || found >= end) {
                break;
            }
            char *name = extract_quoted(found + strlen(patterns[i]), end);
            if (name) {
                char *dir = path_dirname(rel_path);
                char entry[PKGMAP_PATH_BUF];
                snprintf(entry, sizeof(entry), "%s%slib/%s", dir[0] ? dir : "", dir[0] ? "/" : "",
                         name);
                pkg_entries_push(entries, name, strdup(entry));
                free(dir);
                return;
            }
            p = found + SKIP_ONE;
        }
    }
}

/* Swift: Package.swift — SwiftPM manifest.
 *
 * Package.swift is executable Swift, not declarative, so this is a
 * hand-rolled literal pattern-extractor (same spirit as parse_cargo_toml),
 * not a Swift evaluator: it locates `.target(...)` call expressions via a
 * comment/string-aware token scan and pulls only their quoted-string-literal
 * `name:` / `path:` arguments. Anything computed or concatenated is
 * skipped, not guessed — fail-closed, like every other parser here.
 *
 * Only a manifest's OWN `.target(...)` declarations self-register — never
 * `.library(...)` products (a product name is not generally an importable
 * module: SwiftPM lets it alias multiple targets, or none sharing its
 * name), and never `.package(url:)` / `.package(path:)` dependencies or
 * target-to-target dependency references. A dependency resolves because
 * the DEPENDENCY's own Package.swift registers itself when the repo-wide
 * manifest walk (cbm_pkgmap_scan_repo) reaches it, exactly like a JS
 * workspace sibling's package.json (see repro_issue408.c).
 *
 * Deliberately out of scope (matches the item-1 authorization): evaluating
 * `#if`/`#endif` conditional-compilation blocks. A `.target(...)` inside
 * one is scanned like any other — teaching the extractor which platform
 * conditions are "active" would need a Swift semantic tier, which this PR
 * was explicitly asked not to add. */

/* One step of comment/string-aware scanning, shared by swift_find_code_token
 * and swift_match_paren below. If `*pp` sits inside, or is entering, a `//`
 * line comment, a nesting-aware slash-star block comment (continued across
 * calls via `*block_depth`), or a "..." string literal (escape aware,
 * tracked via `*in_str`), advances `*pp` past that one step and returns
 * true. Otherwise leaves `*pp` untouched and returns false, so the caller
 * handles the "real code" character itself (paren tracking, needle
 * matching, ...). */
static bool swift_skip_comment_or_string(const char **pp, const char *end, int *block_depth,
                                         bool *in_str) {
    const char *p = *pp;
    if (*block_depth > 0) {
        if (p + SKIP_ONE < end && p[0] == '/' && p[SKIP_ONE] == '*') {
            (*block_depth)++;
            *pp = p + PAIR_LEN;
        } else if (p + SKIP_ONE < end && p[0] == '*' && p[SKIP_ONE] == '/') {
            (*block_depth)--;
            *pp = p + PAIR_LEN;
        } else {
            *pp = p + SKIP_ONE;
        }
        return true;
    }
    if (*in_str) {
        if (*p == '\\' && p + SKIP_ONE < end) {
            *pp = p + PAIR_LEN;
        } else {
            if (*p == '"') {
                *in_str = false;
            }
            *pp = p + SKIP_ONE;
        }
        return true;
    }
    if (p + SKIP_ONE < end && p[0] == '/' && p[SKIP_ONE] == '/') {
        while (p < end && *p != '\n') {
            p++;
        }
        *pp = p;
        return true;
    }
    if (p + SKIP_ONE < end && p[0] == '/' && p[SKIP_ONE] == '*') {
        *block_depth = SKIP_ONE;
        *pp = p + PAIR_LEN;
        return true;
    }
    if (*p == '"') {
        *in_str = true;
        *pp = p + SKIP_ONE;
        return true;
    }
    return false;
}

/* Scans [start, end) for the next occurrence of `needle` that is not inside
 * a `//` line comment, a nesting-aware slash-star block comment, or a "..."
 * string literal (backslash-escapes honored). This is the single source of
 * truth for "real code" scanning below — a `.target(`, `name:`, or `path:`
 * spelled inside a comment or a string constant must never be mistaken for
 * a live declaration. Returns a pointer to the match, or NULL. */
static const char *swift_find_code_token(const char *start, const char *end, const char *needle) {
    size_t nlen = strlen(needle);
    int block_depth = 0;
    bool in_str = false;
    const char *p = start;
    while (p < end) {
        if (swift_skip_comment_or_string(&p, end, &block_depth, &in_str)) {
            continue;
        }
        if ((size_t)(end - p) >= nlen && memcmp(p, needle, nlen) == 0) {
            return p;
        }
        p++;
    }
    return NULL;
}

/* Find the matching ')' for the '(' at `open`, scanning forward to `end`.
 * Delegates comment/string spans to swift_skip_comment_or_string — matching
 * swift_find_code_token — so a ')', '(', or comment delimiter inside a
 * quoted argument value or a comment never perturbs the depth count.
 * Returns NULL for an unbalanced/unterminated call — the caller treats
 * that span as unparseable and skips it (fail-closed). */
static const char *swift_match_paren(const char *open, const char *end) {
    int depth = 0;
    int block_depth = 0;
    bool in_str = false;
    const char *p = open;
    while (p < end) {
        if (swift_skip_comment_or_string(&p, end, &block_depth, &in_str)) {
            continue;
        }
        if (*p == '(') {
            depth++;
        } else if (*p == ')') {
            depth--;
            if (depth == 0) {
                return p;
            }
        }
        p++;
    }
    return NULL;
}

/* Extract a bare double-quoted string-literal value at `p` (after skipping
 * leading whitespace and honoring backslash-escapes inside the literal),
 * requiring the closing quote be immediately followed by a comma, or by
 * `end` — rejects `name: "Foo" + suffix`-style concatenation, which a plain
 * quote-scan alone cannot tell apart from a true literal. Every caller here
 * passes the enclosing call's own closing ')' position as `end`, so landing
 * exactly on it after the closing quote correctly means "immediately
 * followed by the close-paren", not just "ran off the end of the buffer".
 * Returns heap string, or NULL (fail-closed). */
static char *swift_quoted_literal(const char *p, const char *end) {
    while (p < end && (*p == ' ' || *p == '\t')) {
        p++;
    }
    if (p >= end || *p != '"') {
        return NULL;
    }
    p++;
    const char *start = p;
    while (p < end && *p != '"' && *p != '\n') {
        if (*p == '\\' && p + SKIP_ONE < end) {
            p += PAIR_LEN;
            continue;
        }
        p++;
    }
    if (p >= end || *p != '"') {
        return NULL;
    }
    char *value = cbm_strndup(start, (size_t)(p - start));
    p++; /* past closing quote */
    while (p < end && (*p == ' ' || *p == '\t')) {
        p++;
    }
    if (p >= end || *p == ',') {
        return value;
    }
    free(value);
    return NULL;
}

/* Search [start, end) for `needle` via swift_find_code_token (skipping
 * comments/strings), then extract the bare quoted-literal argument
 * immediately following it via swift_quoted_literal. Bounded to `end` so a
 * match can never leak past the enclosing call's own argument list into a
 * later, unrelated declaration. When `out_found` is non-NULL, it is set to
 * whether `needle` was located at all — independent of whether its value
 * parsed as a bare literal — so callers can tell "argument absent" (fine,
 * apply a default) apart from "argument present but not a literal"
 * (unknowable, fail closed). Returns heap string or NULL. */
static char *swift_extract_after(const char *start, const char *end, const char *needle,
                                 bool *out_found) {
    if (out_found) {
        *out_found = false;
    }
    const char *hit = swift_find_code_token(start, end, needle);
    if (!hit) {
        return NULL;
    }
    if (out_found) {
        *out_found = true;
    }
    return swift_quoted_literal(hit + strlen(needle), end);
}

/* Register `target_name` → its resolved source directory: the literal
 * `path:` argument the target declared, if any, else the conventional
 * `Sources/<target_name>` (fixed-convention, same approach parse_cargo_toml
 * takes for `src/lib`). `literal_path` is borrowed; caller retains
 * ownership. */
static void swift_register_target(const char *rel_path, const char *target_name,
                                  const char *literal_path, cbm_pkg_entries_t *entries) {
    if (!target_name || !target_name[0]) {
        return;
    }
    char suffix_buf[PKGMAP_PATH_BUF];
    const char *suffix;
    if (literal_path && literal_path[0]) {
        suffix = literal_path;
    } else {
        snprintf(suffix_buf, sizeof(suffix_buf), "Sources/%s", target_name);
        suffix = suffix_buf;
    }
    char *entry = build_entry_path(rel_path, suffix);
    if (entry) {
        pkg_entries_push(entries, strdup(target_name), entry);
    }
}

/* Scan for `.target(name: "Foo", ...)` declarations, skipping any
 * `.target(` spelling that falls inside a comment or string literal.
 * Non-overlapping: the scan resumes AFTER each matched close paren, so a
 * `dependencies: [.target(name: "Bar")]` reference nested inside Foo's own
 * argument list is never re-visited as a second top-level target.
 *
 * A target with a `path:` argument that isn't a bare literal (computed,
 * concatenated, ...) is skipped entirely, even though its `name:` may be a
 * valid literal: SwiftPM would use the computed path, not the
 * `Sources/<name>` convention, and guessing that convention anyway would
 * mint a location that is not just unconfirmed but actively likely wrong. */
static void swift_scan_targets(const char *source, const char *end, const char *rel_path,
                               cbm_pkg_entries_t *entries) {
    static const char prefix[] = ".target(";
    const char *cursor = source;
    while (cursor < end) {
        const char *hit = swift_find_code_token(cursor, end, prefix);
        if (!hit) {
            return;
        }
        const char *open = hit + strlen(prefix) - SKIP_ONE;
        const char *close = swift_match_paren(open, end);
        if (!close) {
            return; /* unbalanced — nothing further here is trustworthy */
        }
        char *name = swift_extract_after(open, close, "name:", NULL);
        if (name) {
            bool path_present = false;
            char *literal_path = swift_extract_after(open, close, "path:", &path_present);
            if (literal_path || !path_present) {
                swift_register_target(rel_path, name, literal_path, entries);
            }
            free(literal_path);
            free(name);
        }
        cursor = close + SKIP_ONE;
    }
}

/* SwiftPM: Package.swift — targets → Sources/<name> (or their literal
 * `path:`). Products deliberately do not self-register: see the file
 * comment above swift_find_code_token. */
static void parse_package_swift(const char *source, int source_len, const char *rel_path,
                                cbm_pkg_entries_t *entries) {
    const char *end = source + source_len;
    swift_scan_targets(source, end, rel_path, entries);
}

/* ── Public: manifest detection + parsing ──────────────────────── */

bool cbm_pkgmap_try_parse(const char *basename, const char *rel_path, const char *source,
                          int source_len, cbm_pkg_entries_t *entries) {
    if (!basename || !source || source_len <= 0) {
        return false;
    }

    if (strcmp(basename, "package.json") == 0) {
        parse_package_json(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "go.mod") == 0) {
        parse_go_mod(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "Cargo.toml") == 0) {
        parse_cargo_toml(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "pyproject.toml") == 0) {
        parse_pyproject_toml(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "composer.json") == 0) {
        parse_composer_json(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "pubspec.yaml") == 0) {
        parse_pubspec_yaml(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "pom.xml") == 0) {
        parse_pom_xml(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "build.gradle") == 0 || strcmp(basename, "build.gradle.kts") == 0) {
        parse_build_gradle(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "mix.exs") == 0) {
        parse_mix_exs(source, source_len, rel_path, entries);
        return true;
    }
    if (ends_with(basename, ".gemspec")) {
        parse_gemspec(source, source_len, rel_path, entries);
        return true;
    }
    if (strcmp(basename, "Package.swift") == 0) {
        parse_package_swift(source, source_len, rel_path, entries);
        return true;
    }
    return false;
}

/* ── Merge: per-worker entries → hash table ────────────────────── */

/* A composer.json `autoload.psr-4` key: a namespace prefix ending in '\\'. */
static bool pkgmap_is_psr4_prefix(const char *pkg_name) {
    size_t n = pkg_name ? strlen(pkg_name) : 0;
    return n > 0 && pkg_name[n - SKIP_ONE] == '\\';
}

CBMHashTable *cbm_pkgmap_build(cbm_pkg_entries_t *worker_entries, int worker_count,
                               const char *project_name) {
    /* Count total entries */
    int total = 0;
    for (int w = 0; w < worker_count; w++) {
        total += worker_entries[w].count;
    }
    if (total == 0) {
        return NULL;
    }

    CBMHashTable *map = cbm_ht_create(PKGMAP_HT_INIT);
    int merged = 0;

    for (int w = 0; w < worker_count; w++) {
        cbm_pkg_entries_t *we = &worker_entries[w];
        for (int i = 0; i < we->count; i++) {
            /* Convert entry_rel to QN: project.dir.parts. A PSR-4 namespace
             * prefix (key ends in '\\') keeps its repo-relative DIRECTORY
             * instead: its readers map `Prefix\Sub\Class` onto a file path
             * (<dir>/Sub/Class.php), which a dotted QN cannot express (#1186). */
            const char *entry_rel = we->items[i].entry_rel;
            char *qn = pkgmap_is_psr4_prefix(we->items[i].pkg_name)
                           ? cbm_strndup(entry_rel, strlen(entry_rel))
                           : cbm_pipeline_fqn_module(project_name, entry_rel);
            if (!qn) {
                continue;
            }

            /* Check for duplicate — first wins */
            if (cbm_ht_has(map, we->items[i].pkg_name)) {
                free(qn);
                continue;
            }

            /* Transfer ownership: key = strdup'd pkg_name, value = qn */
            char *key = strdup(we->items[i].pkg_name);
            cbm_ht_set(map, key, qn);
            merged++;
        }
    }

    if (merged == 0) {
        cbm_ht_free(map);
        return NULL;
    }
    cbm_log_info("pkgmap.build", "entries", pkgmap_itoa(merged));
    return map;
}

/* Returns true if basename is a package manifest we know how to parse.
 * Used by the filesystem walker; cbm_pkgmap_try_parse is the source of
 * truth for which basenames produce entries. */
static bool is_pkgmap_manifest_basename(const char *basename) {
    if (!basename) {
        return false;
    }
    if (strcmp(basename, "package.json") == 0 || strcmp(basename, "go.mod") == 0 ||
        strcmp(basename, "Cargo.toml") == 0 || strcmp(basename, "pyproject.toml") == 0 ||
        strcmp(basename, "composer.json") == 0 || strcmp(basename, "pubspec.yaml") == 0 ||
        strcmp(basename, "pom.xml") == 0 || strcmp(basename, "build.gradle") == 0 ||
        strcmp(basename, "build.gradle.kts") == 0 || strcmp(basename, "mix.exs") == 0 ||
        strcmp(basename, "Package.swift") == 0) {
        return true;
    }
    return ends_with(basename, ".gemspec");
}

/* Stat a path, skipping symlinks. Returns 0 on success, -1 to skip.
 * On POSIX, lstat + S_ISLNK avoids following symlink cycles. On Windows
 * we use the UTF-8-safe wide stat (mirroring discover.c's wide_stat);
 * reparse points (junctions/symlinks) are detected separately by
 * pkgmap_is_reparse_point below before we descend. Mirrors discover.c's
 * safe_stat. */
static int pkgmap_safe_stat(const char *abs_path, struct stat *st) {
#ifdef _WIN32
    wchar_t *wpath = cbm_path_to_wide(abs_path);
    if (!wpath) {
        return CBM_NOT_FOUND;
    }
    struct _stat64 wst;
    int ret = _wstat64(wpath, &wst);
    free(wpath);
    if (ret != 0) {
        return CBM_NOT_FOUND;
    }
    st->st_mode = wst.st_mode;
    st->st_size = wst.st_size;
    st->st_mtime = wst.st_mtime;
    return 0;
#else
    if (lstat(abs_path, st) != 0) {
        return CBM_NOT_FOUND;
    }
    if (S_ISLNK(st->st_mode)) {
        return CBM_NOT_FOUND;
    }
    return 0;
#endif
}

/* True if abs_path is a Windows reparse point (directory junction or
 * symlink). Following these is the documented cause of the historic CI
 * hang, so we skip them before recursing. On POSIX this is a no-op
 * (symlinks are already filtered by pkgmap_safe_stat's S_ISLNK check).
 * Note: the PKGMAP_WALK_MAX_DEPTH bound below is the hard termination
 * guarantee; this check is a best-effort early skip on top of it. */
#ifdef _WIN32
static bool pkgmap_is_reparse_point(const char *abs_path) {
    wchar_t *wpath = cbm_path_to_wide(abs_path);
    if (!wpath) {
        return false;
    }
    DWORD attrs = GetFileAttributesW(wpath);
    free(wpath);
    if (attrs == INVALID_FILE_ATTRIBUTES) {
        return false;
    }
    return (attrs & FILE_ATTRIBUTE_REPARSE_POINT) != 0;
}
#endif

/* Recursive filesystem walker that finds and parses package manifest
 * files independently of the main discovery filter. The main discovery
 * filter intentionally hides package.json / composer.json etc. from
 * code indexing (they're config, not source), but pass_pkgmap still
 * needs to read them to resolve workspace imports. Skips directories
 * matched by the shared cbm_should_skip_dir helper so we don't walk
 * node_modules, .git, build, etc. Returns the number of manifests
 * parsed, accumulated across the whole walk.
 *
 * Cross-platform: uses the portable cbm_opendir/cbm_readdir/cbm_closedir
 * API (same as src/discover/discover.c) and the symlink-skipping
 * pkgmap_safe_stat. Termination is guaranteed by the PKGMAP_WALK_MAX_DEPTH
 * recursion bound — even directory junctions / symlink cycles cannot make
 * it hang. On Windows we additionally skip reparse points before
 * descending as a best-effort early-out. */
static int pkgmap_walk_dir(const char *abs_dir, const char *rel_dir, cbm_pkg_entries_t *entries,
                           int depth, char **excluded_dirs, int excluded_count) {
    if (depth >= PKGMAP_WALK_MAX_DEPTH) {
        cbm_log_info("pkgmap.walk", "depth_cap", rel_dir && rel_dir[0] ? rel_dir : ".");
        return 0;
    }
    cbm_dir_t *dir = cbm_opendir(abs_dir);
    if (!dir) {
        return 0;
    }
    int parsed = 0;
    cbm_dirent_t *entry;
    while ((entry = cbm_readdir(dir)) != NULL) {
        const char *name = entry->name;
        if (name[0] == '.' && (name[1] == '\0' || (name[1] == '.' && name[2] == '\0'))) {
            continue;
        }
        char abs_path[PKGMAP_PATH_BUF];
        char rel_path[PKGMAP_PATH_BUF];
        snprintf(abs_path, sizeof(abs_path), "%s/%s", abs_dir, name);
        if (rel_dir && rel_dir[0]) {
            snprintf(rel_path, sizeof(rel_path), "%s/%s", rel_dir, name);
        } else {
            snprintf(rel_path, sizeof(rel_path), "%s", name);
        }
        struct stat st;
        if (pkgmap_safe_stat(abs_path, &st) != 0) {
            continue;
        }
        if (S_ISDIR(st.st_mode)) {
            if (cbm_should_skip_dir(name, CBM_MODE_FULL) ||
                cbm_pipeline_relpath_is_excluded(rel_path, excluded_dirs, excluded_count)) {
                continue;
            }
#ifdef _WIN32
            /* Don't follow Windows directory junctions — they can form
             * cycles. The depth bound is the hard guarantee; this just
             * avoids wasted descent. (POSIX symlinks are already skipped by
             * pkgmap_safe_stat's S_ISLNK check.) */
            if (pkgmap_is_reparse_point(abs_path)) {
                continue;
            }
#endif
            parsed += pkgmap_walk_dir(abs_path, rel_path, entries, depth + 1, excluded_dirs,
                                      excluded_count);
            continue;
        }
        if (!S_ISREG(st.st_mode)) {
            continue;
        }
        if (!is_pkgmap_manifest_basename(name)) {
            continue;
        }
        int source_len = 0;
        char *source = pkgmap_read_file(abs_path, &source_len);
        if (!source) {
            continue;
        }
        if (cbm_pkgmap_try_parse(name, rel_path, source, source_len, entries)) {
            parsed++;
        }
        cbm_free(CBM_MEM_CLASS_EXTRACT, source);
    }
    cbm_closedir(dir);
    return parsed;
}

/* Scan a repository for package manifest files via the filesystem
 * walker above. Always-available companion to the parallel path's
 * per-worker manifest parsing, which is bound to whatever `files[]`
 * the discoverer produces and therefore misses ignored manifests like
 * package.json. NULL-safe; returns 0 entries when repo_path is unset.
 *
 * Cross-platform: the walk runs on every platform via pkgmap_walk_dir,
 * which is depth-bounded (PKGMAP_WALK_MAX_DEPTH) and skips symlinks /
 * Windows reparse points, so it cannot hang on directory junctions.
 * This is what lets bare workspace imports (e.g. "@org/pkg" declared in
 * an ignored package.json) resolve on Windows as well as POSIX. */
int cbm_pkgmap_scan_repo(const char *repo_path, cbm_pkg_entries_t *entries, char **excluded_dirs,
                         int excluded_count) {
    if (!repo_path || !entries) {
        return 0;
    }
    int parsed = pkgmap_walk_dir(repo_path, "", entries, 0, excluded_dirs, excluded_count);
    cbm_log_info("pkgmap.scan_repo", "manifests", pkgmap_itoa(parsed));
    return parsed;
}

/* Build pkgmap for sequential path (reads manifest files directly) */
CBMHashTable *cbm_pkgmap_build_from_files(const cbm_file_info_t *files, int file_count,
                                          const char *project_name) {
    cbm_pkg_entries_t entries;
    cbm_pkg_entries_init(&entries);

    for (int i = 0; i < file_count; i++) {
        const char *basename = path_basename(files[i].rel_path);
        if (!is_pkgmap_manifest_basename(basename)) {
            continue;
        }

        /* Read file */
        int source_len = 0;
        char *source = pkgmap_read_file(files[i].path, &source_len);
        if (!source) {
            continue;
        }
        cbm_pkgmap_try_parse(basename, files[i].rel_path, source, source_len, &entries);
        cbm_free(CBM_MEM_CLASS_EXTRACT, source);
    }

    CBMHashTable *map = cbm_pkgmap_build(&entries, SKIP_ONE, project_name);
    cbm_pkg_entries_free(&entries);
    return map;
}

/* Variant of cbm_pkgmap_build_from_files that ALSO walks the repo
 * filesystem to pick up manifests filtered out by the main discoverer
 * (the canonical case: package.json, which is in IGNORED_JSON_FILES).
 * Falls back to the files[]-only behaviour if repo_path is NULL. */
CBMHashTable *cbm_pkgmap_build_from_repo(const char *repo_path, const cbm_file_info_t *files,
                                         int file_count, const char *project_name,
                                         char **excluded_dirs, int excluded_count) {
    cbm_pkg_entries_t entries;
    cbm_pkg_entries_init(&entries);

    /* Manifests already visible through discovery (Cargo.toml, go.mod,
     * pyproject.toml, ...). package.json typically isn't, but we still
     * harvest whatever the discovery filter exposed in case downstream
     * filters change. */
    int from_files = 0;
    for (int i = 0; i < file_count; i++) {
        const char *basename = path_basename(files[i].rel_path);
        if (!is_pkgmap_manifest_basename(basename)) {
            continue;
        }
        from_files++;
        int source_len = 0;
        char *source = pkgmap_read_file(files[i].path, &source_len);
        if (!source) {
            continue;
        }
        cbm_pkgmap_try_parse(basename, files[i].rel_path, source, source_len, &entries);
        cbm_free(CBM_MEM_CLASS_EXTRACT, source);
    }

    int from_walk = cbm_pkgmap_scan_repo(repo_path, &entries, excluded_dirs, excluded_count);
    cbm_log_info("pkgmap.scan", "manifests_from_files", pkgmap_itoa(from_files),
                 "manifests_from_walk", pkgmap_itoa(from_walk), "entries",
                 pkgmap_itoa(entries.count));
    CBMHashTable *map = cbm_pkgmap_build(&entries, SKIP_ONE, project_name);
    cbm_pkg_entries_free(&entries);
    return map;
}

static void pkgmap_free_entry(const char *key, void *value, void *userdata) {
    (void)userdata;
    free((void *)key);
    free(value);
}

void cbm_pkgmap_free(CBMHashTable *pkgmap) {
    if (!pkgmap) {
        return;
    }
    cbm_ht_foreach(pkgmap, pkgmap_free_entry, NULL);
    cbm_ht_free(pkgmap);
}

/* ── Resolver ──────────────────────────────────────────────────── */

/* Try slash-based prefix matching (Go: github.com/foo/bar/pkg/utils).
 * Returns heap QN or NULL. */
static char *resolve_slash_prefix(CBMHashTable *map, const char *module_path) {
    char *buf = strdup(module_path);
    if (!buf) {
        return NULL;
    }
    for (char *slash = buf + strlen(buf) - SKIP_ONE; slash > buf; slash--) {
        if (*slash != '/') {
            continue;
        }
        *slash = '\0';
        const char *base_qn = (const char *)cbm_ht_get(map, buf);
        if (!base_qn) {
            continue;
        }
        const char *subpath = module_path + (size_t)(slash - buf) + SKIP_ONE;
        char result[PKGMAP_PATH_BUF];
        snprintf(result, sizeof(result), "%s.%s", base_qn, subpath);
        /* Replace / with . in the appended part */
        for (char *c = result + strlen(base_qn) + SKIP_ONE; *c; c++) {
            if (*c == '/') {
                *c = '.';
            }
        }
        free(buf);
        return strdup(result);
    }
    free(buf);
    return NULL;
}

/* Try dot-based prefix matching (Java: com.myorg.pkg.Foo).
 * Returns heap QN or NULL. */
static char *resolve_dot_prefix(CBMHashTable *map, const char *module_path,
                                const char *project_name) {
    char *buf = strdup(module_path);
    if (!buf) {
        return NULL;
    }
    for (char *dot = buf + strlen(buf) - SKIP_ONE; dot > buf; dot--) {
        if (*dot != '.') {
            continue;
        }
        *dot = '\0';
        const char *base_qn = (const char *)cbm_ht_get(map, buf);
        if (!base_qn) {
            continue;
        }
        const char *subpath = module_path + (size_t)(dot - buf) + SKIP_ONE;
        char subpath_slashed[PKGMAP_PATH_BUF];
        snprintf(subpath_slashed, sizeof(subpath_slashed), "%s", subpath);
        for (char *c = subpath_slashed; *c; c++) {
            if (*c == '.') {
                *c = '/';
            }
        }
        char result[PKGMAP_PATH_BUF];
        snprintf(result, sizeof(result), "%s/%s", base_qn, subpath_slashed);
        free(buf);
        return cbm_pipeline_fqn_module(project_name, result);
    }
    free(buf);
    return NULL;
}

/* Try backslash-based prefix matching (PHP PSR-4: App\\Controllers\\Foo).
 * The map value of a PSR-4 prefix is its repo-relative directory (see
 * cbm_pkgmap_build). Returns heap QN or NULL. */
static char *resolve_backslash_prefix(CBMHashTable *map, const char *module_path,
                                      const char *project_name) {
    char *buf = strdup(module_path);
    if (!buf) {
        return NULL;
    }
    for (char *bs = buf + strlen(buf) - SKIP_ONE; bs > buf; bs--) {
        if (*bs != '\\') {
            continue;
        }
        *bs = '\0';
        char prefix[PKGMAP_PATH_BUF];
        snprintf(prefix, sizeof(prefix), "%s\\", buf);
        const char *base_dir = (const char *)cbm_ht_get(map, prefix);
        if (!base_dir) {
            continue;
        }
        const char *subpath = module_path + (size_t)(bs - buf) + SKIP_ONE;
        char path_result[PKGMAP_PATH_BUF];
        snprintf(path_result, sizeof(path_result), "%s%s%s", base_dir, base_dir[0] ? "/" : "",
                 subpath);
        for (char *c = path_result; *c; c++) {
            if (*c == '\\') {
                *c = '/';
            }
        }
        free(buf);
        return cbm_pipeline_fqn_module(project_name, path_result);
    }
    free(buf);
    return NULL;
}

char *cbm_pipeline_resolve_module(const cbm_pipeline_ctx_t *ctx, const char *source_rel,
                                  const char *module_path) {
    if (!ctx || !module_path) {
        return cbm_pipeline_fqn_module(ctx ? ctx->project_name : NULL, module_path);
    }

    /* 1. Try relative import resolution (existing logic) */
    char *resolved = cbm_pipeline_resolve_relative_import(source_rel, module_path);
    if (resolved) {
        /* The relative resolver has already removed an explicit JS/TS file
         * extension.  Treat the remaining path as a module path verbatim so a
         * dotted extensionless basename such as `featureX.engine` is not
         * stripped a second time by cbm_pipeline_fqn_module. */
        char *qn = cbm_pipeline_fqn_folder(ctx->project_name, resolved);
        free(resolved);
        return qn;
    }

    /* 1b. Try build-tool path aliases (tsconfig/jsconfig paths today;
     *     other loaders can register here later). Independent of pkgmap. */
    if (ctx->path_aliases && source_rel) {
        const cbm_path_alias_map_t *amap =
            cbm_path_alias_find_for_file(ctx->path_aliases, source_rel);
        if (amap) {
            char *aliased = cbm_path_alias_resolve(amap, module_path);
            if (aliased) {
                char *qn = cbm_pipeline_fqn_module(ctx->project_name, aliased);
                free(aliased);
                return qn;
            }
        }
    }

    /* 2. No pkgmap → fall through immediately */
    CBMHashTable *pkgmap = cbm_pipeline_get_pkgmap();
    if (!pkgmap) {
        return cbm_pipeline_fqn_module(ctx->project_name, module_path);
    }

    /* 3. Exact lookup */
    const char *mapped_qn = (const char *)cbm_ht_get(pkgmap, module_path);
    if (mapped_qn) {
        return strdup(mapped_qn);
    }

    /* 4. Prefix matching by separator type */
    char *result = resolve_slash_prefix(pkgmap, module_path);
    if (!result) {
        result = resolve_dot_prefix(pkgmap, module_path, ctx->project_name);
    }
    if (!result) {
        result = resolve_backslash_prefix(pkgmap, module_path, ctx->project_name);
    }
    if (result) {
        return result;
    }

    /* 5. Fallthrough to default resolution */
    return cbm_pipeline_fqn_module(ctx->project_name, module_path);
}

/* ── Import-target node resolver ─────────────────────────────────── */

/* Return the last path segment of an import string, recognizing the separators
 * used across languages: '.', '/', '\\', and "::".  Returns a pointer into
 * `path` (no allocation). */
static const char *import_last_segment(const char *path) {
    const char *seg = path;
    for (const char *p = path; *p; p++) {
        if (*p == '.' || *p == '/' || *p == '\\' || *p == ':') {
            seg = p + 1;
        }
    }
    return seg;
}

/* Derive a representative imported symbol name from a raw module/use path,
 * stripping language decorations so it can be matched against an in-graph node:
 *   - trailing alias " as X"      (Rust/Kotlin)
 *   - trailing glob "::*" / ".*"  (Rust/Kotlin/Java wildcard)
 *   - brace groups "{a, b, ...}"  (Rust grouped use) → first member
 * Writes the result into `out` (size `outsz`) and returns it, or NULL if none.
 * For grouped/braced forms the first listed symbol is used as the representative
 * (the tests only require at least one resolved IMPORTS edge per statement). */
static const char *import_candidate_symbol(const char *module_path, char *out, size_t outsz) {
    if (!module_path || !module_path[0]) {
        return NULL;
    }
    char buf[1024];
    snprintf(buf, sizeof(buf), "%s", module_path);

    /* Brace group: `prefix::{a, b}` → take first member `a`. */
    char *brace = strchr(buf, '{');
    if (brace) {
        char *first = brace + 1;
        char *end = first;
        while (*end && *end != ',' && *end != '}') {
            end++;
        }
        *end = '\0';
        /* Trim whitespace. */
        while (*first == ' ' || *first == '\t') {
            first++;
        }
        char *t = first + strlen(first);
        while (t > first && (t[-1] == ' ' || t[-1] == '\t')) {
            *--t = '\0';
        }
        if (first[0] && strcmp(first, "self") != 0) {
            snprintf(out, outsz, "%s", first);
            return out;
        }
        /* `{self, ...}` → fall back to the path before the brace group. */
        *brace = '\0';
    }

    /* Strip trailing " as <alias>". */
    char *as = strstr(buf, " as ");
    if (as) {
        *as = '\0';
    }

    /* Strip trailing glob and separator noise. */
    size_t len = strlen(buf);
    while (len > 0 && (buf[len - 1] == '*' || buf[len - 1] == ':' || buf[len - 1] == '.' ||
                       buf[len - 1] == '/' || buf[len - 1] == '\\' || buf[len - 1] == ' ')) {
        buf[--len] = '\0';
    }
    if (!buf[0]) {
        return NULL;
    }
    const char *seg = import_last_segment(buf);
    if (!seg || !seg[0] || strcmp(seg, "*") == 0) {
        return NULL;
    }
    snprintf(out, outsz, "%s", seg);
    return out;
}

/* True for node labels that represent an importable definition (so a symbol-name
 * fallback does not link to, e.g., a Variable or Field). */
static bool import_targetable_label(const char *label) {
    if (!label) {
        return false;
    }
    static const char *ok[] = {"Class", "Interface", "Function", "Method", "Module", "Struct",
                               "Enum",  "Trait",     "Type",     "File",   NULL};
    for (const char **l = ok; *l; l++) {
        if (strcmp(*l, label) == 0) {
            return true;
        }
    }
    return false;
}

/* #2127: a Python import path spells the module chain that owns the imported
 * name (`from unittest.mock import patch` -> unittest, mock). Strategy 3 matches
 * the leaf name alone, so an EXTERNAL import (stdlib / third party: no project
 * module, Strategy 1 misses) bound to any same-named project definition -- a
 * REST view's `patch` handler became the target of every mock.patch call at
 * import_map confidence. For such an external import, accept a symbol hit only
 * when the module segments preceding `name` in the import path occur, in
 * order, among the hit's enclosing QN segments -- a src/ layout or sys.path
 * root the module resolver missed (`from template_tests.utils import setup` ->
 * proj.tests.template_tests.utils.setup) still qualifies. Relative prefixes
 * (leading dots) carry no segment and are skipped. Imports of project modules
 * are never judged by it (they may re-export from anywhere). Python only. */
enum { PY_IMPORT_MAX_SEGS = 64 };
bool cbm_python_import_path_matches_qn(const char *module_path, const char *name,
                                       const char *hit_qn) {
    if (!module_path || !name || !hit_qn) {
        return true;
    }
    char path[1024];
    snprintf(path, sizeof(path), "%s", module_path);
    char *as = strstr(path, " as ");
    if (as) {
        *as = '\0';
    }
    const char *p = path;
    while (*p == '.') {
        p++;
    }
    /* Segments of the import path; name_at = index of the LAST `name`. */
    const char *segs[PY_IMPORT_MAX_SEGS];
    size_t lens[PY_IMPORT_MAX_SEGS];
    int nseg = 0;
    int name_at = -1;
    size_t name_len = strlen(name);
    while (*p && nseg < PY_IMPORT_MAX_SEGS) {
        const char *dot = strchr(p, '.');
        size_t len = dot ? (size_t)(dot - p) : strlen(p);
        if (len == name_len && strncmp(p, name, len) == 0) {
            name_at = nseg;
        }
        segs[nseg] = p;
        lens[nseg] = len;
        nseg++;
        if (!dot) {
            break;
        }
        p = dot + SKIP_ONE;
    }
    if (name_at <= 0) {
        return true; /* no module chain before the name: nothing to check */
    }
    /* Ordered-subsequence match against the hit's enclosing segments (every
     * segment before the hit's own leaf). */
    const char *leaf = strrchr(hit_qn, '.');
    const char *q = hit_qn;
    int want = 0;
    while (want < name_at && leaf && q < leaf) {
        const char *dot = strchr(q, '.');
        size_t len = (size_t)(dot - q);
        if (len == lens[want] && strncmp(q, segs[want], len) == 0) {
            want++;
        }
        q = dot + SKIP_ONE;
    }
    return want == name_at;
}

/* #2127, call side: an imported name binds the file's identifier to that
 * import for the whole module, exactly like a parameter binds it for a body.
 * When the import could not be materialized (external module) the resolver
 * falls through to project-wide short-name strategies and binds `patch(...)`
 * (or `mock.patch(...)`) to whatever project definition shares the leaf. True
 * when the callee's root identifier is bound by this file's Python imports and
 * EVERY such binding's module chain (`unittest.mock` for `from unittest.mock
 * import patch`; the callee's own dotted path for a root `import a.b`) is
 * absent from `resolved_qn`'s enclosing segments AND the binding is external
 * (no IMPORTS edge materialized it: the module is not in the project). An
 * internal binding is never judged here -- a project module can re-export a
 * name from anywhere -- and a chain consistent with the target (src/ layout)
 * keeps the edge. `gbuf` NULL means "no IMPORTS edges" (all external). */
static bool python_import_local_materialized(const cbm_gbuf_t *gbuf, const char *project_name,
                                             const char *rel_path, const char *local_name) {
    if (!gbuf || !rel_path) {
        return false;
    }
    char *file_qn = cbm_pipeline_fqn_compute(project_name, rel_path, "__file__");
    const cbm_gbuf_node_t *file_node = file_qn ? cbm_gbuf_find_by_qn(gbuf, file_qn) : NULL;
    safe_free(file_qn);
    const cbm_gbuf_edge_t **edges = NULL;
    int edge_count = 0;
    if (!file_node || cbm_gbuf_find_edges_by_source_type(gbuf, file_node->id, "IMPORTS", &edges,
                                                         &edge_count) != 0) {
        return false;
    }
    char needle[CBM_SZ_256];
    snprintf(needle, sizeof(needle), "\"local_name\":\"%s\"", local_name);
    for (int i = 0; i < edge_count; i++) {
        if (edges[i]->properties_json && strstr(edges[i]->properties_json, needle)) {
            return true;
        }
    }
    return false;
}

bool cbm_python_import_binding_contradicts(const CBMImportArray *imports, const char *callee_name,
                                           const char *resolved_qn, const cbm_gbuf_t *gbuf,
                                           const char *project_name, const char *rel_path) {
    if (!imports || imports->count <= 0 || !callee_name || !callee_name[0] || !resolved_qn ||
        !resolved_qn[0]) {
        return false;
    }
    const char *root_end = strchr(callee_name, '.');
    size_t root_len = root_end ? (size_t)(root_end - callee_name) : strlen(callee_name);
    bool bound = false;
    for (int i = 0; i < imports->count; i++) {
        const CBMImport *imp = &imports->items[i];
        if (!imp->local_name || !imp->module_path || strlen(imp->local_name) != root_len ||
            strncmp(imp->local_name, callee_name, root_len) != 0) {
            continue;
        }
        char full[1024];
        snprintf(full, sizeof(full), "%s", imp->module_path);
        char *as = strstr(full, " as ");
        if (as) {
            *as = '\0';
        }
        const char *path_leaf_seg = strrchr(full, '.');
        bool from_import = path_leaf_seg && strcmp(path_leaf_seg + SKIP_ONE, imp->local_name) == 0;
        if (!as && !from_import && strncmp(full, callee_name, root_len) == 0 &&
            (full[root_len] == '.' || full[root_len] == '\0')) {
            /* `import a.b` binds the ROOT package `a`: the callee already
             * spells its own full dotted path (`a.b.f()`). */
            snprintf(full, sizeof(full), "%s", callee_name);
        } else if (!as && !path_leaf_seg && full[0] != '.' && strcmp(full, imp->local_name) != 0) {
            /* `import m as y` (the extractor stores module_path `m`, local
             * `y`; a from-import always spells a dotted path): `y` IS module
             * `m`, so `y.T` spells `m.T`. */
            snprintf(full, sizeof(full), "%s%s", imp->module_path, callee_name + root_len);
        }
        /* Otherwise (`from m import x [as y]`) only the import's own module
         * chain is evidence: members reached THROUGH x (`x.objects.create`)
         * may live on any type, so they are not compared. */
        const char *leaf = strrchr(full, '.');
        leaf = leaf ? leaf + SKIP_ONE : full;
        if (cbm_python_import_path_matches_qn(full, leaf, resolved_qn) ||
            python_import_local_materialized(gbuf, project_name, rel_path, imp->local_name)) {
            return false; /* consistent with the target, or a project import */
        }
        bound = true;
    }
    return bound;
}

/* Base-class twin of the #2127 call gate. `class SimpleTestCase(
 * unittest.TestCase)` under `import unittest` names the STDLIB base; the
 * registry's same-module suffix fallback (`unittest.TestCase` -> module's
 * `TestCase`) or a short-name strategy bound it to a same-named PROJECT class
 * (django: an inheritance cycle SimpleTestCase -> TestCase ->
 * TransactionTestCase -> SimpleTestCase, plus fabricated OVERRIDEs). An
 * external import binding (never materialized as an IMPORTS edge) whose
 * module chain the target does not spell can never be that target, whatever
 * the registry strategy. Exact metadata import maps remain valid when the
 * target spells the imported module chain. Every base resolver (sequential
 * + parallel semantic, cross-LSP pxc) calls this ONE
 * gate so the venues cannot diverge. Python only. */
bool cbm_python_external_base_contradicts(CBMLanguage lang, const CBMImportArray *imports,
                                          const char *base_spelling, const char *base_qn,
                                          const cbm_gbuf_t *gbuf, const char *project_name,
                                          const char *rel_path) {
    return lang == CBM_LANG_PYTHON &&
           cbm_python_import_binding_contradicts(imports, base_spelling, base_qn, gbuf,
                                                 project_name, rel_path);
}

/* #2127: whether a Python import's module lives in this project. Relative
 * imports always do; otherwise the module part (the path minus the imported
 * name) must resolve to a graph node. Strategy 1 has already failed on the
 * full path when this is asked. */
static bool python_import_module_in_project(const cbm_pipeline_ctx_t *ctx, const char *source_rel,
                                            const char *module_path) {
    if (!module_path || module_path[0] == '.') {
        return true;
    }
    char part[1024];
    snprintf(part, sizeof(part), "%s", module_path);
    char *as = strstr(part, " as ");
    if (as) {
        *as = '\0';
    }
    char *dot = strrchr(part, '.');
    if (!dot) {
        return false; /* `import x`: Strategy 1 already missed x itself */
    }
    *dot = '\0';
    char *qn = cbm_pipeline_resolve_module(ctx, source_rel, part);
    bool found = qn && cbm_gbuf_find_by_qn(ctx->gbuf, qn) != NULL;
    safe_free(qn);
    return found;
}

/* `import a.b` / `import a` (as opposed to `from a import b`): every segment
 * names a module. The extractor binds the ROOT (`a`) for a dotted plain
 * import and the leaf for a from-import; a dot-less path is always a plain
 * import. An aliased form is ambiguous and reads as a from-import. */
static bool python_is_plain_module_import(const CBMImport *imp) {
    const char *p = imp->module_path;
    if (!p || p[0] == '.' || strstr(p, " as ")) {
        return false;
    }
    const char *first_dot = strchr(p, '.');
    if (!first_dot) {
        return true;
    }
    const char *leaf = strrchr(p, '.') + SKIP_ONE;
    size_t root_len = (size_t)(first_dot - p);
    return imp->local_name && strlen(imp->local_name) == root_len &&
           strncmp(imp->local_name, p, root_len) == 0 && strcmp(leaf, imp->local_name) != 0;
}

/* #2127: Strategy 3 hit filter for an EXTERNAL Python import. The hit must
 * spell the import's module chain (a src/ layout the module resolver missed
 * still does), and whatever names a module -- an enclosing path segment, or
 * any segment of a plain `import x` -- can only be a Module/File node (`import
 * copy` must not fall back to a project method called `copy`). */
static bool python_external_hit_rejected(const CBMImport *imp, const char *name,
                                         bool enclosing_segment, const cbm_gbuf_node_t *hit) {
    if (!cbm_python_import_path_matches_qn(imp->module_path, name, hit->qualified_name)) {
        return true;
    }
    bool names_module = enclosing_segment || python_is_plain_module_import(imp);
    return names_module && strcmp(hit->label, "Module") != 0 && strcmp(hit->label, "File") != 0;
}

/* #1934: whether the name-guess import fallbacks — Strategy 1b (sibling file,
 * whose label filter admits symbols) and Strategy 3 (symbol name) — may run
 * for imports from this language. A Go import path names a package — never a
 * function, method
 * or field — and every correct Go import resolves in Strategy 1 (module path
 * → the package's Folder node); when that misses the import is external and
 * the correct result is NO edge. The fallback instead bound the last path
 * segment to an arbitrary same-named project symbol (`import "os/exec"` → a
 * test harness's exec() method, two imports → a Makefile target). Languages
 * whose import genuinely can name a member (Python `from m import f`, Java
 * `import com.example.Foo`, Rust `use crate::ops::helper`) keep it. */
bool cbm_import_symbol_fallback_allowed(CBMLanguage lang) {
    return lang != CBM_LANG_GO;
}

/* A Python def or class declared inside a function body -- a closure, a
 * decorator's `wrapper`, a test's local class -- is a local of that function:
 * no import can name it. Its QN extends a Function/Method node's
 * (proj.tests.mock_inputs.inner.wrapper.mock_getpass.getpass), which is how it
 * is recognised; the symbol-name fallback bound `import getpass` to exactly
 * that def. Only an enclosing def of the SAME file counts: a package
 * __init__.py function can share a submodule's QN (poetry: layouts/__init__.py
 * `def layout` vs layouts/layout.py `class Layout`). Mirrors
 * cbm_registry_add_lang_in_module, which keeps the same symbols out of the call
 * resolver's short-name index. */
static bool import_candidate_is_python_local(const cbm_gbuf_t *gbuf, const cbm_gbuf_node_t *cand) {
    const char *qn = cand->qualified_name;
    const char *slash = cand->file_path ? strrchr(cand->file_path, '/') : NULL;
    char scope[CBM_SZ_512];
    size_t len = qn ? strlen(qn) : 0;
    if (!cand->file_path || len == 0 || len >= sizeof(scope) ||
        cbm_language_for_filename(slash ? slash + SKIP_ONE : cand->file_path) != CBM_LANG_PYTHON) {
        return false;
    }
    memcpy(scope, qn, len + SKIP_ONE);
    for (char *dot = strrchr(scope, '.'); dot; dot = strrchr(scope, '.')) {
        *dot = '\0';
        const cbm_gbuf_node_t *outer = cbm_gbuf_find_by_qn(gbuf, scope);
        if (outer && outer->label && outer->file_path &&
            strcmp(outer->file_path, cand->file_path) == 0 &&
            (strcmp(outer->label, "Function") == 0 || strcmp(outer->label, "Method") == 0)) {
            return true;
        }
    }
    return false;
}

static const char *path_leaf(const char *path) {
    const char *leaf = path;
    for (const char *p = path; p && *p; p++) {
        if (*p == '/' || *p == '\\') {
            leaf = p + 1;
        }
    }
    return leaf;
}

static bool node_in_php_file(const cbm_gbuf_node_t *n) {
    return n && n->file_path && cbm_language_for_filename(path_leaf(n->file_path)) == CBM_LANG_PHP;
}

static bool is_header_include(const char *path) {
    if (!path || !path[0]) {
        return false;
    }
    static const char *header_exts[] = {".h", ".hh", ".hpp", ".hxx", ".inc", ".inl", ".ipp", NULL};
    for (const char **ext = header_exts; *ext; ext++) {
        size_t path_len = strlen(path);
        size_t ext_len = strlen(*ext);
        if (path_len > ext_len && strcmp(path + path_len - ext_len, *ext) == 0) {
            return true;
        }
    }
    return false;
}

static bool is_c_family_source(const char *source_rel) {
    if (!source_rel || !source_rel[0]) {
        return false;
    }
    static const char *exts[] = {".c", ".cc", ".cpp", ".cxx", ".c++",
                                 ".h", ".hh", ".hpp", ".hxx", NULL};
    for (const char **ext = exts; *ext; ext++) {
        size_t path_len = strlen(source_rel);
        size_t ext_len = strlen(*ext);
        if (path_len > ext_len && strcmp(source_rel + path_len - ext_len, *ext) == 0) {
            return true;
        }
    }
    return false;
}

/* Directory depth of a repo-relative path: how many directories sit above it. */
static int include_path_depth(const char *path) {
    int depth = 0;
    for (const char *p = path; *p; p++) {
        if (*p == '/' || *p == '\\') {
            depth++;
        }
    }
    return depth;
}

/* Total order among nodes whose file path ends with the include path. The
 * by-name hits arrive in node-registration order, which under parallel
 * extraction is the workers' merge order and differs run to run; taking the
 * first hit made `#include <linux/device.h>` target include/linux/device.h in
 * one index of the kernel and tools/virtio/linux/device.h in the next (5,821
 * IMPORTS edges moved, and every CALLS edge resolved through those files'
 * import maps moved with them). The include names a file, so a File node
 * outranks a symbol declared in it; among files the least nested path wins
 * (include/ over tools/virtio/), then the smaller path, then the smaller QN
 * — a function of the candidate set alone (O9). */
static bool include_target_outranks(const cbm_gbuf_node_t *cand, const cbm_gbuf_node_t *best) {
    if (!best) {
        return true;
    }
    bool cand_file = strcmp(cand->label, "File") == 0;
    bool best_file = strcmp(best->label, "File") == 0;
    if (cand_file != best_file) {
        return cand_file;
    }
    int cd = include_path_depth(cand->file_path);
    int bd = include_path_depth(best->file_path);
    if (cd != bd) {
        return cd < bd;
    }
    int by_path = strcmp(cand->file_path, best->file_path);
    if (by_path != 0) {
        return by_path < 0;
    }
    return cand->qualified_name && best->qualified_name &&
           strcmp(cand->qualified_name, best->qualified_name) < 0;
}

static const cbm_gbuf_node_t *resolve_exact_file_node(const cbm_pipeline_ctx_t *ctx,
                                                      const char *file_path,
                                                      const char *source_file_qn) {
    if (!ctx || !file_path || !file_path[0]) {
        return NULL;
    }

    const char *leaf = path_leaf(file_path);
    if (!leaf || !leaf[0]) {
        return NULL;
    }

    char stem[PKGMAP_PATH_BUF];
    snprintf(stem, sizeof(stem), "%s", leaf);
    char *last_dot = strrchr(stem, '.');
    if (last_dot && last_dot != stem) {
        *last_dot = '\0';
    }

    const char *names[2] = {stem[0] ? stem : NULL, leaf};
    const cbm_gbuf_node_t *best = NULL;
    for (int ni = 0; ni < 2; ni++) {
        const char *name = names[ni];
        if (!name || !name[0]) {
            continue;
        }

        const cbm_gbuf_node_t **hits = NULL;
        int hit_count = 0;
        if (cbm_gbuf_find_by_name(ctx->gbuf, name, &hits, &hit_count) != 0 || !hits) {
            continue;
        }

        for (int i = 0; i < hit_count; i++) {
            const cbm_gbuf_node_t *cand = hits[i];
            if (!cand || !cand->file_path) {
                continue;
            }

            /* Tie-breaker: Ensure the candidate's actual file_path ends with the
             * specific include path requested (e.g., 'a/util.h' instead of just 'util.h'). */
            if (!ends_with(cand->file_path, file_path)) {
                continue;
            }

            if (!cand->label || !import_targetable_label(cand->label)) {
                continue;
            }
            if (source_file_qn && cand->qualified_name &&
                strcmp(cand->qualified_name, source_file_qn) == 0) {
                continue;
            }
            if (include_target_outranks(cand, best)) {
                best = cand;
            }
        }
    }
    return best;
}

static const cbm_gbuf_node_t *resolve_header_include(const cbm_pipeline_ctx_t *ctx,
                                                     const char *source_rel,
                                                     const char *source_file_qn,
                                                     const char *module_path) {
    if (!is_c_family_source(source_rel) || !is_header_include(module_path)) {
        return NULL;
    }

    const char *base = module_path;
    if (base[0] == '.' && base[1] == '/') {
        base += 2;
    }

    const cbm_gbuf_node_t *exact = resolve_exact_file_node(ctx, base, source_file_qn);
    if (exact) {
        return exact;
    }

    if (source_rel && source_rel[0]) {
        char *dir = path_dirname(source_rel);
        if (dir) {
            char candidate[PKGMAP_PATH_BUF];
            if (dir[0]) {
                snprintf(candidate, sizeof(candidate), "%s/%s", dir, base);
            } else {
                snprintf(candidate, sizeof(candidate), "%s", base);
            }
            free(dir);
            exact = resolve_exact_file_node(ctx, candidate, source_file_qn);
            if (exact) {
                return exact;
            }
        }
    }

    return NULL;
}

static bool explicit_relative_path(const char *p) {
    return strncmp(p, "./", PAIR_LEN) == 0 || strncmp(p, "../", PAIR_LEN + SKIP_ONE) == 0;
}

enum { SIBLING_MAX_CANDS = 4 };

/* The paths resolve_sibling_file tries for module_path, relative to the
 * importer's directory `dir`, in priority order. Returns how many it wrote. */
static int sibling_file_candidates(const char *dir, const char *module_path,
                                   char cands[SIBLING_MAX_CANDS][PKGMAP_PATH_BUF]) {
    int ncand = 0;
    const char *sep = dir[0] ? "/" : "";
    const char *base = module_path;
    /* Skip a leading "./". */
    if (strncmp(base, "./", PAIR_LEN) == 0) {
        base += PAIR_LEN;
    }
    const char *slash = strrchr(base, '/');
    /* 1. Direct sibling: dir/<module_path>. */
    snprintf(cands[ncand++], PKGMAP_PATH_BUF, "%s%s%s", dir, sep, base);
    /* 2. SCSS partial: dir/[subdir/]_<basename>.scss (underscore-prefixed). */
    {
        const char *bn = slash ? slash + SKIP_ONE : base;
        char *dpart = slash ? cbm_strndup(base, (size_t)(slash - base)) : strdup("");
        if (dpart && bn[0] != '_') {
            snprintf(cands[ncand++], PKGMAP_PATH_BUF, "%s%s%s%s_%s.scss", dir, sep, dpart,
                     dpart[0] ? "/" : "", bn);
        }
        free(dpart);
    }
    /* 3. Meson subdir: dir/<module_path>/meson.build. */
    snprintf(cands[ncand++], PKGMAP_PATH_BUF, "%s%s%s/meson.build", dir, sep, base);
    /* 4. Basename sibling: dir/<basename(module_path)>.  Covers include paths
     *    that carry a non-relative prefix (Hyprlang `source = ~/.config/.../x.conf`,
     *    absolute include paths) but reference a file sitting beside the importer.
     *    An explicit `./` or `../` path names one location, which Strategy 1c
     *    resolves exactly; its basename beside the importer is another file (#2797). */
    if (slash && slash[SKIP_ONE] && !explicit_relative_path(module_path)) {
        snprintf(cands[ncand++], PKGMAP_PATH_BUF, "%s%s%s", dir, sep, slash + SKIP_ONE);
    }
    return ncand;
}

/* Resolve a sibling-file import: a bare path/name (no leading "./") that names
 * a file relative to the importer's directory.  This covers build/markup
 * grammars whose import string is a sibling filename or directory rather than a
 * dotted module path:
 *   - SCSS  `@use 'vars'`              → sibling `_vars.scss` (partial underscore)
 *   - Just  `import 'common.just'`     → sibling `common.just`
 *   - BitBake `require mypackage.inc`  → sibling `mypackage.inc`
 *   - Meson `subdir('lib')`            → `lib/meson.build`
 *   - func  `#include "utils.fc"`      → sibling `utils.fc`
 *   - Pony  `use "util"`               → sibling `util.pony`
 * Builds a path relative to source_rel's directory, then looks up the resulting
 * File/Module-node QN (extension is stripped by fqn_module).  Returns a borrowed
 * node or NULL.  Several filename conventions are tried in turn. */
static const cbm_gbuf_node_t *resolve_sibling_file(const cbm_pipeline_ctx_t *ctx,
                                                   const char *source_rel,
                                                   const char *source_file_qn,
                                                   const char *module_path, bool php_only) {
    if (!module_path || !module_path[0]) {
        return NULL;
    }
    /* Directory of the importing file (empty for repo-root files). */
    char *dir = path_dirname(source_rel ? source_rel : "");
    if (!dir) {
        return NULL;
    }

    char cands[SIBLING_MAX_CANDS][PKGMAP_PATH_BUF];
    int ncand = sibling_file_candidates(dir, module_path, cands);

    const cbm_gbuf_node_t *found = NULL;
    for (int i = 0; i < ncand; i++) {
        char *qn = cbm_pipeline_fqn_module(ctx->project_name, cands[i]);
        if (!qn) {
            continue;
        }
        const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(ctx->gbuf, qn);
        free(qn);
        if (n && (!php_only || node_in_php_file(n)) && import_targetable_label(n->label) &&
            (!source_file_qn || !n->qualified_name ||
             strcmp(n->qualified_name, source_file_qn) != 0)) {
            found = n;
            break;
        }
    }
    free(dir);
    return found;
}

/* The File an explicit relative import (`./x`, `../x`) names exactly, for
 * files whose File QN differs from the module QN Strategy 1 tries
 * (`../styles/global.css`, `../layouts/Layout.astro`, #2558). Resolved in
 * stack buffers by cbm_repo_rel_join, which refuses a path above the
 * repository root. */
static const cbm_gbuf_node_t *resolve_relative_file(const cbm_pipeline_ctx_t *ctx,
                                                    const char *source_rel, const char *module_path,
                                                    bool php_only) {
    if (!source_rel || !module_path || !explicit_relative_path(module_path)) {
        return NULL;
    }
    char dir[PKGMAP_PATH_BUF];
    int dir_len = snprintf(dir, sizeof(dir), "%s", source_rel);
    if (dir_len < 0 || (size_t)dir_len >= sizeof(dir)) {
        return NULL;
    }
    char *slash = strrchr(dir, '/');
    if (slash) {
        *slash = '\0';
    } else {
        dir[0] = '\0';
    }
    char path[PKGMAP_PATH_BUF];
    if (!cbm_repo_rel_join(dir, module_path, path, sizeof(path))) {
        return NULL;
    }
    const cbm_gbuf_node_t *file = cbm_pipeline_file_node(ctx->gbuf, ctx->project_name, path);
    return file && (!php_only || node_in_php_file(file)) ? file : NULL;
}

/* ── PHP PSR-4 class imports (#1186) ──────────────────────────────── */

typedef enum {
    PSR4_NOT_APPLICABLE = 0, /* no composer psr-4 prefix covers the import */
    PSR4_RESOLVED,           /* the class file exists: *out is its File node */
    PSR4_UNRESOLVED,         /* a prefix covers it but no class file exists */
} psr4_outcome_t;

/* The File node at exactly `rel_path`, or NULL. Looked up through the name
 * index (File nodes are named by basename) and matched on the full path, so
 * a same-named file in another directory never qualifies. */
static const cbm_gbuf_node_t *psr4_file_node(const cbm_gbuf_t *gbuf, const char *rel_path) {
    const cbm_gbuf_node_t **hits = NULL;
    int hit_count = 0;
    if (cbm_gbuf_find_by_name(gbuf, path_leaf(rel_path), &hits, &hit_count) != 0 || !hits) {
        return NULL;
    }
    for (int i = 0; i < hit_count; i++) {
        const cbm_gbuf_node_t *n = hits[i];
        if (n && n->label && strcmp(n->label, "File") == 0 && n->file_path &&
            strcmp(n->file_path, rel_path) == 0) {
            return n;
        }
    }
    return NULL;
}

/* Resolve a PHP class import `use A\B\C;` the way composer's PSR-4 autoloader
 * does: for every autoload.psr-4 prefix covering the name, longest first, the
 * class lives in exactly <prefix-dir>/<rest>.php with sub-namespaces as
 * subdirectories; the first existing file wins. When a prefix covers the name
 * but no such file exists the import is UNRESOLVED: it must never fall through
 * to the namespace bucket, which binds it to whichever file of the namespace
 * came first. `use function` / `use const` name namespace members, not class
 * files, so they are not applicable. */
static psr4_outcome_t resolve_php_psr4_class(const cbm_gbuf_t *gbuf, const char *source_file_qn,
                                             const CBMImport *imp, const cbm_gbuf_node_t **out) {
    *out = NULL;
    CBMHashTable *pkgmap = cbm_pipeline_get_pkgmap();
    if (!pkgmap || imp->kind != CBM_IMPORT_KIND_DEFAULT) {
        return PSR4_NOT_APPLICABLE;
    }
    const char *name = imp->module_path;
    if (name[0] == '\\') {
        name++; /* fully qualified `use \App\X;` */
    }
    char key[PKGMAP_PATH_BUF];
    size_t name_len = strlen(name);
    if (name_len == 0 || name_len >= sizeof(key) || !strchr(name, '\\')) {
        return PSR4_NOT_APPLICABLE;
    }
    bool covered = false;
    /* Right to left: each '\' ends a candidate prefix, longest first. */
    for (size_t cut = name_len - SKIP_ONE; cut > 0; cut--) {
        if (name[cut - SKIP_ONE] != '\\') {
            continue;
        }
        memcpy(key, name, cut);
        key[cut] = '\0';
        const char *dir = (const char *)cbm_ht_get(pkgmap, key);
        if (!dir) {
            continue;
        }
        covered = true;
        char rel[PKGMAP_PATH_BUF];
        int w = snprintf(rel, sizeof(rel), "%s%s%s.php", dir, dir[0] ? "/" : "", name + cut);
        if (w <= 0 || (size_t)w >= sizeof(rel)) {
            continue;
        }
        for (char *c = rel; *c; c++) {
            if (*c == '\\') {
                *c = '/';
            }
        }
        const cbm_gbuf_node_t *file = psr4_file_node(gbuf, rel);
        if (file && (!source_file_qn || !file->qualified_name ||
                     strcmp(file->qualified_name, source_file_qn) != 0)) {
            *out = file;
            return PSR4_RESOLVED;
        }
    }
    return covered ? PSR4_UNRESOLVED : PSR4_NOT_APPLICABLE;
}

static bool psr4_class_label(const char *label) {
    return label && (strcmp(label, "Class") == 0 || strcmp(label, "Interface") == 0 ||
                     strcmp(label, "Trait") == 0 || strcmp(label, "Enum") == 0);
}

/* The QN of `member` on the class `cls` defined in `file_path`, or NULL when
 * that file defines no such class or the class has no such member. */
static const char *psr4_member_in_file(const cbm_gbuf_t *gbuf, const char *file_path,
                                       const char *cls, const char *member) {
    const cbm_gbuf_node_t **hits = NULL;
    int hit_count = 0;
    if (cbm_gbuf_find_by_name(gbuf, cls, &hits, &hit_count) != 0 || !hits) {
        return NULL;
    }
    for (int i = 0; i < hit_count; i++) {
        const cbm_gbuf_node_t *c = hits[i];
        if (!c || !psr4_class_label(c->label) || !c->qualified_name || !c->file_path ||
            strcmp(c->file_path, file_path) != 0) {
            continue;
        }
        char qn[CBM_SZ_1K];
        int w = snprintf(qn, sizeof(qn), "%s.%s", c->qualified_name, member);
        if (w <= 0 || (size_t)w >= sizeof(qn)) {
            return NULL;
        }
        const cbm_gbuf_node_t *m = cbm_gbuf_find_by_qn(gbuf, qn);
        return m ? m->qualified_name : NULL;
    }
    return NULL;
}

cbm_psr4_member_t cbm_pipeline_psr4_member_qn(const cbm_gbuf_t *gbuf, const char *class_fqn,
                                              const char *member, const char **out_qn) {
    *out_qn = NULL;
    if (!gbuf || !class_fqn || !member || !member[0]) {
        return CBM_PSR4_MEMBER_NOT_COVERED;
    }
    const CBMImport imp = {.module_path = class_fqn, .kind = CBM_IMPORT_KIND_DEFAULT};
    const cbm_gbuf_node_t *file = NULL;
    psr4_outcome_t placed = resolve_php_psr4_class(gbuf, NULL, &imp, &file);
    if (placed == PSR4_NOT_APPLICABLE) {
        return CBM_PSR4_MEMBER_NOT_COVERED;
    }
    /* Covered from here on: composer would load this file or none, so a
     * missing file, class or member leaves the member unresolved. */
    if (placed != PSR4_RESOLVED || !file->file_path) {
        return CBM_PSR4_MEMBER_UNRESOLVED;
    }
    const char *cls = strrchr(class_fqn, '\\');
    cls = cls ? cls + SKIP_ONE : class_fqn;
    *out_qn = psr4_member_in_file(gbuf, file->file_path, cls, member);
    return *out_qn ? CBM_PSR4_MEMBER_RESOLVED : CBM_PSR4_MEMBER_UNRESOLVED;
}

/* A kustomization entry naming a remote base -- a URL, a go-getter host path,
 * an ssh remote or a `?ref=` pin -- lies outside the repository. */
static bool kustomize_remote_entry(const char *entry) {
    static const char *const hosts[] = {"github.com/", "gitlab.com/", "bitbucket.org/", "git@",
                                        NULL};
    if (strstr(entry, "://") || strstr(entry, "?ref=") || strstr(entry, ".git/")) {
        return true;
    }
    for (int i = 0; hosts[i]; i++) {
        if (strncmp(entry, hosts[i], strlen(hosts[i])) == 0) {
            return true;
        }
    }
    return false;
}

static bool kustomize_file_label(const char *label) {
    return label && (strcmp(label, "Module") == 0 || strcmp(label, "File") == 0);
}

/* The Folder of a directory entry: plain, or `proj.pkg.base/` when a file
 * beside it shares the stem (cbm_stem_marks_t). */
static const cbm_gbuf_node_t *kustomize_folder(const cbm_pipeline_ctx_t *ctx, const char *path) {
    char *fqn = cbm_pipeline_fqn_folder(ctx->project_name, path);
    if (!fqn) {
        return NULL;
    }
    const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(ctx->gbuf, fqn);
    if (!n || !n->label || strcmp(n->label, "Folder") != 0) {
        char marked[PKGMAP_PATH_BUF];
        int len = snprintf(marked, sizeof(marked), "%s/", fqn);
        n = len > 0 && (size_t)len < sizeof(marked) ? cbm_gbuf_find_by_qn(ctx->gbuf, marked) : NULL;
    }
    free(fqn);
    return n && n->label && strcmp(n->label, "Folder") == 0 ? n : NULL;
}

/* A kustomization entry is a path relative to the kustomization's own
 * directory -- a manifest file or a directory -- or a remote base; it never
 * names a symbol. Resolve it exactly or not at all: the name-guess strategies
 * bound a remote base's URL segment `deploy` to a shell function, component
 * paths to Go structs, and an entry's basename to a same-named file beside
 * the importer. */
static const cbm_gbuf_node_t *resolve_kustomize_entry(const cbm_pipeline_ctx_t *ctx,
                                                      const char *source_rel, const char *entry) {
    if (!entry[0] || kustomize_remote_entry(entry)) {
        return NULL;
    }
    /* "x.yaml" and "./x.yaml" name the same file; make every entry relative. */
    bool dotted = entry[0] == '.' && (entry[1] == '/' || (entry[1] == '.' && entry[2] == '/'));
    char rel[PKGMAP_PATH_BUF];
    snprintf(rel, sizeof(rel), "%s%s", dotted ? "" : "./", entry);
    char *path = cbm_pipeline_resolve_relative_import(source_rel, rel);
    if (!path) {
        return NULL;
    }
    const cbm_gbuf_node_t *found = NULL;
    char *qn = cbm_pipeline_fqn_module(ctx->project_name, path);
    const cbm_gbuf_node_t *n = qn ? cbm_gbuf_find_by_qn(ctx->gbuf, qn) : NULL;
    free(qn);
    /* The Module must be the entry's own file: a directory entry `base`
     * beside `base.yaml` shares its module QN but names the directory. */
    if (n && kustomize_file_label(n->label) && n->file_path && strcmp(n->file_path, path) == 0) {
        found = n;
    } else {
        found = kustomize_folder(ctx, path);
    }
    free(path);
    return found;
}

/* Language-generic strategies retain their ordering. PHP name imports with
 * no namespace information (and global uses) restrict candidates before any
 * winner is selected, so a non-PHP collision cannot hide a later PHP hit.
 * src_lang is the importing file's language; it gates the name-guess
 * fallbacks (#1934). */
static const cbm_gbuf_node_t *resolve_import_strategies(
    const cbm_pipeline_ctx_t *ctx, const char *source_rel, const char *source_file_qn,
    const CBMImport *imp, CBMHashTable *namespace_map, CBMLanguage src_lang, bool php_only) {
    /* Strategy 1: module-path resolution → existing node (Python/TS/Go).
     * No label filter here: directory-module languages (Go/Java packages)
     * legitimately resolve straight to a Folder node -- that's the intended,
     * correct import target, not a collision. The Folder-collision problem
     * (#767) only shows up downstream, in Strategy 4's retry-with-truncated-
     * path loop, which re-enters resolve_module with a DIFFERENT, shortened
     * string that the original import never named. */
    char *target_qn = cbm_pipeline_resolve_module(ctx, source_rel, imp->module_path);
    const cbm_gbuf_node_t *target = target_qn ? cbm_gbuf_find_by_qn(ctx->gbuf, target_qn) : NULL;
    free(target_qn);
    if (target && (!php_only || node_in_php_file(target))) {
        /* Python/TS from-import of a member: module_path is often
         * "pkg.mod.symbol" while resolve_module lands on the Module node
         * "pkg.mod". Prefer the member Function/Class when it exists —
         * required for `from M import f as g` so CALLS can import_map to f
         * (local_name g ≠ f). */
        if (target->label &&
            (strcmp(target->label, "Module") == 0 || strcmp(target->label, "File") == 0)) {
            char symbuf[256];
            const char *sym = import_candidate_symbol(imp->module_path, symbuf, sizeof(symbuf));
            if (sym && sym[0] && strcmp(sym, "*") != 0) {
                const char *mod_tail =
                    import_last_segment(target->qualified_name ? target->qualified_name : "");
                if (!mod_tail || strcmp(mod_tail, sym) != 0) {
                    char member_qn[CBM_SZ_512];
                    snprintf(member_qn, sizeof(member_qn), "%s.%s", target->qualified_name, sym);
                    const cbm_gbuf_node_t *member = cbm_gbuf_find_by_qn(ctx->gbuf, member_qn);
                    if (member && (!php_only || node_in_php_file(member)) &&
                        import_targetable_label(member->label) &&
                        strcmp(member->label, "Module") != 0 &&
                        strcmp(member->label, "File") != 0) {
                        return member;
                    }
                }
            }
        }
        return target;
    }

    /* Name-guess fallbacks below (Strategy 1b sibling-file, Strategy 3
     * symbol-name) are gated per importing-file language — see
     * cbm_import_symbol_fallback_allowed (#1934). */
    const bool symbol_fallback_allowed = cbm_import_symbol_fallback_allowed(src_lang);

    /* Strategy 1b: sibling-file resolution for build/markup grammars whose
     * import string is a sibling filename or directory (SCSS partials, Just/
     * BitBake/func includes, Meson subdir, Pony use). Its label filter admits
     * symbols too, so for Go it re-creates the Strategy-3 bug one directory
     * closer (`os/exec` → a same-package exec() method) — gated the same. */
    if (symbol_fallback_allowed) {
        const cbm_gbuf_node_t *sib =
            resolve_sibling_file(ctx, source_rel, source_file_qn, imp->module_path, php_only);
        if (sib) {
            return sib;
        }
    }

    /* Strategy 1c: relative non-module files can have a File QN that does not
     * match the module QN above. Resolve the exact file after module and
     * sibling lookup. */
    const cbm_gbuf_node_t *rel_file =
        resolve_relative_file(ctx, source_rel, imp->module_path, php_only);
    if (rel_file) {
        return rel_file;
    }

    /* Strategy 2: namespace map.  `using App.Utils`, `import com.example.Foo`,
     * `use App\Utils\Helper` name a NAMESPACE (or a member of it) that the
     * path-based QN cannot express.  Try the full module path and progressively
     * shorter prefixes (dropping the trailing member segment) so both a bare
     * namespace import and a member import resolve to the declaring file. */
    if (namespace_map) {
        /* Normalize separators to '.' for namespace keys (PHP uses '\\').
         * Strip decorations first so `com.example.Util as U`, `crate::ops::*`
         * and `App\Utils\{A, B}` reduce to a clean dotted path. */
        char norm[1024];
        snprintf(norm, sizeof(norm), "%s", imp->module_path);
        char *brace = strchr(norm, '{');
        if (brace) {
            *brace = '\0'; /* drop the group; the prefix is the namespace */
        }
        char *as = strstr(norm, " as ");
        if (as) {
            *as = '\0';
        }
        for (char *p = norm; *p; p++) {
            if (*p == '\\' || *p == ':' || *p == '/') {
                *p = '.';
            }
        }
        /* Strip trailing glob/separator noise. */
        size_t nl = strlen(norm);
        while (nl > 0 && (norm[nl - 1] == '*' || norm[nl - 1] == '.' || norm[nl - 1] == ' ')) {
            norm[--nl] = '\0';
        }
        /* Collapse any "::"-induced empty segments ("a..b" → "a.b"). */
        for (;;) {
            char *dd = strstr(norm, "..");
            if (!dd) {
                break;
            }
            memmove(dd, dd + 1, strlen(dd + 1) + 1);
        }
        for (;;) {
            /* The map value is a '\n'-delimited list of __file__ QNs declaring
             * this namespace. Return the FIRST that is not the importing file,
             * so a same-package wildcard import (`import com.example.*` from a
             * file that is itself in com.example) resolves to a sibling — and
             * deterministically, independent of file-iteration order across
             * platforms (amd64 vs arm64). */
            const char *list = (const char *)cbm_ht_get(namespace_map, norm);
            for (const char *seg = list; seg && *seg;) {
                const char *eol = strchr(seg, '\n');
                size_t len = eol ? (size_t)(eol - seg) : strlen(seg);
                char qbuf[1024];
                if (len > 0 && len < sizeof(qbuf)) {
                    memcpy(qbuf, seg, len);
                    qbuf[len] = '\0';
                    const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(ctx->gbuf, qbuf);
                    if (n && (!php_only || node_in_php_file(n)) &&
                        (!source_file_qn || strcmp(n->qualified_name, source_file_qn) != 0)) {
                        return n;
                    }
                }
                seg = eol ? eol + 1 : NULL;
            }
            char *dot = strrchr(norm, '.');
            if (!dot) {
                break;
            }
            *dot = '\0';
        }
    }

    /* Strategy 3: symbol-name fallback.  Derive a representative imported
     * symbol (handling alias / glob / grouped forms) and match it against an
     * in-graph definition of the same simple name in another file
     * (Rust `helper`, Java `Util`, Kotlin grouped, ...).
     * Gated per importing-file language, like Strategy 1b above (#1934). */
    char symbuf[256];
    /* Prefer the clean candidate from the module path; the local_name may be an
     * alias (Rust `as h`, Kotlin `as U`) that names no real symbol. */
    const char *seg = import_candidate_symbol(imp->module_path, symbuf, sizeof(symbuf));
    if (!seg && imp->local_name && imp->local_name[0] && strcmp(imp->local_name, "*") != 0) {
        seg = imp->local_name;
    }
    /* Build the candidate symbol list: the derived symbol plus, when the import
     * is a dotted member path like `com.example.Config.DEFAULT`, the enclosing
     * type segments (`Config`).  This resolves object/class-member imports to
     * the declaring type when the leaf member isn't an importable node. */
    const char *cands[8];
    int ncands = 0;
    if (seg && seg[0] && strcmp(seg, "*") != 0) {
        cands[ncands++] = seg;
    }
    {
        /* Strip decorations, normalize separators to '.', and collect the
         * trailing path segments (last first) as fallback candidates. */
        char mp[1024];
        snprintf(mp, sizeof(mp), "%s", imp->module_path);
        char *br = strchr(mp, '{');
        if (br) {
            *br = '\0';
        }
        char *as3 = strstr(mp, " as ");
        if (as3) {
            *as3 = '\0';
        }
        for (char *p = mp; *p; p++) {
            if (*p == '\\' || *p == ':' || *p == '/') {
                *p = '.';
            }
        }
        /* Walk segments from the end. */
        char *end = mp + strlen(mp);
        while (end > mp && ncands < 8) {
            char *dot = NULL;
            for (char *p = end - 1; p >= mp; p--) {
                if (*p == '.') {
                    dot = p;
                    break;
                }
            }
            const char *s = dot ? dot + 1 : mp;
            if (s[0] && strcmp(s, "*") != 0) {
                bool dup = false;
                for (int k = 0; k < ncands; k++) {
                    if (strcmp(cands[k], s) == 0) {
                        dup = true;
                        break;
                    }
                }
                if (!dup) {
                    cands[ncands++] = s;
                }
            }
            if (!dot) {
                break;
            }
            *dot = '\0';
            end = dot;
        }
        /* #2127: a Python import whose module is not in the project (stdlib /
         * third party) may only fall back to a hit that spells its chain. */
        const bool py_external =
            symbol_fallback_allowed && src_lang == CBM_LANG_PYTHON &&
            !python_import_module_in_project(ctx, source_rel, imp->module_path);
        for (int ci = 0; symbol_fallback_allowed && ci < ncands; ci++) {
            const cbm_gbuf_node_t **hits = NULL;
            int n = 0;
            if (cbm_gbuf_find_by_name(ctx->gbuf, cands[ci], &hits, &n) == 0 && hits) {
                /* Deterministic winner: hits[] is in node-registration order,
                 * which under parallel extraction varies run to run — taking
                 * the FIRST targetable hit made the same import resolve to
                 * different same-named nodes across runs (xfs: 360 flickering
                 * IMPORTS diff lines between two MT runs). Pick the candidate
                 * with the lexicographically smallest qualified name instead:
                 * stable, content-derived, identical for ST and MT. */
                const cbm_gbuf_node_t *best = NULL;
                for (int i = 0; i < n; i++) {
                    const cbm_gbuf_node_t *cand = hits[i];
                    if (!cand || (php_only && !node_in_php_file(cand)) ||
                        !import_targetable_label(cand->label)) {
                        continue;
                    }
                    /* A Python def-local (#1548) is no importable name. */
                    if (import_candidate_is_python_local(ctx->gbuf, cand)) {
                        continue;
                    }
                    /* Nor is a generated member (a Java record's implicit
                     * accessor, an instance method no import can name). It is
                     * registered by qualified name only, and a package segment
                     * that merely spells it (`javax.crypto.spec` -> spec())
                     * must not bind the import -- or every use of the
                     * imported name -- to it. */
                    if (cbm_node_props_generated(cand->properties_json)) {
                        continue;
                    }
                    if (source_file_qn && cand->qualified_name &&
                        strcmp(cand->qualified_name, source_file_qn) == 0) {
                        continue; /* self */
                    }
                    if (py_external && python_external_hit_rejected(imp, cands[ci], ci > 0, cand)) {
                        continue; /* #2127: not the external module's symbol */
                    }
                    if (!best || (cand->qualified_name && best->qualified_name &&
                                  strcmp(cand->qualified_name, best->qualified_name) < 0)) {
                        best = cand;
                    }
                }
                if (best) {
                    return best;
                }
            }
        }
    }

    /* Strategy 4: crate-relative module path → File/Module node.  Rust glob
     * `use crate::ops::*` names a module, not a symbol; strip the glob and the
     * `crate::`/`self::`/`super::` prefix, convert `::`→`/`, then resolve the
     * remaining path (and successive prefixes) to a Module/File node. */
    {
        char mp[1024];
        snprintf(mp, sizeof(mp), "%s", imp->module_path);
        char *brace = strchr(mp, '{');
        if (brace) {
            *brace = '\0';
        }
        char *as2 = strstr(mp, " as ");
        if (as2) {
            *as2 = '\0';
        }
        /* Convert "::" → "/" (drop the doubled colon cleanly). */
        char clean[1024] = ""; /* first byte defined even on the zero-write path */
        size_t ci = 0;
        for (const char *p = mp; *p && ci + 1 < sizeof(clean); p++) {
            if (*p == ':') {
                if (ci > 0 && clean[ci - 1] == '/') {
                    continue; /* collapse "::" → single "/" */
                }
                clean[ci++] = '/';
            } else if (*p == '*' || *p == ' ') {
                continue;
            } else {
                clean[ci++] = *p;
            }
        }
        clean[ci] = '\0';
        /* Drop trailing slashes. */
        while (ci > 0 && clean[ci - 1] == '/') {
            clean[--ci] = '\0';
        }
        /* Strip a leading crate-relative prefix. */
        const char *body = clean;
        static const char *prefixes[] = {"crate/", "self/", "super/", NULL};
        for (const char **pf = prefixes; *pf; pf++) {
            size_t pl = strlen(*pf);
            if (strncmp(body, *pf, pl) == 0) {
                body += pl;
                break;
            }
        }
        if (body[0]) {
            char work[1024];
            snprintf(work, sizeof(work), "%s", body);
            for (;;) {
                char *rqn = cbm_pipeline_resolve_module(ctx, source_rel, work);
                const cbm_gbuf_node_t *n = rqn ? cbm_gbuf_find_by_qn(ctx->gbuf, rqn) : NULL;
                free(rqn);
                if (n && (!php_only || node_in_php_file(n)) && import_targetable_label(n->label) &&
                    (!source_file_qn || !n->qualified_name ||
                     strcmp(n->qualified_name, source_file_qn) != 0)) {
                    return n;
                }
                char *sl = strrchr(work, '/');
                if (!sl) {
                    break;
                }
                *sl = '\0';
            }
        }
    }

    return NULL;
}

/* ── PHP `use` of a namespaced name (#1186 follow-up) ─────────────── */

/* The shape of a PHP `use` import. The importing file is PHP and the path is
 * a name: identifier segments, joined by '\' when qualified. require/include
 * paths ("lib/x.php", 'a\b.php') contain '/', '.' or quotes: PHP_USE_NONE. */
typedef enum {
    PHP_USE_NONE = 0,   /* not a PHP `use` (other language, require/include) */
    PHP_USE_GLOBAL,     /* `use Closure;` names the global namespace */
    PHP_USE_NAMESPACED, /* `use A\B\C;` */
} php_use_shape_t;

enum { PHP_NON_ASCII_MIN = 0x80 }; /* PHP identifiers admit any byte >= 0x80 */

static bool php_ident_byte(unsigned char c) {
    return c == '_' || isalnum(c) || c >= PHP_NON_ASCII_MIN;
}

static php_use_shape_t php_use_shape(const char *source_rel, const CBMImport *imp) {
    if (!source_rel || cbm_language_for_filename(path_leaf(source_rel)) != CBM_LANG_PHP) {
        return PHP_USE_NONE;
    }
    const char *p = imp->module_path;
    if (p[0] == '\\') {
        p++;
    }
    if (!p[0]) {
        return PHP_USE_NONE;
    }
    bool qualified = false;
    for (; *p; p++) {
        unsigned char c = (unsigned char)*p;
        if (c == '\\') {
            qualified = true;
        } else if (!php_ident_byte(c)) {
            return PHP_USE_NONE;
        }
    }
    return qualified ? PHP_USE_NAMESPACED : PHP_USE_GLOBAL;
}

/* The next usable file of a namespace-map bucket (a '\n'-delimited list of
 * __file__ QNs): a PHP File node that is not the importing file. Advances
 * *cursor past the entry. */
static const cbm_gbuf_node_t *php_bucket_next(const cbm_pipeline_ctx_t *ctx, const char **cursor,
                                              const char *source_file_qn) {
    while (*cursor && **cursor) {
        const char *seg = *cursor;
        const char *eol = strchr(seg, '\n');
        size_t len = eol ? (size_t)(eol - seg) : strlen(seg);
        *cursor = eol ? eol + SKIP_ONE : NULL;
        char qbuf[CBM_SZ_1K];
        if (len == 0 || len >= sizeof(qbuf)) {
            continue;
        }
        memcpy(qbuf, seg, len);
        qbuf[len] = '\0';
        const cbm_gbuf_node_t *n = cbm_gbuf_find_by_qn(ctx->gbuf, qbuf);
        if (n && n->label && strcmp(n->label, "File") == 0 && node_in_php_file(n) &&
            (!source_file_qn || strcmp(n->qualified_name, source_file_qn) != 0)) {
            return n;
        }
    }
    return NULL;
}

/* The file of `bucket` that defines a symbol named `leaf`, or NULL. Exact:
 * the definition must live in that very file (same file_path). */
static const cbm_gbuf_node_t *php_bucket_declaring(const cbm_pipeline_ctx_t *ctx,
                                                   const char *bucket, const char *source_file_qn,
                                                   const char *leaf) {
    const cbm_gbuf_node_t **hits = NULL;
    int hit_count = 0;
    if (!bucket || cbm_gbuf_find_by_name(ctx->gbuf, leaf, &hits, &hit_count) != 0 || !hits) {
        return NULL;
    }
    const char *cursor = bucket;
    for (const cbm_gbuf_node_t *f = php_bucket_next(ctx, &cursor, source_file_qn); f;
         f = php_bucket_next(ctx, &cursor, source_file_qn)) {
        for (int i = 0; i < hit_count; i++) {
            const cbm_gbuf_node_t *h = hits[i];
            if (h && h->label && strcmp(h->label, "File") != 0 && h->file_path && f->file_path &&
                strcmp(h->file_path, f->file_path) == 0) {
                return f;
            }
        }
    }
    return NULL;
}

/* Resolve a PHP namespaced `use` that no psr-4 prefix covers, through the
 * namespaces project files DECLARE. `use A\B\C` names C in namespace A\B (or
 * the namespace A\B\C itself, as an alias): the target is the A\B file that
 * defines C, else a file declaring namespace A\B\C, else the first A\B file.
 * A namespace no project PHP file declares (Illuminate\, Spatie\, ...) is
 * outside the project: the import stays unresolved instead of binding by name
 * to a same-named project symbol, possibly in another language. */
static const cbm_gbuf_node_t *resolve_php_declared_use(const cbm_pipeline_ctx_t *ctx,
                                                       const char *source_file_qn,
                                                       const CBMImport *imp,
                                                       CBMHashTable *namespace_map) {
    const char *name = imp->module_path[0] == '\\' ? imp->module_path + SKIP_ONE : imp->module_path;
    char key[CBM_SZ_1K];
    if (strlen(name) >= sizeof(key)) {
        return NULL;
    }
    snprintf(key, sizeof(key), "%s", name);
    for (char *p = key; *p; p++) {
        if (*p == '\\') {
            *p = '.';
        }
    }
    const char *full_bucket = (const char *)cbm_ht_get(namespace_map, key);
    char *dot = strrchr(key, '.');
    *dot = '\0'; /* PHP_USE_NAMESPACED guarantees a separator */
    const char *parent_bucket = (const char *)cbm_ht_get(namespace_map, key);
    const char *leaf = dot + SKIP_ONE;

    const cbm_gbuf_node_t *hit = php_bucket_declaring(ctx, parent_bucket, source_file_qn, leaf);
    if (!hit) {
        const char *cursor = full_bucket;
        hit = php_bucket_next(ctx, &cursor, source_file_qn);
    }
    if (!hit) {
        const char *cursor = parent_bucket;
        hit = php_bucket_next(ctx, &cursor, source_file_qn);
    }
    return hit;
}

const cbm_gbuf_node_t *cbm_pipeline_resolve_import_node(const cbm_pipeline_ctx_t *ctx,
                                                        const char *source_rel,
                                                        const char *source_file_qn,
                                                        const CBMImport *imp,
                                                        CBMHashTable *namespace_map) {
    if (!ctx || !imp || !imp->module_path) {
        return NULL;
    }

    /* The importing file's language gates the strategies below. */
    const char *src_base = source_rel ? source_rel : "";
    for (const char *pb = src_base; *pb; pb++) {
        if (*pb == '/' || *pb == '\\') {
            src_base = pb + SKIP_ONE;
        }
    }
    const CBMLanguage src_lang = cbm_language_for_filename(src_base);
    if (src_lang == CBM_LANG_KUSTOMIZE) {
        return resolve_kustomize_entry(ctx, source_rel, imp->module_path);
    }

    /* Prefer exact header-file nodes for C/C++ includes so same-stem source or
     * module nodes do not steal the edge target. */
    const cbm_gbuf_node_t *header_target =
        resolve_header_include(ctx, source_rel, source_file_qn, imp->module_path);
    if (header_target) {
        return header_target;
    }

    /* PHP class imports covered by a composer psr-4 prefix name exactly one
     * file; when it is absent the import stays unresolved (#1186). */
    const cbm_gbuf_node_t *psr4_target = NULL;
    switch (resolve_php_psr4_class(ctx->gbuf, source_file_qn, imp, &psr4_target)) {
    case PSR4_RESOLVED:
        return psr4_target;
    case PSR4_UNRESOLVED:
        return NULL;
    case PSR4_NOT_APPLICABLE:
        break;
    }

    const php_use_shape_t php_use = php_use_shape(source_rel, imp);
    if (php_use == PHP_USE_NONE) {
        return resolve_import_strategies(ctx, source_rel, source_file_qn, imp, namespace_map,
                                         src_lang, false);
    }
    /* Any other PHP namespaced `use` resolves only through declared namespaces.
     * A global-namespace `use Closure;` and the CALLS import map (which passes
     * no namespace map) keep the generic strategies, but a PHP `use` never
     * binds to a non-PHP file. */
    if (php_use == PHP_USE_NAMESPACED && namespace_map) {
        return resolve_php_declared_use(ctx, source_file_qn, imp, namespace_map);
    }
    return resolve_import_strategies(ctx, source_rel, source_file_qn, imp, namespace_map, src_lang,
                                     true);
}

/* PHP binding evidence is per File. The first field is canonical so its
 * completion bit can be invalidated without allocating, before a rebuild.
 * Node properties are exclusively owned heap strings; both writers run on
 * the coordinator before resolve workers borrow the graph read-only. */
static const char php_import_complete[] = "{\"php_imports_complete\":1,";

/* A resolver NULL can also mean unsupported input or a failed lookup. Only
 * the bounded namespace-only path and an unaliased global class `use` with no
 * same-named PHP type anywhere admit an absence proof. A covered-but-missing
 * PSR-4 file, any other global use, or an unavailable namespace map leaves the
 * whole file unknown; already resolved IMPORTS are still written. */
/* A global-namespace class `use Exception;` names a project type only when a
 * PHP file declares a class-like symbol of that name. With no such node at all
 * (namespaced ones included, so the proof stays conservative), the import is
 * absent from the project: the PHP builtin or a vendor class. Without this a
 * single `use Exception;` left the whole file's evidence unknown, and its
 * project imports reached the PHP LSP as File QNs again. */
static bool php_global_use_known_absent(const cbm_gbuf_t *gbuf, const CBMImport *imp) {
    if (!gbuf || imp->kind != CBM_IMPORT_KIND_DEFAULT) {
        return false;
    }
    const char *name = imp->module_path[0] == '\\' ? imp->module_path + 1 : imp->module_path;
    if (!name[0] || strcmp(name, imp->local_name) != 0) {
        return false; /* `use X as Y;` keeps the old, unknown verdict */
    }
    const cbm_gbuf_node_t **nodes = NULL;
    int count = 0;
    if (cbm_gbuf_find_by_name(gbuf, name, &nodes, &count) != 0) {
        return false;
    }
    for (int i = 0; i < count; i++) {
        const cbm_gbuf_node_t *n = nodes[i];
        if (!n || !n->label || !node_in_php_file(n)) {
            continue;
        }
        if (strcmp(n->label, "Class") == 0 || strcmp(n->label, "Interface") == 0 ||
            strcmp(n->label, "Trait") == 0 || strcmp(n->label, "Enum") == 0 ||
            strcmp(n->label, "File") == 0 || strcmp(n->label, "Module") == 0) {
            return false;
        }
    }
    return true;
}

static bool php_import_known_absent(const cbm_gbuf_t *gbuf, const char *rel, const CBMImport *imp,
                                    CBMHashTable *namespace_map) {
    if (!namespace_map || !imp->module_path || !imp->local_name || !imp->local_name[0] ||
        (imp->kind != CBM_IMPORT_KIND_DEFAULT && imp->kind != CBM_IMPORT_KIND_FUNCTION &&
         imp->kind != CBM_IMPORT_KIND_CONST))
        return false;
    php_use_shape_t shape = php_use_shape(rel, imp);
    if (shape == PHP_USE_GLOBAL)
        return php_global_use_known_absent(gbuf, imp);
    if (shape != PHP_USE_NAMESPACED)
        return false;
    const char *name = imp->module_path[0] == '\\' ? imp->module_path + 1 : imp->module_path;
    char key[CBM_SZ_1K];
    size_t length = strlen(name);
    if (length >= sizeof(key) || name[0] == '\\' || name[length - 1] == '\\' ||
        strstr(name, "\\\\"))
        return false;
    CBMHashTable *pkgmap = cbm_pipeline_get_pkgmap();
    if (pkgmap && imp->kind == CBM_IMPORT_KIND_DEFAULT) {
        /* The resolver does not handle Composer's fallback empty prefix.
         * Its presence therefore cannot support a negative proof either. */
        if (cbm_ht_get(pkgmap, ""))
            return false;
        for (size_t cut = length - 1; cut > 0; cut--) {
            if (name[cut - 1] != '\\')
                continue;
            memcpy(key, name, cut);
            key[cut] = '\0';
            if (cbm_ht_get(pkgmap, key))
                return false;
        }
    }
    memcpy(key, name, length + 1);
    for (char *p = key; *p; p++)
        if (*p == '\\')
            *p = '.';
    if (cbm_ht_get(namespace_map, key))
        return false;
    *strrchr(key, '.') = '\0';
    return cbm_ht_get(namespace_map, key) == NULL;
}

static bool php_json_string_eq(yyjson_val *value, const char *text) {
    return text ? yyjson_is_str(value) && yyjson_get_len(value) == strlen(text) &&
                      strcmp(yyjson_get_str(value), text) == 0
                : yyjson_is_null(value);
}

static size_t php_json_key_count(yyjson_val *obj, const char *name) {
    size_t idx, max, count = 0;
    yyjson_val *key, *value;
    yyjson_obj_foreach(obj, idx, max, key, value) {
        (void)value;
        if (php_json_string_eq(key, name))
            count++;
    }
    return count;
}

static bool php_binding_identity(yyjson_val *value, const CBMImport *imp) {
    yyjson_val *kind = yyjson_obj_get(value, "kind");
    yyjson_val *def = yyjson_obj_get(value, "is_default");
    return yyjson_is_obj(value) && yyjson_obj_size(value) == 5 && yyjson_is_int(kind) &&
           yyjson_get_int(kind) == (int)imp->kind && yyjson_is_bool(def) &&
           yyjson_get_bool(def) == imp->is_default &&
           php_json_string_eq(yyjson_obj_get(value, "local_name"), imp->local_name) &&
           php_json_string_eq(yyjson_obj_get(value, "module_path"), imp->module_path);
}

static bool php_json_add_string(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key,
                                const char *text) {
    return text ? yyjson_mut_obj_add_strcpy(doc, obj, key, text)
                : yyjson_mut_obj_add_null(doc, obj, key);
}

static yyjson_mut_val *php_binding_json(yyjson_mut_doc *doc, const CBMImport *imp,
                                        const char *target) {
    yyjson_mut_val *obj = yyjson_mut_obj(doc);
    if (!obj || !php_json_add_string(doc, obj, "local_name", imp->local_name) ||
        !php_json_add_string(doc, obj, "module_path", imp->module_path) ||
        !yyjson_mut_obj_add_int(doc, obj, "kind", imp->kind) ||
        !yyjson_mut_obj_add_bool(doc, obj, "is_default", imp->is_default) ||
        !php_json_add_string(doc, obj, "target", target)) {
        return NULL;
    }
    return obj;
}

/* Validate the entire snapshot, including bindings that coalesced into one
 * (source, target, local_name) edge. A positive insertion ID alone is not
 * evidence that all properties and secondary indexes were stored. */
static bool php_read_binding_snapshot(const cbm_gbuf_t *gbuf, const cbm_gbuf_node_t *file,
                                      const CBMFileResult *result, const char *json,
                                      cbm_php_vendor_names_t *out) {
    if (!json || strncmp(json, php_import_complete, sizeof(php_import_complete) - 1) != 0)
        return false;
    yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
    if (!doc)
        return false;
    yyjson_val *root = yyjson_doc_get_root(doc);
    yyjson_val *manifest = yyjson_obj_get(root, "php_import_bindings");
    int count = result->imports.count;
    const cbm_gbuf_edge_t **edges = NULL;
    int edge_count = 0;
    const char **targets = NULL;
    int *seen = NULL;
    bool ok =
        count >= 0 && (count == 0 || result->imports.items) &&
        php_json_key_count(root, "php_imports_complete") == 1 &&
        php_json_key_count(root, "php_import_bindings") == 1 && yyjson_is_arr(manifest) &&
        yyjson_arr_size(manifest) == (size_t)count &&
        cbm_gbuf_find_edges_by_source_type(gbuf, file->id, "IMPORTS", &edges, &edge_count) == 0 &&
        edge_count >= 0 && (edge_count == 0 || edges);
    if (!ok)
        goto done;
    size_t slots = count > 0 ? (size_t)count : 1;
    if (slots > SIZE_MAX / sizeof(*targets) || slots > SIZE_MAX / sizeof(*seen)) {
        ok = false;
        goto done;
    }
    targets = cbm_calloc(CBM_MEM_CLASS_OTHER, slots * sizeof(*targets));
    seen = cbm_calloc(CBM_MEM_CLASS_OTHER, slots * sizeof(*seen));
    if (!targets || !seen) {
        ok = false;
        goto done;
    }
    for (int i = 0; ok && i < count; i++) {
        yyjson_val *entry = yyjson_arr_get(manifest, (size_t)i);
        yyjson_val *target = yyjson_obj_get(entry, "target");
        ok = php_binding_identity(entry, &result->imports.items[i]);
        if (yyjson_is_str(target)) {
            const cbm_gbuf_node_t *node = cbm_gbuf_find_by_qn(gbuf, yyjson_get_str(target));
            ok = ok && node && node->id != file->id && node->qualified_name &&
                 php_json_string_eq(target, node->qualified_name);
            if (ok)
                targets[i] = node->qualified_name;
        } else if (!yyjson_is_null(target)) {
            ok = false;
        }
    }
    for (int e = 0; ok && e < edge_count; e++) {
        const cbm_gbuf_edge_t *edge = edges[e];
        if (!edge) {
            ok = false;
            break;
        }
        const cbm_gbuf_node_t *target = cbm_gbuf_find_by_id(gbuf, edge->target_id);
        yyjson_doc *edoc = edge->properties_json ? yyjson_read(edge->properties_json,
                                                               strlen(edge->properties_json), 0)
                                                 : NULL;
        yyjson_val *obj = edoc ? yyjson_doc_get_root(edoc) : NULL;
        yyjson_val *local = yyjson_obj_get(obj, "local_name");
        yyjson_val *bindings = yyjson_obj_get(obj, "php_import_bindings");
        ok = target && target->qualified_name && yyjson_is_obj(obj) && yyjson_obj_size(obj) == 2 &&
             yyjson_is_str(local) && yyjson_is_arr(bindings) && yyjson_arr_size(bindings) > 0;
        for (size_t b = 0; ok && b < yyjson_arr_size(bindings); b++) {
            yyjson_val *binding = yyjson_arr_get(bindings, b);
            int match = -1;
            for (int i = 0; i < count; i++) {
                if (targets[i] && strcmp(targets[i], target->qualified_name) == 0 &&
                    php_binding_identity(binding, &result->imports.items[i]) &&
                    php_json_string_eq(local, result->imports.items[i].local_name) &&
                    php_json_string_eq(yyjson_obj_get(binding, "target"), targets[i])) {
                    if (match != -1) {
                        ok = false;
                        break;
                    }
                    match = i;
                }
            }
            if (match < 0 || ++seen[match] != 1)
                ok = false;
        }
        yyjson_doc_free(edoc);
    }
    for (int i = 0; ok && i < count; i++)
        ok = seen[i] == (targets[i] ? 1 : 0);
done:
    if (ok) {
        out->imports = &result->imports;
        out->targets = targets;
        targets = NULL;
    }
    cbm_free(CBM_MEM_CLASS_OTHER, targets);
    cbm_free(CBM_MEM_CLASS_OTHER, seen);
    yyjson_doc_free(doc);
    return ok;
}

/* Shared by the sequential and parallel PHP IMPORTS writers. Other languages
 * retain their original writer and property layout. */
int cbm_pipeline_php_create_import_edges(cbm_pipeline_ctx_t *ctx, const CBMFileResult *result,
                                         const char *rel, const char *file_qn,
                                         const cbm_gbuf_node_t *file, CBMHashTable *namespace_map) {
    char *old_json = file->properties_json;
    if (old_json && strncmp(old_json, php_import_complete, sizeof(php_import_complete) - 1) == 0)
        old_json[sizeof(php_import_complete) - 3] = '0';

    int count = result->imports.count;
    if (count < 0 || (count > 0 && !result->imports.items))
        return 0;
    size_t slots = count > 0 ? (size_t)count : 1;
    if (slots > SIZE_MAX / sizeof(const cbm_gbuf_node_t *))
        return 0;
    const cbm_gbuf_node_t **targets = cbm_calloc(CBM_MEM_CLASS_OTHER, slots * sizeof(*targets));
    yyjson_doc *old = old_json ? yyjson_read(old_json, strlen(old_json), 0) : NULL;
    yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
    yyjson_mut_val *root = doc ? yyjson_mut_obj(doc) : NULL;
    yyjson_mut_val *manifest = doc ? yyjson_mut_arr(doc) : NULL;
    bool ok = targets && root && manifest &&
              (!old_json || (old && yyjson_is_obj(yyjson_doc_get_root(old)))) &&
              yyjson_mut_obj_add_int(doc, root, "php_imports_complete", 1) &&
              yyjson_mut_obj_add_val(doc, root, "php_import_bindings", manifest);
    int written = 0;
    bool complete = true;
    if (!ok)
        goto done;
    yyjson_mut_doc_set_root(doc, root);
    if (old) {
        size_t idx, max;
        yyjson_val *key, *value;
        yyjson_obj_foreach(yyjson_doc_get_root(old), idx, max, key, value) {
            const char *name = yyjson_get_str(key);
            if (strcmp(name, "php_imports_complete") == 0 ||
                strcmp(name, "php_import_bindings") == 0)
                continue;
            yyjson_mut_val *copy = yyjson_val_mut_copy(doc, value);
            if (!copy || !yyjson_mut_obj_add_val(doc, root, name, copy)) {
                ok = false;
                goto done;
            }
        }
    }
    for (int i = 0; i < count; i++) {
        const CBMImport *imp = &result->imports.items[i];
        targets[i] = imp->module_path
                         ? cbm_pipeline_resolve_import_node(ctx, rel, file_qn, imp, namespace_map)
                         : NULL;
        if (targets[i] && targets[i]->id == file->id)
            targets[i] = NULL;
        if (!targets[i] && !php_import_known_absent(ctx->gbuf, rel, imp, namespace_map))
            complete = false;
        yyjson_mut_val *entry =
            php_binding_json(doc, imp, targets[i] ? targets[i]->qualified_name : NULL);
        if (!entry || !yyjson_mut_arr_add_val(manifest, entry)) {
            ok = false;
            goto done;
        }
    }
    for (int i = 0; ok && i < count; i++) {
        if (!targets[i])
            continue;
        const char *local = result->imports.items[i].local_name;
        if (!local || !local[0]) {
            ok = false;
            break;
        }
        bool prior = false;
        for (int j = 0; j < i; j++)
            if (targets[j] && targets[j]->id == targets[i]->id &&
                result->imports.items[j].local_name &&
                strcmp(local, result->imports.items[j].local_name) == 0)
                prior = true;
        if (prior)
            continue;
        yyjson_mut_val *edge = yyjson_mut_obj(doc);
        yyjson_mut_val *bindings = yyjson_mut_arr(doc);
        ok = edge && bindings && yyjson_mut_obj_add_strcpy(doc, edge, "local_name", local) &&
             yyjson_mut_obj_add_val(doc, edge, "php_import_bindings", bindings);
        for (int j = i; ok && j < count; j++) {
            if (!targets[j] || targets[j]->id != targets[i]->id ||
                !result->imports.items[j].local_name ||
                strcmp(local, result->imports.items[j].local_name) != 0)
                continue;
            yyjson_mut_val *entry =
                php_binding_json(doc, &result->imports.items[j], targets[j]->qualified_name);
            ok = entry && yyjson_mut_arr_add_val(bindings, entry);
        }
        char *props = ok ? yyjson_mut_val_write(edge, 0, NULL) : NULL;
        ok = props &&
             cbm_gbuf_insert_edge(ctx->gbuf, file->id, targets[i]->id, "IMPORTS", props) > 0;
        free(props);
        if (ok)
            written++;
    }
    if (ok && complete) {
        char *props = yyjson_mut_write(doc, 0, NULL);
        cbm_php_vendor_names_t check = {0};
        if (props && php_read_binding_snapshot(ctx->gbuf, file, result, props, &check)) {
            /* Failure leaves the earlier completion bit disabled. */
            (void)cbm_gbuf_node_set_properties_json((cbm_gbuf_node_t *)file, props);
        }
        cbm_pipeline_php_vendor_names_free(&check);
        free(props);
    }
done:
    yyjson_doc_free(old);
    yyjson_mut_doc_free(doc);
    cbm_free(CBM_MEM_CLASS_OTHER, targets);
    return written;
}

void cbm_pipeline_php_vendor_names_build(const cbm_gbuf_t *gbuf, const char *project_name,
                                         const char *rel, const CBMFileResult *result,
                                         cbm_php_vendor_names_t *out) {
    memset(out, 0, sizeof(*out));
    if (!gbuf || !result || !rel || cbm_language_for_filename(path_leaf(rel)) != CBM_LANG_PHP)
        return;
    char *qn = cbm_pipeline_fqn_compute(project_name, rel, "__file__");
    const cbm_gbuf_node_t *file = qn ? cbm_gbuf_find_by_qn(gbuf, qn) : NULL;
    free(qn);
    if (file)
        (void)php_read_binding_snapshot(gbuf, file, result, file->properties_json, out);
}

void cbm_pipeline_php_vendor_names_free(cbm_php_vendor_names_t *value) {
    if (value) {
        cbm_free(CBM_MEM_CLASS_OTHER, value->targets);
        memset(value, 0, sizeof(*value));
    }
}

static bool php_vendor_kind(const cbm_php_vendor_names_t *value, const char *name, int kind) {
    if (!value || !value->targets || !value->imports || !name || name[0] == '\\')
        return false;
    size_t length = 0;
    while (php_ident_byte((unsigned char)name[length]))
        length++;
    if (length == 0)
        return false;
    for (int i = 0; i < value->imports->count; i++) {
        const CBMImport *imp = &value->imports->items[i];
        if (!imp->local_name || !imp->module_path || value->targets[i] ||
            (kind >= 0 && (int)imp->kind != kind))
            continue;
        if (strlen(imp->local_name) == length && strncmp(imp->local_name, name, length) == 0)
            return true;
    }
    return false;
}

bool cbm_pipeline_php_vendor_bound(const cbm_php_vendor_names_t *value, const char *name) {
    return php_vendor_kind(value, name, CBM_IMPORT_KIND_DEFAULT);
}

/* Existing occurrence metadata can identify a constructor or a type without
 * adding serialized fields. If its tree/source was not retained, -1 preserves
 * uncertainty: only an unresolved matching import can veto a guessed edge. */
static int php_import_kind_at_site(const CBMFileResult *result, uint32_t start, uint32_t end,
                                   CBMSourceOrigin origin, bool call) {
    if (!result || origin != CBM_SOURCE_ORIGIN_RAW || end <= start)
        return -1;
    if (result->cached_tree) {
        TSNode node = ts_node_descendant_for_byte_range(ts_tree_root_node(result->cached_tree),
                                                        start, end - 1);
        for (int depth = 0; !ts_node_is_null(node) && depth < 16; depth++) {
            const char *type = ts_node_type(node);
            if (strcmp(type, "named_type") == 0 || strcmp(type, "base_clause") == 0 ||
                strcmp(type, "class_interface_clause") == 0)
                return CBM_IMPORT_KIND_DEFAULT;
            if (strcmp(type, "object_creation_expression") == 0 ||
                strcmp(type, "scoped_call_expression") == 0 ||
                strcmp(type, "class_constant_access_expression") == 0) {
                TSNode scope = ts_node_named_child(node, 0);
                if (call || (!ts_node_is_null(scope) && ts_node_start_byte(scope) <= start &&
                             ts_node_end_byte(scope) >= end))
                    return CBM_IMPORT_KIND_DEFAULT;
                break;
            }
            if (strcmp(type, "function_call_expression") == 0) {
                TSNode function = ts_node_child_by_field_name(node, "function", 8);
                if (call || (!ts_node_is_null(function) && ts_node_start_byte(function) <= start &&
                             ts_node_end_byte(function) >= end))
                    return CBM_IMPORT_KIND_FUNCTION;
                break;
            }
            if (strcmp(type, "namespace_use_declaration") == 0 ||
                strcmp(type, "method_declaration") == 0 || strcmp(type, "function_definition") == 0)
                break;
            node = ts_node_parent(node);
        }
    }
    if (call && result->source && end <= (uint32_t)result->source_len && end - start > 3 &&
        memcmp(result->source + start, "new", 3) == 0 &&
        isspace((unsigned char)result->source[start + 3]))
        return CBM_IMPORT_KIND_DEFAULT;
    return -1;
}

bool cbm_pipeline_php_vendor_call(const cbm_php_vendor_names_t *value, const CBMFileResult *result,
                                  const CBMCall *call) {
    if (!call || !call->callee_name)
        return false;
    int kind = strstr(call->callee_name, "::")
                   ? CBM_IMPORT_KIND_DEFAULT
                   : php_import_kind_at_site(result, call->site_start_byte, call->site_end_byte,
                                             call->source_origin, true);
    return php_vendor_kind(value, call->callee_name, kind);
}

bool cbm_pipeline_php_vendor_usage(const cbm_php_vendor_names_t *value, const CBMFileResult *result,
                                   const CBMUsage *usage) {
    if (!usage)
        return false;
    int kind = php_import_kind_at_site(result, usage->site_start_byte, usage->site_end_byte,
                                       usage->source_origin, false);
    return php_vendor_kind(value, usage->ref_name, kind);
}

/* ── Namespace map ───────────────────────────────────────────────── */

/* The namespace names themselves, so a caller that has parked some results on
 * disk can still contribute their namespaces (see
 * cbm_result_spill_namespace). A file missing from this map does not fail to
 * resolve -- it resolves DIFFERENTLY, through the looser fallback, which is why
 * an incomplete map changed edge counts in both directions rather than only
 * losing edges. */
CBMHashTable *cbm_pipeline_namespace_map_build_names(const char *project_name,
                                                     const char *const *namespaces,
                                                     const char *const *rels, int count) {
    /* NULL means no namespace information (e.g. the CALLS import map), while
     * an empty map means no project file declares a namespace. A partial map
     * cannot prove a PHP import absent, so every construction failure returns
     * NULL after releasing the accumulated entries. */
    if (count < 0 || (count > 0 && (!namespaces || !rels)))
        return NULL;
    CBMHashTable *map = cbm_ht_create(CBM_SZ_64);
    if (!map) {
        return NULL;
    }
    for (int i = 0; i < count; i++) {
        const char *namespace_name = namespaces[i];
        if (!namespace_name || !namespace_name[0]) {
            continue;
        }
        char *file_qn = NULL;
        char *key = NULL;
        bool ok = false;
        if (!rels[i])
            goto item_done;
        file_qn = cbm_pipeline_fqn_compute(project_name, rels[i], "__file__");
        if (!file_qn) {
            goto item_done;
        }
        /* Normalize the namespace key to dot-separated form so it matches the
         * dot-normalized lookups in cbm_pipeline_resolve_import_node (PHP uses
         * '\\', some grammars '::' or '/'). */
        key = cbm_mem_strdup(CBM_MEM_CLASS_OTHER, namespace_name);
        if (!key) {
            goto item_done;
        }
        for (char *p = key; *p; p++) {
            if (*p == '\\' || *p == ':' || *p == '/') {
                *p = '.';
            }
        }
        /* Store ALL files declaring a namespace as a '\n'-delimited list so the
         * resolver can pick a non-importer sibling (see resolve loop). The hash
         * table does not copy keys. The map owns memory-core keys and libc
         * values from fqn_compute or the combined allocation below. */
        if (!cbm_ht_has(map, key)) {
            cbm_ht_set(map, key, file_qn); /* map owns key + file_qn */
            /* set returns NULL for both insertion and allocation failure.
             * These lookups allocate nothing and verify ownership transfer. */
            const char *stored_key = cbm_ht_get_key(map, key);
            void *stored_value = cbm_ht_get(map, key);
            ok = stored_key == key && stored_value == file_qn;
            if (stored_key == key)
                key = NULL;
            if (stored_value == file_qn)
                file_qn = NULL;
        } else {
            /* Append to the existing list. Re-key with the STORED key pointer
             * (not our fresh copy) so the map's key pointer never changes —
             * otherwise Verstable would adopt the new key and our cleanup
             * below would free the live key (use-after-free). */
            const char *stored_key = cbm_ht_get_key(map, key);
            const char *cur = (const char *)cbm_ht_get(map, key);
            char *combined = NULL;
            if (stored_key && cur) {
                size_t cur_len = strlen(cur), file_len = strlen(file_qn);
                if (file_len > SIZE_MAX - 2 || cur_len > SIZE_MAX - file_len - 2) {
                    goto item_done;
                }
                size_t need = cur_len + 1 + file_len + 1;
                combined = malloc(need);
                if (combined) {
                    snprintf(combined, need, "%s\n%s", cur, file_qn);
                    (void)cbm_ht_set(map, stored_key, combined);
                    if (cbm_ht_get(map, stored_key) != combined) {
                        free(combined);
                        combined = NULL;
                    } else {
                        free((void *)cur); /* replaced value string */
                    }
                }
            }
            ok = combined != NULL;
        }
    item_done:
        cbm_free(CBM_MEM_CLASS_OTHER, key);
        free(file_qn);
        if (!ok) {
            cbm_pipeline_namespace_map_free(map);
            return NULL;
        }
    }
    return map;
}

/* Convenience for callers whose results are all in memory (the sequential
 * definitions pass). A caller that can SPILL must use the _names variant and
 * fill the parked slots from cbm_result_spill_namespace, or its map silently
 * loses those files. */
CBMHashTable *cbm_pipeline_namespace_map_build(const char *project_name,
                                               CBMFileResult *const *results,
                                               const char *const *rels, int count) {
    if (count < 0 || (count > 0 && (!results || !rels)) ||
        (size_t)count > SIZE_MAX / sizeof(char *))
        return NULL;
    if (count == 0)
        return cbm_pipeline_namespace_map_build_names(project_name, NULL, rels, 0);
    const char **names = cbm_calloc(CBM_MEM_CLASS_OTHER, (size_t)count * sizeof(char *));
    if (!names) {
        return NULL;
    }
    for (int i = 0; i < count; i++) {
        names[i] = results[i] ? results[i]->namespace_name : NULL;
    }
    CBMHashTable *map = cbm_pipeline_namespace_map_build_names(project_name, names, rels, count);
    cbm_free(CBM_MEM_CLASS_OTHER, names);
    return map;
}

static void ns_map_free_entry(const char *key, void *value, void *ud) {
    (void)ud;
    cbm_free(CBM_MEM_CLASS_OTHER, (void *)key);
    free(value);
}

void cbm_pipeline_namespace_map_free(CBMHashTable *map) {
    if (!map) {
        return;
    }
    cbm_ht_foreach(map, ns_map_free_entry, NULL);
    cbm_ht_free(map);
}