Merge pull request #5 from ak4code/claude/hopeful-curie-8ax1e4

Support Django string references and test-only code detection

Author: ak4code

README.md

@@ -55,9 +55,13 @@ dc --kind function,method   # только функции и методы
 файл `.dc.toml` в корне проекта, секция `[tool.dc]` в `pyproject.toml`.
 Незнакомые ключи считаются ошибкой — опечатка не отключит настройку молча.
 
-По умолчанию из анализа исключаются `.venv` (включая окружения `uv`),
-`migrations`, `tests` и скрытые директории; правила `.gitignore`
-учитываются автоматически.
+По умолчанию из анализа полностью исключаются `.venv` (включая окружения
+`uv`), `migrations` и скрытые директории; правила `.gitignore` учитываются
+автоматически. Тестовые файлы (пакет `tests`, а также `test_*.py`,
+`*_test.py`, `tests.py`, `conftest.py`) не исключаются, а
+анализируются только как источник ссылок: код, используемый исключительно
+в тестах, не считается мертвым, но сами тесты в отчет не попадают. Чтобы
+исключить тесты полностью, добавьте `tests` в `exclude_directories`.
 
 ```toml
 # .dc.toml (или те же ключи в [tool.dc] файла pyproject.toml)
@@ -92,6 +96,16 @@ extra_framework_base_markers = ["Repository", "Actor"]
 - **Строковые ссылки** — строки из `getattr`, `setattr`, `hasattr`,
   `delattr` и `importlib.import_module` образуют пул динамических ссылок;
   совпадающие по имени сущности считаются используемыми.
+- **Точечные строковые пути** — любая строка вида `app.views.handler`
+  (не менее двух сегментов, каждый — корректный идентификатор Python)
+  считается ссылкой на код и добавляется в пул динамических ссылок. Это
+  покрывает повсеместные для Django строковые ссылки: `handler404`,
+  значения настроек DRF (`EXCEPTION_HANDLER`, `DEFAULT_SCHEMA_CLASS`),
+  строковые константы динамических импортов. Версии (`1.2.3`), пути файлов
+  и человекочитаемый текст ссылками не считаются.
+- **Тесты как источник ссылок** — тестовые файлы анализируются ради
+  ссылок на код проекта, поэтому функции, вызываемые только из тестов,
+  не считаются мертвыми; сущности самих тестов в отчет не попадают.
 - **Маршрутизация** — представления из вызовов `path`, `re_path`, `url`
   (включая строковые ссылки `myapp.views.my_view`) помечаются точками входа.
 - **Админка** — строковые значения `list_display`, `list_filter`, `actions`,

src/config.rs

@@ -42,11 +42,7 @@ pub struct AnalyzerConfiguration {
 impl Default for AnalyzerConfiguration {
     fn default() -> Self {
         Self {
-            exclude_directories: vec![
-                ".venv".to_string(),
-                "migrations".to_string(),
-                "tests".to_string(),
-            ],
+            exclude_directories: vec![".venv".to_string(), "migrations".to_string()],
             extra_entry_point_decorators: Vec::new(),
             extra_dynamic_names: Vec::new(),
             extra_framework_base_markers: Vec::new(),
@@ -155,7 +151,8 @@ mod tests {
         assert!(configuration
             .exclude_directories
             .contains(&"migrations".to_string()));
-        assert!(configuration
+        // Тесты не исключаются полностью: они нужны как источник ссылок.
+        assert!(!configuration
             .exclude_directories
             .contains(&"tests".to_string()));
     }

src/heuristics.rs

@@ -293,6 +293,74 @@ pub fn last_dotted_segment(dotted_name: &str) -> &str {
     dotted_name.rsplit('.').next().unwrap_or(dotted_name)
 }
 
+/// Проверяет, похож ли строковый литерал на точечную ссылку Python.
+///
+/// Django и его экосистема повсеместно ссылаются на код строками:
+/// `handler404 = 'app.views.handler'`, `'EXCEPTION_HANDLER':
+/// 'api.exception_handler.custom_handler'`, динамические импорты вида
+/// `'dms.schema_filters.reviews_endpoints_filter'`. Такие строки невозможно
+/// отличить от обычного текста без эвристики, поэтому ссылкой считается
+/// строка не короче двух сегментов, каждый из которых — корректный
+/// идентификатор Python. Это отсекает версии (`1.2.3`), пути файлов
+/// и человекочитаемый текст, оставляя пути импорта и обращения к атрибутам.
+///
+/// :param literal_value: Содержимое строкового литерала.
+/// :return: Признак строки, похожей на точечную ссылку на код.
+pub fn looks_like_dotted_reference(literal_value: &str) -> bool {
+    let mut segment_count = 0usize;
+    for segment in literal_value.split('.') {
+        if !is_python_identifier(segment) {
+            return false;
+        }
+        segment_count += 1;
+    }
+    segment_count >= 2
+}
+
+/// Проверяет, является ли сегмент корректным идентификатором Python.
+///
+/// :param segment: Проверяемый сегмент точечного имени.
+/// :return: Признак корректного идентификатора Python.
+fn is_python_identifier(segment: &str) -> bool {
+    let mut characters = segment.chars();
+    match characters.next() {
+        // Python 3 допускает не-ASCII идентификаторы (`обработчик`),
+        // поэтому используются Unicode-категории, а не ASCII-проверки.
+        Some(first_character) if first_character == '_' || first_character.is_alphabetic() => {}
+        _ => return false,
+    }
+    characters.all(|character| character == '_' || character.is_alphanumeric())
+}
+
+/// Проверяет принадлежность файла к тестам по соглашениям Pytest и Django.
+///
+/// Тестами считаются файлы внутри пакета `tests`, а также файлы
+/// `test_*.py`, `*_test.py`, `tests.py` и `conftest.py`. Директория с
+/// именем `test` в единственном числе не считается тестовой: это слишком
+/// частое имя продуктового пакета, и пометка скрыла бы реальный мертвый
+/// код. Тестовые файлы анализируются только как источник ссылок: код,
+/// используемый исключительно в тестах, не считается мертвым, а сами
+/// тесты не попадают в отчет.
+///
+/// :param file_path: Путь к анализируемому файлу.
+/// :return: Признак тестового файла.
+pub fn is_test_file_path(file_path: &Path) -> bool {
+    let inside_tests_package = file_path
+        .components()
+        .filter_map(|component| component.as_os_str().to_str())
+        .any(|component| component == "tests");
+    if inside_tests_package {
+        return true;
+    }
+    let Some(file_name) = file_path.file_name().and_then(|name| name.to_str()) else {
+        return false;
+    };
+    file_name == "tests.py"
+        || file_name == "conftest.py"
+        || (file_name.starts_with("test_") && file_name.ends_with(".py"))
+        || file_name.ends_with("_test.py")
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -386,4 +454,38 @@ mod tests {
         )));
         assert!(!is_management_command_path(Path::new("shop/views.py")));
     }
