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(python): docstrings and __future__ imports are no namespace barriers

Martin Vogel240b24ae822c
diff --git a/internal/cbm/cbm.h b/internal/cbm/cbm.h
index 86586dd15..4a72ce36c 100644
--- a/internal/cbm/cbm.h
+++ b/internal/cbm/cbm.h
@@ -401,8 +401,12 @@ typedef struct {
CBMImportKind kind; // CBM_IMPORT_KIND_DEFAULT unless the syntax names a member kind
} CBMImport;
-/* Content-only ordered Python namespace facts; no resolved target identities. */
-#define CBM_PY_NAMESPACE_FACTS_VERSION 1u
+/* Content-only ordered Python namespace facts; no resolved target identities.
+ * The version travels in the lsp_surface "py" payload, and a stored payload of
+ * another version does not decode: an incremental run then re-extracts in full,
+ * so stored facts of an older extraction never mix with fresh ones.
+ * 2: string-literal statements are no effect; `from __future__` imports bind. */
+#define CBM_PY_NAMESPACE_FACTS_VERSION 2u
typedef enum {
CBM_PY_NS_NOT_CAPTURED = 0,
diff --git a/internal/cbm/extract_imports.c b/internal/cbm/extract_imports.c
index abcc583f7..596bd5f60 100644
--- a/internal/cbm/extract_imports.c
+++ b/internal/cbm/extract_imports.c
@@ -484,6 +484,37 @@ static bool py_ns_plain_string(PyNamespaceBuilder *b, TSNode node, const char **
return true;
}
+/* One string of a literal: any quoting or prefix (r, b, u, rb), unless it is an
+ * f-string with a replacement field, whose __format__ / __str__ may run code. */
+static bool py_ns_string_without_field(TSNode node) {
+ if (strcmp(ts_node_type(node), "string") != 0)
+ return false;
+ uint32_t count = ts_node_named_child_count(node);
+ for (uint32_t i = 0; i < count; i++) {
+ if (strcmp(ts_node_type(ts_node_named_child(node, i)), "interpolation") == 0)
+ return false;
+ }
+ return true;
+}
+
+/* A string literal, implicit concatenations included, evaluates nothing: a
+ * docstring (module, class or attribute) is no namespace effect. */
+static bool py_ns_literal_string(TSNode node) {
+ if (strcmp(ts_node_type(node), "concatenated_string") != 0)
+ return py_ns_string_without_field(node);
+ uint32_t count = ts_node_named_child_count(node);
+ bool parts = false;
+ for (uint32_t i = 0; i < count; i++) {
+ TSNode part = ts_node_named_child(node, i);
+ if (strcmp(ts_node_type(part), "comment") == 0)
+ continue;
+ if (!py_ns_string_without_field(part))
+ return false;
+ parts = true;
+ }
+ return parts;
+}
+
/* Bounded syntactic proof only. Unsupported or deep expressions become an
* unknown-effect barrier; no evaluator or source execution is involved. */
static bool py_ns_safe_expr(PyNamespaceBuilder *b, TSNode node, int depth) {
@@ -496,11 +527,8 @@ static bool py_ns_safe_expr(PyNamespaceBuilder *b, TSNode node, int depth) {
strcmp(kind, "float") == 0 || strcmp(kind, "true") == 0 || strcmp(kind, "false") == 0 ||
strcmp(kind, "none") == 0 || strcmp(kind, "comment") == 0)
return true;
- if (strcmp(kind, "string") == 0) {
- const char *text = NULL;
- size_t len = 0;
- return py_ns_plain_string(b, node, &text, &len);
- }
+ if (strcmp(kind, "string") == 0 || strcmp(kind, "concatenated_string") == 0)
+ return py_ns_literal_string(node);
bool container =
strcmp(kind, "tuple") == 0 || strcmp(kind, "list") == 0 ||
strcmp(kind, "parenthesized_expression") == 0 || strcmp(kind, "parameters") == 0 ||
@@ -549,8 +577,7 @@ static bool py_ns_class_safe(PyNamespaceBuilder *b, TSNode node) {
continue;
if (strcmp(kind, "expression_statement") == 0 &&
ts_node_named_child_count(child) == 1) {
- TSNode expr = ts_node_named_child(child, 0);
- if (strcmp(ts_node_type(expr), "string") == 0 && py_ns_safe_expr(b, expr, 0))
+ if (py_ns_literal_string(ts_node_named_child(child, 0)))
continue;
/* Even an identifier assignment can install a descriptor whose
* __set_name__ hook executes during class creation. */
@@ -573,6 +600,8 @@ static bool py_ns_import_fact(PyNamespaceBuilder *b, TSNode child, bool from,
.module_name = module_name,
.relative_level = level};
if (from && strcmp(kind, "wildcard_import") == 0) {
+ if (level == 0 && module_name && strcmp(module_name, "__future__") == 0)
+ return false; /* a syntax error in Python: stays unsupported */
f.kind = CBM_PY_NS_IMPORT_STAR;
*out = f;
return true;
@@ -840,6 +869,35 @@ static bool py_ns_type_checking_block(PyNamespaceBuilder *b, TSNode node) {
return !b->failure;
}
+/* `from __future__ import x [as y]` is its own node type, without a module
+ * field: a compiler directive that also binds x (or y) to the feature object,
+ * like a from-import of module `__future__`. */
+static bool py_ns_future_import(PyNamespaceBuilder *b, TSNode node) {
+ const char *module_name = py_ns_copy(b, "__future__", strlen("__future__"));
+ if (!module_name)
+ return false;
+ TSTreeCursor cursor = ts_tree_cursor_new(node);
+ bool ok = true;
+ int emitted = 0;
+ if (ts_tree_cursor_goto_first_child(&cursor)) {
+ do {
+ const char *field = ts_tree_cursor_current_field_name(&cursor);
+ if (!field || strcmp(field, "name") != 0)
+ continue;
+ CBMPyNamespaceFact f;
+ if (!py_ns_import_fact(b, ts_tree_cursor_current_node(&cursor), true, module_name, 0,
+ &f) ||
+ !py_ns_push(b, f)) {
+ ok = false;
+ break;
+ }
+ emitted++;
+ } while (ts_tree_cursor_goto_next_sibling(&cursor));
+ }
+ ts_tree_cursor_delete(&cursor);
+ return ok && emitted > 0;
+}
+
static bool py_ns_statement(PyNamespaceBuilder *b, TSNode node) {
const char *kind = ts_node_type(node);
if (strcmp(kind, "comment") == 0 || strcmp(kind, "pass_statement") == 0)
@@ -848,6 +906,8 @@ static bool py_ns_statement(PyNamespaceBuilder *b, TSNode node) {
return py_ns_import(b, node, false);
if (strcmp(kind, "import_from_statement") == 0)
return py_ns_import(b, node, true);
+ if (strcmp(kind, "future_import_statement") == 0)
+ return py_ns_future_import(b, node);
bool decorated = strcmp(kind, "decorated_definition") == 0;
TSNode def = decorated ? ts_node_child_by_field_name(node, TS_FIELD("definition")) : node;
if (!ts_node_is_null(def)) {
diff --git a/tests/test_pipeline.c b/tests/test_pipeline.c
index 3548e867b..00787339d 100644
--- a/tests/test_pipeline.c
+++ b/tests/test_pipeline.c
@@ -22988,26 +22988,32 @@ TEST(pipeline_python_namespace_codec_owns_ordered_facts) {
}
TEST(pipeline_python_namespace_codec_rejects_non_authoritative_rows) {
- /* Numeric values below are the frozen version-1 namespace wire values.
- * Even an empty LSP array must validate its namespace envelope. */
+ /* Numeric values below are the frozen namespace wire values (version 2
+ * changed which statements extraction proves harmless, not the wire
+ * shape). Even an empty LSP array must validate its namespace envelope,
+ * and a payload of an older facts version is no authority: its facts
+ * were extracted under other rules, so the incremental run that reads
+ * it re-extracts in full. */
const char *bad[] = {
"{\"v\":1,\"lsp\":[]}",
"{\"v\":2,\"lang\":1,\"lsp\":[]}",
"{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":null}",
"{\"v\":2,\"lang\":1.0,\"lsp\":[],\"py\":null}",
"{\"v\":2,\"v\":2,\"lang\":0,\"lsp\":[],\"py\":null}",
- "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":1,\"lang\":1,"
+ "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":2,\"lang\":1,"
"\"module\":\"p.m\",\"path\":\"m.py\",\"status\":3,\"failure\":2,\"events\":[]}}",
+ "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":1,\"lang\":1,"
+ "\"module\":\"p.m\",\"path\":\"m.py\",\"status\":2,\"failure\":0,\"events\":[]}}",
"{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":99,\"lang\":1,"
"\"module\":\"p.m\",\"path\":\"m.py\",\"status\":2,\"failure\":0,\"events\":[]}}",
- "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":1,\"lang\":1,"
+ "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":2,\"lang\":1,"
"\"module\":\"p.m\",\"path\":\"m.py\\u0000suffix\",\"status\":2,"
"\"failure\":0,\"events\":[]}}",
- "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":1,\"lang\":1,"
+ "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":2,\"lang\":1,"
"\"module\":\"p.m\",\"path\":\"m.py\",\"status\":2,\"failure\":0,\"events\":["
"{\"k\":999,\"d\":0,\"s\":0,\"r\":0,\"f\":0,\"l\":0,"
"\"n\":null,\"m\":null,\"i\":null,\"a\":[]}]}}",
- "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":1,\"lang\":1,"
+ "{\"v\":2,\"lang\":1,\"lsp\":[],\"py\":{\"v\":2,\"lang\":1,"
"\"module\":\"p.m\",\"path\":\"m.py\",\"status\":2,\"failure\":0,\"events\":["
"{\"k\":8,\"d\":0,\"s\":1,\"r\":0,\"f\":0,\"l\":4294967296,"
"\"n\":null,\"m\":null,\"i\":null,\"a\":[]}]}}",
@@ -23027,7 +23033,7 @@ TEST(pipeline_python_namespace_codec_rejects_non_authoritative_rows) {
cbm_arena_destroy(&arena);
}
const char *unknown =
- "{\"v\":2,\"lang\":1,\"lsp\":[],\"reg\":[],\"py\":{\"v\":1,\"lang\":1,"
+ "{\"v\":2,\"lang\":1,\"lsp\":[],\"reg\":[],\"py\":{\"v\":2,\"lang\":1,"
"\"module\":\"p.m\",\"path\":\"m.py\",\"status\":2,\"failure\":0,\"events\":["
"{\"k\":7,\"d\":0,\"s\":0,\"r\":7,\"f\":0,\"l\":0,"
"\"n\":null,\"m\":null,\"i\":null,\"a\":[]}]}}";
@@ -23040,6 +23046,7 @@ TEST(pipeline_python_namespace_codec_rejects_non_authoritative_rows) {
facts.facts.items[0].kind == CBM_PY_NS_UNKNOWN &&
facts.facts.items[0].reason == CBM_PY_NS_REASON_PARSE;
cbm_arena_destroy(&arena);
+ ASSERT_EQ(CBM_PY_NAMESPACE_FACTS_VERSION, 2u); /* the rows above spell it */
ASSERT_TRUE(rejected);
ASSERT_EQ(unknown_rc, 1);
ASSERT_EQ(equal_rc, 0);