v8unpack-agent 0.1.0__py3-none-any.whl

v8unpack_agent/__init__.py

@@ -0,0 +1,322 @@
+"""v8unpack-agent — надстройка над v8unpack для агентных пайплайнов.
+
+Реализует доработки из статьи «Обычные формы 1С в агентном пайплайне:
+пошаговая распаковка»: фабрику путей по конвенции, FormArtifact с флагом
+полноты распаковки, forms_index с контролем рассинхрона и распаковку как
+pre-step индексации.
+
+Публичная поверхность
+---------------------
+- :func:`~v8unpack_agent.form_paths.form_paths`
+- :func:`~v8unpack_agent.form_paths.item_modules`
+- :func:`~v8unpack_agent.form_paths.all_module_paths`
+- :class:`~v8unpack_agent.form_artifact.FormArtifact`
+- :class:`~v8unpack_agent.forms_index.FormsIndex`
+- :class:`~v8unpack_agent.forms_index.FormsIndexEntry`
+- :func:`~v8unpack_agent.forms_index.is_form_stale`
+- :func:`~v8unpack_agent.pipeline.unpack_all_forms`
+- :func:`~v8unpack_agent.pipeline.update_forms_index`
+- :func:`~v8unpack_agent.pipeline.discover_form_bins`
+- :func:`~v8unpack_agent.scan_forms.scan_forms`
+- :class:`~v8unpack_agent.scan_forms.FormEntry`
+- :class:`~v8unpack_agent.scan_forms.FormScanIndex`
+- :func:`~v8unpack_agent.drift_checker.check_drift`
+- :class:`~v8unpack_agent.drift_checker.DriftReport`
+- :func:`~v8unpack_agent.managed_forms.discover_elem_forms` (issue #55)
+- :class:`~v8unpack_agent.managed_forms.ElemFormEntry` (issue #55)
+- :class:`~v8unpack_agent.form_summary.FormSummary` (issue #69)
+- :func:`~v8unpack_agent.form_summary.build_form_summary` (issue #69)
+- :func:`~v8unpack_agent.form_summary.build_form_summary_from_elem_index` (issue #69)
+- :class:`~v8unpack_agent.form_classifier.FormClass` (issue #98)
+- :func:`~v8unpack_agent.form_classifier.classify_form` (issue #98)
+- :func:`~v8unpack_agent.form_classifier.classify_form_by_name` (issue #98)
+- :func:`~v8unpack_agent.form_classifier.classify_form_by_bindings` (issue #98)
+"""
+
+from v8unpack_agent.form_paths import (
+    all_module_paths,
+    form_paths,
+    form_root,
+    item_modules,
+)
+
+
+def __getattr__(name: str):
+    """Lazy-load selected exports to keep `python -m v8unpack_agent.scan_forms` clean."""
+    if name in {
+        "SERVICE_FORM_NAME_PATTERNS",
+        "FormClass",
+        "classify_form",
+        "classify_form_by_bindings",
+        "classify_form_by_name",
+    }:
+        # Ленивая группа form_classifier (issue #140, часть A). Вместе с ней
+        # перестаёт загружаться транзитивный coverage_metric: его тянет
+        # form_classifier ради DATA_ELEMENT_TYPES.
+        from v8unpack_agent.form_classifier import (
+            SERVICE_FORM_NAME_PATTERNS,
+            FormClass,
+            classify_form,
+            classify_form_by_bindings,
+            classify_form_by_name,
+        )
+
+        values = {
+            "SERVICE_FORM_NAME_PATTERNS": SERVICE_FORM_NAME_PATTERNS,
+            "FormClass": FormClass,
+            "classify_form": classify_form,
+            "classify_form_by_bindings": classify_form_by_bindings,
+            "classify_form_by_name": classify_form_by_name,
+        }
+        globals().update(values)
+        return values[name]
+    if name in {"FormRouter", "RouteResult"}:
+        # Ленивая группа form_router (issue #140, часть B). Публичные имена
+        # FormRouter и RouteResult остаются в __all__ и доступны как раньше.
+        from v8unpack_agent.form_router import FormRouter, RouteResult
+
+        values = {
+            "FormRouter": FormRouter,
+            "RouteResult": RouteResult,
+        }
+        globals().update(values)
+        return values[name]
+    if name in {"FormsIndex", "FormsIndexEntry", "is_form_stale"}:
+        from v8unpack_agent.forms_index import (
+            FormsIndex,
+            FormsIndexEntry,
+            is_form_stale,
+        )
+
+        values = {
+            "FormsIndex": FormsIndex,
+            "FormsIndexEntry": FormsIndexEntry,
+            "is_form_stale": is_form_stale,
+        }
+        globals().update(values)
+        return values[name]
+
+    if name in {"SkdResult", "SkdBatchResult", "extract_skd_queries",
+                "extract_all_skd_queries"}:
+        from v8unpack_agent.skd_extractor import (
+            SkdBatchResult,
+            SkdResult,
+            extract_all_skd_queries,
+            extract_skd_queries,
+        )
+
+        values = {
+            "SkdResult": SkdResult,
+            "SkdBatchResult": SkdBatchResult,
+            "extract_skd_queries": extract_skd_queries,
+            "extract_all_skd_queries": extract_all_skd_queries,
+        }
+        globals().update(values)
+        return values[name]
+
+    if name in {"ElemIndexResult", "parse_elem_json"}:
+        from v8unpack_agent.elem_parser import ElemIndexResult, parse_elem_json
+
+        values = {
+            "ElemIndexResult": ElemIndexResult,
+            "parse_elem_json": parse_elem_json,
+        }
+        globals().update(values)
+        return values[name]
+
+    if name in {"FormUnpacker", "ErfUnpacker", "discover_form_bins",
+                "unpack_all_forms", "unpack_erf", "update_forms_index"}:
+        from v8unpack_agent.pipeline import (
+            ErfUnpacker,
+            FormUnpacker,
+            discover_form_bins,
+            unpack_all_forms,
+            unpack_erf,
+            update_forms_index,
+        )
+
+        values = {
+            "FormUnpacker": FormUnpacker,
+            "ErfUnpacker": ErfUnpacker,
+            "discover_form_bins": discover_form_bins,
+            "unpack_all_forms": unpack_all_forms,
+            "unpack_erf": unpack_erf,
+            "update_forms_index": update_forms_index,
+        }
+        globals().update(values)
+        return values[name]
+    
+    if name in {"FormArtifact"}:
+        from v8unpack_agent.form_artifact import FormArtifact
+
+        values = {
+            "FormArtifact": FormArtifact,
+        }
+        globals().update(values)
+        return values[name]
+
+    if name in {"check_drift", "DriftReport"}:
+        from v8unpack_agent.drift_checker import DriftReport, check_drift
+
+        values = {
+            "check_drift": check_drift,
+            "DriftReport": DriftReport,
+        }
+        globals().update(values)
+        return values[name]
+
+    if name in {
+        "AmbiguousFormNameError",
+        "FormBinSource",
+        "FormIdentityError",
+        "adapt_legacy_unpacker",
+        "discover_form_sources",
+    }:
+        from v8unpack_agent.form_identity import (
+            AmbiguousFormNameError,
+            FormBinSource,
+            FormIdentityError,
+            adapt_legacy_unpacker,
+            discover_form_sources,
+        )
+
+        _identity_exports = {
+            "AmbiguousFormNameError": AmbiguousFormNameError,
+            "FormBinSource": FormBinSource,
+            "FormIdentityError": FormIdentityError,
+            "adapt_legacy_unpacker": adapt_legacy_unpacker,
+            "discover_form_sources": discover_form_sources,
+        }
+        globals().update(_identity_exports)
+        return _identity_exports[name]
+
+    if name in {"scan_forms", "FormEntry", "FormScanIndex"}:
+        from v8unpack_agent.scan_forms import FormEntry, FormScanIndex, scan_forms
+
+        values = {
+            "scan_forms": scan_forms,
+            "FormEntry": FormEntry,
+            "FormScanIndex": FormScanIndex,
+        }
+        globals().update(values)
+        return values[name]
+
+    if name in {"discover_elem_forms", "ElemFormEntry",
+                "discover_managed_forms", "ManagedFormEntry"}:
+        from v8unpack_agent.managed_forms import (
+            ElemFormEntry,
+            ManagedFormEntry,
+            discover_elem_forms,
+            discover_managed_forms,
+        )
+
+        values = {
+            "discover_elem_forms": discover_elem_forms,
+            "ElemFormEntry": ElemFormEntry,
+            "discover_managed_forms": discover_managed_forms,
+            "ManagedFormEntry": ManagedFormEntry,
+        }
+        globals().update(values)
+        return values[name]
+
+    if name in {"FormSummary", "build_form_summary",
+                "build_form_summary_from_elem_index"}:
+        from v8unpack_agent.form_summary import (
+            FormSummary,
+            build_form_summary,
+            build_form_summary_from_elem_index,
+        )
+
+        values = {
+            "FormSummary": FormSummary,
+            "build_form_summary": build_form_summary,
+            "build_form_summary_from_elem_index": build_form_summary_from_elem_index,
+        }
+        globals().update(values)
+        return values[name]
+
+    if name in {"FormContext", "build_form_context",
+                "to_llm_prompt_fragment"}:
+        from v8unpack_agent.form_context import (
+            FormContext,
+            build_form_context,
+            to_llm_prompt_fragment,
+        )
+
+        values = {
+            "FormContext": FormContext,
+            "build_form_context": build_form_context,
+            "to_llm_prompt_fragment": to_llm_prompt_fragment,
+        }
+        globals().update(values)
+        return values[name]
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# Публичная поверхность пакета. Порядок — isort-style (требование RUF022):
+# SCREAMING_SNAKE_CASE → CamelCase → snake_case. Порядок не является
+# контрактом: тесты #124/#128/#131/#134 проверяют состав через set()/in,
+# а не последовательность. Ленивые имена разрешаются через PEP 562
+# __getattr__, сортировка не делает импорты eager.
+#
+# Происхождение экспортов (карта сохранена при сортировке):
+#   issue #55                                   — discover_elem_forms
+#                                                 ElemFormEntry
+#   deprecated aliases (обратная совместимость) — discover_managed_forms
+#                                                 ManagedFormEntry
+#   issue #69                                   — FormSummary
+#                                                 build_form_summary
+#                                                 build_form_summary_from_elem_index
+#   issue #124 (form_context, issue #77)        — FormContext
+#                                                 build_form_context
+#                                                 to_llm_prompt_fragment
+#   issue #98                                   — FormClass
+#                                                 classify_form
+#                                                 classify_form_by_name
+#                                                 classify_form_by_bindings
+#                                                 SERVICE_FORM_NAME_PATTERNS
+__all__ = [
+    "SERVICE_FORM_NAME_PATTERNS",
+    "DriftReport",
+    "ElemFormEntry",
+    "ElemIndexResult",
+    "ErfUnpacker",
+    "FormArtifact",
+    "FormClass",
+    "FormContext",
+    "FormEntry",
+    "FormRouter",
+    "FormScanIndex",
+    "FormSummary",
+    "FormUnpacker",
+    "FormsIndex",
+    "FormsIndexEntry",
+    "ManagedFormEntry",
+    "RouteResult",
+    "SkdBatchResult",
+    "SkdResult",
+    "all_module_paths",
+    "build_form_context",
+    "build_form_summary",
+    "build_form_summary_from_elem_index",
+    "check_drift",
+    "classify_form",
+    "classify_form_by_bindings",
+    "classify_form_by_name",
+    "discover_elem_forms",
+    "discover_form_bins",
+    "discover_managed_forms",
+    "extract_all_skd_queries",
+    "extract_skd_queries",
+    "form_paths",
+    "form_root",
+    "is_form_stale",
+    "item_modules",
+    "parse_elem_json",
+    "scan_forms",
+    "to_llm_prompt_fragment",
+    "unpack_all_forms",
+    "unpack_erf",
+    "update_forms_index",
+]