+
+    #[test]
+    fn dotted_references_are_recognized_in_strings() {
+        assert!(looks_like_dotted_reference(
+            "mis_service.api.exception_handler.custom_exception_handler"
+        ));
+        assert!(looks_like_dotted_reference("app.views.handler"));
+        assert!(looks_like_dotted_reference("_private.module._name"));
+        // Не-ASCII идентификаторы допустимы в Python 3.
+        assert!(looks_like_dotted_reference("проект.views.обработчик"));
+        // Одного сегмента недостаточно: слишком много ложных совпадений.
+        assert!(!looks_like_dotted_reference("custom_exception_handler"));
+        // Версии и пути файлов не являются ссылками на код.
+        assert!(!looks_like_dotted_reference("1.2.3"));
+        assert!(!looks_like_dotted_reference("app.views.1handler"));
+        assert!(!looks_like_dotted_reference("product-list"));
+        assert!(!looks_like_dotted_reference("module..name"));
+        assert!(!looks_like_dotted_reference("some text.with spaces"));
+        assert!(!looks_like_dotted_reference(""));
+    }
+
+    #[test]
+    fn test_files_are_recognized() {
+        assert!(is_test_file_path(Path::new("shop/tests/test_views.py")));
+        assert!(is_test_file_path(Path::new("shop/tests.py")));
+        assert!(is_test_file_path(Path::new("conftest.py")));
+        assert!(is_test_file_path(Path::new("shop/test_models.py")));
+        assert!(is_test_file_path(Path::new("shop/models_test.py")));
+        assert!(!is_test_file_path(Path::new("shop/models.py")));
+        assert!(!is_test_file_path(Path::new("shop/latest.py")));
+        // Каталог `test` в единственном числе — частое имя продуктового
+        // пакета, поэтому тестовым не считается.
+        assert!(!is_test_file_path(Path::new("app/test/factories.py")));
+    }
 }

