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.

fix(elixir): stop walking @spec and @type subtrees as code

Chad4d21c3bbd34b
diff --git a/internal/cbm/extract_defs.c b/internal/cbm/extract_defs.c
index 839e482de..2faf10856 100644
--- a/internal/cbm/extract_defs.c
+++ b/internal/cbm/extract_defs.c
@@ -5477,9 +5477,18 @@ static TSNode elixir_call_args(TSNode node) {
// responsible are the typespec heads the widened span now covers -- `@spec
// f(t) :: u` puts the declared name in a `call` node, and the unified walk
// reads it as code -- a separate defect with a separate fix, not something this
-// fold can close. What the fold and the head suppression together remove is
-// 2,436 edges, none of them added back: see elixir_call_is_definition_role in
-// extract_calls.c.
+// fold can close.
+//
+// Skipping the typespec subtrees, later in this stack, closes that half: the
+// same method then reports 389 self_recursive Function nodes and 8 with no
+// self-call form, against 129 and 6 on the base. All 8 are the pre-existing
+// phantom a local variable sharing the function's name mints (`defp slug(value)
+// do slug = ...`), 6 of them already present on the base; the other 2 are
+// guarded clauses that only have a node of their own to be flagged on because
+// of this stack.
+//
+// What the fold and the head suppression together remove is 2,436 edges, none
+// of them added back: see elixir_call_is_definition_role in extract_calls.c.
//
// A clause whose macro differs (`def` foo/1 beside `defp` foo/2) still folds,
// because the arity-free QN already puts both on one node; is_exported is then
diff --git a/internal/cbm/extract_unified.c b/internal/cbm/extract_unified.c
index 68e0fbdcc..9467d82e6 100644
--- a/internal/cbm/extract_unified.c
+++ b/internal/cbm/extract_unified.c
@@ -2041,6 +2041,111 @@ static bool is_unified_trivia_node(TSNode node) {
return ts_node_is_extra(node);
}
+static bool unified_node_text_equals(const CBMExtractCtx *ctx, TSNode node, const char *expected) {
+ if (ts_node_is_null(node) || !ctx->source || !expected) {
+ return false;
+ }
+ uint32_t start = ts_node_start_byte(node);
+ uint32_t end = ts_node_end_byte(node);
+ size_t len = strlen(expected);
+ return end >= start && (size_t)(end - start) == len &&
+ memcmp(ctx->source + start, expected, len) == 0;
+}
+
+/* An Elixir module attribute parses as `unary_operator(@, call(<attr>, args))`,
+ * so the typespec family reaches the unified walk in the shape real code has:
+ * `@spec foo(t) :: t` puts `foo(t)` in the same `call` node an invocation would
+ * occupy, and `@type entry :: String.t()` does the same to a type name. The
+ * walk then reads a declaration as code and mints reference edges from it.
+ *
+ * Measured on a fixture of three typespec lines (`@type state :: map()`, `@spec
+ * fetch(opts) :: state`, `@spec load(User.t()) :: :ok`) beside `def state`,
+ * `def opts` and a remote `MyApp.User.t/0`: seven edges, every one phantom and
+ * every one landing on a Function. CALLS onto each specified function;
+ * CALLS + USAGE + WRITES onto `state`, the WRITES asserting a mutation that
+ * does not exist; and USAGE onto `opts` and onto `MyApp.User.t/0`, because a
+ * bare or remote TYPE name resolves to the same-named FUNCTION. On a codebase
+ * whose convention is @spec on every public function, fan_in therefore never
+ * reaches 0 and "which exported functions nothing calls" is unanswerable.
+ *
+ * The whole subtree is skipped, not just the specified name. What that costs is
+ * not uniform across the six heads, and both halves were measured by indexing
+ * one fixture repo -- a declaring file per head plus the file each one reaches
+ * -- with the pristine binary and with this one:
+ *
+ * spec, type, typep, opaque. A type reference resolves onto a FUNCTION or
+ * onto nothing, never onto the type it names, because a type declaration
+ * mints no node. `@spec build(MyApp.User.t())` where that module's `t` is a
+ * `@type` produced no edge in either build, and `@type ext :: Ecto.Schema.t()`
+ * naming a module outside the repo produced none either. The references that
+ * do resolve land on a same-named Function, cross-file included -- `USAGE
+ * lib/decl_type.ex -> Function type_target @lib/remote_type.ex`, and the
+ * @typep and @opaque equivalents. A Function standing in for a Type is the
+ * pollution rather than a record of it, so nothing correct is lost here.
+ *
+ * callback, macrocallback. The declared name IS a function name, so it
+ * resolves onto an implementation elsewhere in the corpus: pristine yields
+ * `CALLS lib/decl_callback.ex -> Function callback_fun @lib/impl_callback.ex`
+ * and the @macrocallback equivalent, both cross-file, and this build yields
+ * neither. That edge does point at a real Behaviour-to-Impl relationship, and
+ * nothing replaces it -- `@behaviour MyBehaviour` mints no edge of its own,
+ * so after this change nothing in the graph links a behaviour to its
+ * implementations. It is deleted anyway because it is name resolution and not
+ * a behaviour model: on a fixture with one @callback and three same-named
+ * `handle_it/1` defs, the single edge landed on the one module that
+ * implements nothing, leaving both real implementors at fan_in 0. Recording
+ * that relationship correctly means minting it from `@behaviour`, which is a
+ * separate change and not a reason to keep an arbitrary edge.
+ *
+ * The other accepted cost: `unquote(...)` inside a typespec does execute at
+ * compile time, so `@type t :: unquote(build_type())` loses its genuine
+ * `build_type` call edge along with the phantoms.
+ *
+ * Only this family is skipped. Every other attribute VALUE is ordinary
+ * compile-time code -- `@timeout Application.compile_env(:app, :timeout)`
+ * really does call compile_env -- so those subtrees are walked exactly as
+ * before, and their attribute NAME is still emitted as a callee: `@behaviour
+ * GenServer`, `@timeout 5_000` and `@doc "x"` each still mint one phantom CALLS
+ * onto a same-named Function. That half of the defect class is untouched here
+ * and needs its own fix.
+ *
+ * This subtree skip is one of two mechanisms, and neither subsumes the other.
+ * It removes the phantom a typespec LINE mints; the def-head phantom is removed
+ * separately, by the calls walk recognising a `when`-wrapped head as a
+ * declaration (elixir_call_is_definition_role, extract_calls.c). A function
+ * carrying both an @spec and a `when` clause needs both: with only this one it
+ * keeps the def-head reference, with only the other it keeps the @spec one.
+ * `extract_elixir_typespec_attribute_is_not_code` pins that by asserting 0
+ * references onto such a function, so removing either mechanism fails it.
+ *
+ * Measured over forge-symphony-graph/lib (970 .ex files) by classifying the
+ * source line every CALLS/USAGE/WRITES edge records: a build without this skip
+ * anchors 4,565 CALLS edges on a typespec-attribute line, and this build
+ * anchors 0 -- with no USAGE or WRITES appearing in their place, which is what
+ * a relabel rather than a removal would look like. Total USAGE edges fall from
+ * 25,393 to 23,044 over the same corpus; they do not rise. */
+static bool is_elixir_typespec_attribute(const CBMExtractCtx *ctx, TSNode node) {
+ static const char *const typespec_heads[] = {
+ "spec", "callback", "macrocallback", "type", "typep", "opaque", NULL};
+ if (ctx->language != CBM_LANG_ELIXIR || strcmp(ts_node_type(node), "unary_operator") != 0 ||
+ !unified_node_text_equals(ctx, ts_node_child_by_field_name(node, TS_FIELD("operator")),
+ "@")) {
+ return false;
+ }
+ TSNode operand = ts_node_child_by_field_name(node, TS_FIELD("operand"));
+ if (ts_node_is_null(operand) || strcmp(ts_node_type(operand), "call") != 0 ||
+ ts_node_child_count(operand) == 0) {
+ return false;
+ }
+ TSNode head = ts_node_child(operand, 0);
+ for (const char *const *name = typespec_heads; *name; name++) {
+ if (unified_node_text_equals(ctx, head, *name)) {
+ return true;
+ }
+ }
+ return false;
+}
+
// JS/TS `export_statement` appears in import_node_types so re-exports
// (`export { X } from './m'`) are treated as an import boundary. But it also
// wraps exported *declarations* (`export function f(cfg: Config) {}`), and
@@ -2631,7 +2736,8 @@ void cbm_extract_unified(CBMExtractCtx *ctx) {
break;
}
bool trivia = is_unified_trivia_node(node);
- if (!trivia) {
+ bool typespec = is_elixir_typespec_attribute(ctx, node);
+ if (!trivia && !typespec) {
/* Trivia consumes no semantic state. Scope expiry may be deferred
* until the next code-bearing node; pop restores the displaced
* tuple and push applies the new frame's effect, both O(1) --
@@ -2661,7 +2767,7 @@ void cbm_extract_unified(CBMExtractCtx *ctx) {
* asking the cursor to construct a child iterator for every one of
* hundreds of thousands of flat comment siblings. Structured extras
* still descend normally. */
- if ((!trivia || ts_node_child_count(node) > 0) &&
+ if (!typespec && (!trivia || ts_node_child_count(node) > 0) &&
ts_tree_cursor_goto_first_child(&cursor)) {
depth++;
continue;
diff --git a/tests/test_extraction.c b/tests/test_extraction.c
index 1adca8bce..3f6544853 100644
--- a/tests/test_extraction.c
+++ b/tests/test_extraction.c
@@ -1847,24 +1847,22 @@ static int elixir_any_ref_count(CBMFileResult *r, const char *name) {
}
/* The head suppression has to REMOVE the phantom, not relabel it. What makes
- * that hold for a def head is not the calls walk alone: is_elixir_def_binding
- * in extract_usages.c already treats everything inside a def's first argument
- * as a binding occurrence rather than a reference, so the identifier
- * handle_calls declines is declined by handle_usages too. That agreement is the
- * invariant under test, and it is why the counts below are over every extractor
- * rather than over r->calls.
+ * that hold for a def head is not the calls walk alone: is_elixir_def_binding in
+ * extract_usages.c already treats everything inside a def's first argument as
+ * a binding occurrence rather than a reference, so the identifier handle_calls
+ * declines is declined by handle_usages too. That agreement is the invariant
+ * under test, and it is why the counts below are over every extractor rather
+ * than over r->calls.
*
- * `spec_subject` pins the boundary of this patch, and pins it as a RELATION
- * rather than a count, because the count cannot see the defect. A typespec
- * subject is the same shape as a def head and is NOT suppressed here: nothing
- * in extract_usages.c treats it as a binding, so declining it in handle_calls
- * only relabels its phantom as a USAGE. At extraction that relabel is
- * invisible -- one reference before, one after -- and it becomes a defect
- * downstream, where CALLS and USAGE are separate rows under
- * UNIQUE(source,target,type) and the relabelled phantom stops colliding with
- * the real call it used to hide behind. So the assertion is that every
- * reference recorded for a typespec subject is a CALL and none has become a
- * usage, a read/write or a type reference. */
+ * `spec_subject` pins the boundary between the two mechanisms. A typespec
+ * subject is the same shape as a def head, and suppressing it in the calls walk
+ * would only relabel its phantom as a USAGE, because nothing treats it as a
+ * binding. It is removed instead by skipping the whole `@spec` subtree before
+ * any extractor sees it (is_elixir_typespec_attribute, extract_unified.c), so
+ * the assertion is both that no reference of any kind survives AND that what
+ * does survive is never a relabelling: the equality holds at 0 == 0 here, and
+ * would hold at 1 == 1 on a build with the subtree skip removed but the calls
+ * suppression left in place. */
TEST(extract_elixir_declaration_head_mints_no_reference_of_any_kind) {
CBMFileResult *r = extract("defmodule Heads do\n" /* 1 */
" def guarded(x) when is_integer(x), do: x\n" /* 2 */
@@ -1886,11 +1884,19 @@ TEST(extract_elixir_declaration_head_mints_no_reference_of_any_kind) {
/* The guard predicate is a real call and survives as one. */
ASSERT_EQ(1, count_calls_named(r, "is_integer"));
ASSERT_EQ(1, elixir_any_ref_count(r, "is_integer"));
- /* Declared, not suppressed here; see the comment above. Every reference
- * this file records for a typespec subject is a CALL -- none of them has
- * been relabelled into a usage, a read/write or a type reference. */
+ /* Neither the @spec line nor the def head it precedes leaves a reference,
+ * and nothing has been relabelled into a usage, a read/write or a type
+ * reference. */
+ ASSERT_EQ(0, count_calls_named(r, "spec_subject"));
ASSERT_EQ(count_calls_named(r, "spec_subject"),
elixir_any_ref_count(r, "spec_subject"));
+
+ ASSERT_EQ(1, count_defs_named(r, "Function", "guarded"));
+ const CBMDefinition *guarded = elixir_first_def(r, "guarded");
+ ASSERT_NOT_NULL(guarded);
+ ASSERT_EQ(2, (int)guarded->start_line);
+ ASSERT_EQ(3, (int)guarded->end_line);
+ ASSERT_FALSE(guarded->is_recursive);
cbm_free_result(r);
PASS();
}
@@ -1919,6 +1925,94 @@ TEST(extract_elixir_real_recursion_survives_head_suppression) {
PASS();
}
+/* An Elixir module attribute parses as `unary_operator(@, call(<attr>, args))`,
+ * so a typespec line reaches the unified walk as ordinary code and every symbol
+ * it names collects a phantom inbound edge from the enclosing Module -- a CALLS
+ * onto the specified function, and for `@type` a USAGE plus a WRITES asserting
+ * a mutation that does not exist. On a codebase whose convention is @spec on
+ * every public function, fan_in then never reaches 0 and "which exported
+ * functions nothing calls" is unanswerable.
+ *
+ * All six heads in the skip list are exercised, so deleting any one entry from
+ * typespec_heads[] breaks this test.
+ *
+ * Two of the groups below pin a decision rather than a repair, and both are
+ * argued in is_elixir_typespec_attribute's comment:
+ *
+ * type_refs[] -- a typespec's type references are not indexed at all. A type
+ * declaration mints no node, so such a reference resolves onto nothing or
+ * onto a same-named FUNCTION, which is the pollution rather than a record of
+ * it. Restoring any of them must break this test.
+ *
+ * behaviour_contract_names[] -- accepted cost. A @callback / @macrocallback
+ * name is a function name, so before this change it resolved cross-file onto
+ * the functions implementing the behaviour. Nothing replaces that edge.
+ *
+ * The attribute NAME phantom outside the typespec family is deliberately still
+ * there: `@timeout` keeps its one reference, and its VALUE is ordinary
+ * compile-time code that still runs. `guarded` is pinned at 0 rather than 1
+ * because the guarded def head no longer mints a phantom either -- the calls
+ * walk now recognises a `when`-wrapped head as a declaration. */
+TEST(extract_elixir_typespec_attribute_is_not_code) {
+ /* Names a typespec declares, plus the six attribute heads themselves.
+ * Every one carries a reference on the pristine build. */
+ static const char *const declared[] = {"with_spec", "entry", "secret", "handle",
+ "spec", "type", "typep", "opaque",
+ "callback", "macrocallback", NULL};
+ /* Accepted cost: these used to resolve onto the behaviour's implementors. */
+ static const char *const behaviour_contract_names[] = {"handle_it", "expand_it", NULL};
+ /* Pinned decision: type references are not indexed -- remote, bare-local
+ * and builtin alike. */
+ static const char *const type_refs[] = {"MyApp.User.t", "String.t", "MyApp.Vault.key",
+ "Macro.t", "t", "key",
+ "term", "integer", "reference",
+ "atom", NULL};
+ CBMFileResult *r = extract("defmodule Specced do\n"
+ " @timeout Application.compile_env(:app, :timeout)\n"
+ " @type entry :: String.t()\n"
+ " @typep secret :: MyApp.Vault.key()\n"
+ " @opaque handle :: reference()\n"
+ " @callback handle_it(term) :: :ok\n"
+ " @macrocallback expand_it(term) :: Macro.t()\n"
+ " @spec with_spec(MyApp.User.t()) :: integer\n"
+ " def with_spec(n), do: n\n"
+ " def without_spec(n), do: n\n"
+ " @spec guarded(atom) :: :ok\n"
+ " def guarded(x) when is_atom(x), do: :ok\n"
+ "end\n",
+ CBM_LANG_ELIXIR, "t", "specced.ex");
+ ASSERT_NOT_NULL(r);
+ ASSERT_FALSE(r->has_error);
+ /* The definitions themselves are a separate pass and are unaffected. */
+ ASSERT(has_def(r, "Function", "with_spec"));
+ ASSERT(has_def(r, "Function", "without_spec"));
+ ASSERT(has_def(r, "Function", "guarded"));
+ /* Control on the instrument, not a pin: `without_spec` carries no typespec
+ * and is never called, so it reads 0 on the pristine build too. It is here
+ * to show elixir_any_ref_count does not score a definition as a reference,
+ * which is what would make every 0 below vacuous. It cannot fail first and
+ * cannot catch a regression. */
+ ASSERT_EQ(0, elixir_any_ref_count(r, "without_spec"));
+ for (const char *const *name = declared; *name; name++) {
+ ASSERT_EQ(0, elixir_any_ref_count(r, *name));
+ }
+ for (const char *const *name = behaviour_contract_names; *name; name++) {
+ ASSERT_EQ(0, elixir_any_ref_count(r, *name));
+ }
+ for (const char *const *name = type_refs; *name; name++) {
+ ASSERT_EQ(0, elixir_any_ref_count(r, *name));
+ }
+ /* A non-typespec attribute is untouched: its value really is compile-time
+ * code, and its name still mints the one phantom this fix does not close. */
+ ASSERT_EQ(1, count_calls_named(r, "Application.compile_env"));
+ ASSERT_EQ(1, elixir_any_ref_count(r, "timeout"));
+ /* Both phantoms onto `guarded` are gone: the @spec one to the subtree skip,
+ * the def-head one to the calls walk recognising a guarded head. */
+ ASSERT_EQ(0, elixir_any_ref_count(r, "guarded"));
+ cbm_free_result(r);
+ PASS();
+}
+
/* tree-sitter-elixir gives a call's arguments node no field name, so the
* generic `arguments` field lookup returns null and first_string_arg was never
* populated for any Elixir call — Phoenix route paths, service URLs and config
@@ -9168,6 +9262,7 @@ SUITE(extraction) {
RUN_TEST(extract_elixir_guarded_clause_head_is_not_a_self_call);
RUN_TEST(extract_elixir_declaration_head_mints_no_reference_of_any_kind);
RUN_TEST(extract_elixir_real_recursion_survives_head_suppression);
+ RUN_TEST(extract_elixir_typespec_attribute_is_not_code);
RUN_TEST(elixir_call_string_argument);
RUN_TEST(extract_elixir_guarded_def_head_scope);
RUN_TEST(extract_elixir_guarded_def_head_guard_usages);