v8unpack_agent/_safe_paths.py

@@ -0,0 +1,135 @@
+"""Обезличенные ссылки на пути файловой системы (issue #123).
+
+Предупреждения парсера регулярно публикуются: в отчётах, логах CI, теле
+issue и PR, промптах к модели. Абсолютный путь несёт имя пользователя и
+структуру локальной ФС, поэтому в текст предупреждения он попадать не
+должен. При этом предупреждение обязано оставаться полезным: по нему
+нужно понять, о какой форме речь.
+
+Модуль решает эту задачу функциями :func:`safe_path_ref` и
+:func:`safe_error_text`. Он намеренно не зависит ни от чего внутри пакета,
+чтобы его могли использовать ``elem_parser`` и ``object_decoder`` без
+циклических импортов.
+
+Почему не :mod:`pathlib`
+------------------------
+
+На POSIX ``Path`` не считает ``\\`` разделителем, поэтому строка вида
+``C:\\dump\\Catalog\\Объект\\CatalogForm\\Форма`` осталась бы единым
+сегментом и утечка сохранилась бы. Разбор идёт регулярным выражением по
+обоим разделителям, поэтому результат не зависит от ОС, на которой
+запущен код или тесты.
+
+Гарантии
+--------
+
+* результат ``safe_path_ref`` никогда не является абсолютным путём;
+* у абсолютного входа сохраняются последние значимые сегменты — для
+  выгрузки 1С это «тип / объект / контейнер / форма»;
+* относительный путь не искажается, пока он не длиннее хвоста;
+* в выводе всегда posix-разделитель ``/``;
+* ``safe_error_text`` сохраняет смысл ошибки, но заменяет переданные
+  связанные пути, включая варианты с ``/`` и ``\\``;
+* функции детерминированы и не обращаются к файловой системе.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "SAFE_TAIL_SEGMENTS",
+    "TRUNCATION_MARKER",
+    "UNKNOWN_REF",
+    "safe_error_text",
+    "safe_path_ref",
+]
+
+#: Сколько хвостовых сегментов сохраняется по умолчанию.
+#: Для выгрузки 1С это тип объекта / объект / контейнер форм / форма.
+SAFE_TAIL_SEGMENTS = 4
+
+#: Признак того, что начало пути отброшено осознанно.
+TRUNCATION_MARKER = "..."
+
+#: Замена для пустого или отсутствующего пути.
+UNKNOWN_REF = "<путь не указан>"
+
+_SEPARATORS_RE = re.compile(r"[\\/]+")
+_WINDOWS_DRIVE_RE = re.compile(r"^[A-Za-z]:$")
+_ABSOLUTE_RE = re.compile(r"^(?:[\\/]|[A-Za-z]:[\\/])")
+
+
+def safe_path_ref(value: object, tail: int = SAFE_TAIL_SEGMENTS) -> str:
+    """Вернуть обезличенную ссылку на путь для текста предупреждения.
+
+    ``value`` может быть ``Path``, строкой с ``/`` или ``\\`` либо ``None``.
+    ``tail`` задаёт число сохраняемых хвостовых сегментов; ``tail <= 0``
+    оставляет только последний сегмент.
+    """
+    if value is None:
+        return UNKNOWN_REF
+
+    text = str(value).strip().strip('"')
+    if not text:
+        return UNKNOWN_REF
+
+    absolute = bool(_ABSOLUTE_RE.match(text))
+    segments = [
+        segment
+        for segment in _SEPARATORS_RE.split(text)
+        if segment not in ("", ".", "..") and not _WINDOWS_DRIVE_RE.match(segment)
+    ]
+    if not segments:
+        return UNKNOWN_REF
+
+    if tail <= 0:
+        return segments[-1]
+
+    if not absolute:
+        if len(segments) <= tail:
+            return "/".join(segments)
+        return f"{TRUNCATION_MARKER}/" + "/".join(segments[-tail:])
+
+    # Абсолютный путь: начало отбрасывается всегда. Если сегментов меньше
+    # хвоста, надёжного слоя-ориентира нет — остаётся только имя.
+    kept = segments[-tail:] if len(segments) > tail else segments[-1:]
+    return f"{TRUNCATION_MARKER}/" + "/".join(kept)
+
+
+def safe_error_text(
+    error: BaseException | object,
+    *paths: object,
+    tail: int = SAFE_TAIL_SEGMENTS,
+) -> str:
+    """Вернуть текст ошибки без известных абсолютных путей.
+
+    ``OSError`` и производные часто повторяют имя файла внутри ``str(exc)``.
+    На Windows это имя может быть записано с удвоенными обратными слешами,
+    поскольку форматируется через строковое представление ``filename``.
+    Для каждого связанного пути заменяются исходная запись, варианты с обоими
+    разделителями и escaped Windows-вариант. Остальной текст сохраняется.
+
+    ``tail`` передаётся в :func:`safe_path_ref`: object JSON использует
+    три сегмента «тип / объект / файл», пути форм сохраняют default из
+    четырёх сегментов.
+    """
+    text = str(error)
+    for path in paths:
+        if path is None:
+            continue
+        raw = str(path)
+        if not raw:
+            continue
+        replacement = safe_path_ref(raw, tail=tail)
+        backslash = raw.replace("/", "\\")
+        variants = {
+            raw,
+            raw.replace("\\", "/"),
+            backslash,
+            backslash.replace("\\", "\\\\"),
+        }
+        for variant in sorted(variants, key=len, reverse=True):
+            if variant:
+                text = text.replace(variant, replacement)
+    return text