src/model.rs

@@ -73,6 +73,11 @@ pub struct FileAnalysis {
     pub scoped_references: Vec<ScopedReference>,
     /// Пул динамических строковых ссылок.
     pub dynamic_references: Vec<String>,
+    /// Признак файла, анализируемого только как источник ссылок.
+    ///
+    /// Тестовые файлы поддерживают живым код, используемый лишь в тестах,
+    /// но их собственные сущности не считаются мертвым кодом.
+    pub is_reference_only: bool,
 }
 
 /// Файл, пропущенный при анализе из-за ошибки чтения или парсинга.

src/pipeline/extract.rs

@@ -68,14 +68,24 @@ pub fn analyze_python_file(
             reason: "парсер tree-sitter не построил синтаксическое дерево".to_string(),
         })?;
 
+    // Признак тестового файла определяется по пути относительно корня
+    // проекта. Если префикс снять не удалось, файл считается обычным:
+    // сканировать абсолютный путь нельзя — каталог-предок с именем `tests`
+    // выше корня иначе пометил бы весь проект как источник ссылок.
+    let is_reference_only = file_path
+        .strip_prefix(project_root)
+        .map(heuristics::is_test_file_path)
+        .unwrap_or(false);
     let mut entity_extractor = EntityExtractor::new(
         &source_code,
         file_path,
         compute_module_path(file_path, project_root),
         configuration,
     );
     entity_extractor.visit_node(syntax_tree.root_node());
-    Ok(entity_extractor.into_analysis())
+    let mut file_analysis = entity_extractor.into_analysis();
+    file_analysis.is_reference_only = is_reference_only;
+    Ok(file_analysis)
 }
 
 /// Вычисляет точечный путь модуля по расположению файла.
@@ -161,9 +171,13 @@ impl<'source> EntityExtractor<'source> {
 
     /// Завершает обход и возвращает результат анализа файла.
     ///
+    /// Признак `is_reference_only` проставляется вызывающей стороной,
+    /// располагающей путем файла относительно корня проекта.
+    ///
     /// :return: Результат анализа файла.
     fn into_analysis(self) -> FileAnalysis {
         FileAnalysis {
+            is_reference_only: false,
             module_path: self.module_path,
             entities: self.entities,
             scoped_references: self.references.into_iter().collect(),
@@ -206,10 +220,30 @@ impl<'source> EntityExtractor<'source> {
             "call" => self.process_call(current_node),
             "assignment" => self.process_assignment(current_node),
             "identifier" => self.record_reference(self.node_text(current_node)),
+            "string" => self.process_string_literal(current_node),
             _ => self.visit_children(current_node),
         }
     }
 
+    /// Обрабатывает строковый литерал.
+    ///
+    /// Строка, похожая на точечную ссылку на код (`app.views.handler`),
+    /// добавляется в пул динамических ссылок: так покрываются строковые
+    /// настройки Django, обработчики и динамические импорты. Потомки
+    /// обходятся, чтобы сохранить ссылки из интерполяций f-строк.
+    ///
+    /// :param string_node: Узел `string`.
+    fn process_string_literal(&mut self, string_node: Node) {
+        // Проверка выполняется по заимствованному срезу: аллокация строки
+        // нужна лишь при совпадении, а не на каждом литерале файла.
+        if let Some(literal_text) = self.string_literal_text(string_node) {
+            if heuristics::looks_like_dotted_reference(literal_text) {
+                self.dynamic_references.insert(literal_text.to_string());
+            }
+        }
+        self.visit_children(string_node);
+    }
+
     /// Обходит все дочерние узлы текущего узла.
     ///
     /// :param current_node: Текущий узел дерева tree-sitter.
@@ -611,13 +645,21 @@ impl<'source> EntityExtractor<'source> {
     /// :param node: Проверяемый узел дерева.
     /// :return: Содержимое строки либо `None` для других видов узлов.
     fn string_literal_value(&self, node: Node) -> Option<String> {
+        self.string_literal_text(node).map(str::to_string)
+    }
+
+    /// Возвращает содержимое строкового литерала без копирования.
+    ///
+    /// :param node: Проверяемый узел дерева.
+    /// :return: Срез содержимого строки либо `None` для других видов узлов.
+    fn string_literal_text(&self, node: Node) -> Option<&'source str> {
         if node.kind() != "string" {
             return None;
         }
         let mut tree_cursor = node.walk();
         for child_node in node.children(&mut tree_cursor) {
             if child_node.kind() == "string_content" {
-                return Some(self.node_text(child_node).to_string());
+                return Some(self.node_text(child_node));
             }
         }
         None

src/pipeline/reachability.rs

@@ -26,6 +26,7 @@ pub fn find_unreachable_entities<'analysis>(
     let mut scope_nodes: HashMap<&str, NodeIndex> = HashMap::new();
     let mut name_index: HashMap<&str, Vec<NodeIndex>> = HashMap::new();
     let mut entities_by_node: HashMap<NodeIndex, &CodeEntity> = HashMap::new();
+    let mut reference_only_nodes: HashSet<NodeIndex> = HashSet::new();
 
     for file_analysis in file_analyses {
         let module_node = dependency_graph.add_node(file_analysis.module_path.as_str());
@@ -41,6 +42,9 @@ pub fn find_unreachable_entities<'analysis>(
                 .or_default()
                 .push(entity_node);
             entities_by_node.insert(entity_node, code_entity);
+            if file_analysis.is_reference_only {
+                reference_only_nodes.insert(entity_node);
+            }
         }
     }
 
@@ -65,7 +69,9 @@ pub fn find_unreachable_entities<'analysis>(
 
     let mut unreachable_entities: Vec<&CodeEntity> = entities_by_node
         .iter()
-        .filter(|(node_index, _)| !reachable_nodes.contains(node_index))
+        .filter(|(node_index, _)| {
+            !reachable_nodes.contains(node_index) && !reference_only_nodes.contains(node_index)
+        })
         .map(|(_, code_entity)| *code_entity)
         .collect();
     unreachable_entities.sort_by(|first, second| {
@@ -136,6 +142,9 @@ fn add_containment_edges(
 ///
 /// Точечные строки вида `myapp.views.my_view` разрешаются до простого
 /// имени функции. Имена из конфигурации пользователя дополняют пул.
+/// Строки из тестовых файлов в пул не попадают: тест, упоминающий имя
+/// строкой, не должен оживлять мертвый продуктовый код (реальные ссылки
+/// из тестов учитываются графом по именам, а не через этот пул).
 ///
 /// :param file_analyses: Результаты анализа файлов.
 /// :param configuration: Конфигурация анализатора.
@@ -148,6 +157,7 @@ fn build_dynamic_reference_pool<'analysis>(
     let configured_names = configuration.extra_dynamic_names.iter().map(String::as_str);
     let extracted_names = file_analyses
         .iter()
+        .filter(|file_analysis| !file_analysis.is_reference_only)
         .flat_map(|file_analysis| file_analysis.dynamic_references.iter().map(String::as_str));
     for dynamic_name in configured_names.chain(extracted_names) {
         dynamic_reference_pool.insert(dynamic_name);