jprotect 0.1.0__py3-none-any.whl

jprotect/__init__.py

@@ -0,0 +1,4 @@
+"""Package jProtect."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

jprotect/__main__.py

@@ -0,0 +1,5 @@
+from jprotect.cli.main import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jprotect/cli/__init__.py

@@ -0,0 +1 @@
+"""Package CLI cho jProtect."""

jprotect/cli/main.py

@@ -0,0 +1,64 @@
+import argparse
+
+from jprotect.config.loader import load_from_cli, validate_config
+from jprotect.core.pipeline import run_pipeline
+from jprotect.core.report import print_summary
+from jprotect.errors import JProtectError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Tạo parser cho CLI và đăng ký các tham số của lệnh protect-module.
+
+    Ví dụ: phân tích ``protect-module --input a --output b --compile``.
+    """
+    parser = argparse.ArgumentParser(description="jProtect CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    protect_parser = subparsers.add_parser("protect-module", help="Bảo vệ một module Odoo")
+    protect_parser.add_argument("--input", required=True, help="Đường dẫn thư mục module Odoo")
+    protect_parser.add_argument("--output", required=True, help="Đường dẫn output cho module đã bảo vệ")
+    protect_parser.add_argument("--mode", choices=["dist", "inplace"], default="dist")
+    protect_parser.add_argument("--dry-run", action="store_true", help="Chỉ quét và báo cáo, không ghi file")
+    protect_parser.add_argument(
+        "--compile",
+        action="store_true",
+        help="Compile các file đã tách thành nhị phân (.so/.pyd) bằng Cython",
+    )
+    protect_parser.add_argument(
+        "--include",
+        action="append",
+        help="Glob include, có thể lặp lại. Mặc định: models/**/*.py",
+    )
+    protect_parser.add_argument(
+        "--exclude",
+        action="append",
+        help="Glob exclude, có thể lặp lại.",
+    )
+    return parser
+
+
+def main() -> int:
+    """Điểm vào CLI: đọc tham số, chạy pipeline và in kết quả.
+
+    Ví dụ: trả về 0 khi thành công, 2 khi gặp JProtectError.
+    """
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        config = load_from_cli(args)
+        validate_config(config)
+        report = run_pipeline(config)
+        print_summary(report)
+        if config.dry_run:
+            print("Dry-run mode: no files were written.")
+        else:
+            print(f"Manifest    : {report.get('manifest_path')}")
+        return 0
+    except JProtectError as exc:
+        print(f"Error: {exc}")
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jprotect/config/__init__.py

@@ -0,0 +1 @@
+"""Package cấu hình cho jProtect."""

jprotect/config/loader.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+from jprotect.config.schema import DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS, ProtectConfig
+from jprotect.errors import ConfigError
+
+
+def _normalize_patterns(patterns: list[str] | None, defaults: list[str]) -> list[str]:
+    """Chuẩn hóa danh sách pattern; trả về giá trị mặc định nếu rỗng.
+
+    Ví dụ: None -> defaults; ['  ', ''] -> defaults; [' models/*.py '] -> ['models/*.py'].
+    """
+    if not patterns:
+        return list(defaults)
+    normalized = [p.strip() for p in patterns if p and p.strip()]
+    if not normalized:
+        return list(defaults)
+    return normalized
+
+
+def load_from_cli(args) -> ProtectConfig:
+    """Dựng đối tượng args từ argparse thành ProtectConfig.
+
+    Ví dụ: args(input='a', output='b', mode='dist', compile=True) ->
+    ProtectConfig tương ứng với đường dẫn đã resolve.
+    """
+    include_patterns = _normalize_patterns(args.include, DEFAULT_INCLUDE_PATTERNS)
+    exclude_patterns = _normalize_patterns(args.exclude, DEFAULT_EXCLUDE_PATTERNS)
+    return ProtectConfig(
+        input_path=Path(args.input).resolve(),
+        output_path=Path(args.output).resolve(),
+        mode=args.mode,
+        dry_run=bool(args.dry_run),
+        compile=bool(getattr(args, "compile", False)),
+        include_patterns=include_patterns,
+        exclude_patterns=exclude_patterns,
+    )
+
+
+def validate_config(config: ProtectConfig) -> None:
+    """Kiểm tra tính hợp lệ của config trước khi chạy pipeline.
+
+    Ví dụ: mode lạ -> ConfigError; input không tồn tại -> ConfigError;
+    dist nhưng input trùng output -> ConfigError.
+    """
+    if config.mode not in {"dist", "inplace"}:
+        raise ConfigError(f"Unsupported mode: {config.mode}")
+
+    if not config.input_path.exists() or not config.input_path.is_dir():
+        raise ConfigError(f"Input path does not exist or is not a directory: {config.input_path}")
+
+    if config.mode == "dist" and config.input_path == config.output_path:
+        raise ConfigError("Output path must differ from input path when mode is 'dist'.")
+
+    if config.mode == "inplace" and config.output_path != config.input_path:
+        raise ConfigError("Output path must equal input path when mode is 'inplace'.")

jprotect/config/schema.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+DEFAULT_INCLUDE_PATTERNS = ["models/**/*.py"]
+DEFAULT_EXCLUDE_PATTERNS = [
+    "**/__init__.py",
+    "**/__manifest__.py",
+    "**/migrations/**",
+    "**/controllers/**",
+    "**/*hook*.py",
+]
+
+
+@dataclass
+class ProtectConfig:
+    """Cấu hình đầy đủ cho một lần chạy protect-module.
+
+    Ví dụ: ProtectConfig(input_path=Path('addons/sale_ext'),
+    output_path=Path('dist/sale_ext'), mode='dist', compile=True).
+    """
+
+    input_path: Path
+    output_path: Path
+    mode: str = "dist"
+    dry_run: bool = False
+    compile: bool = False
+    include_patterns: list[str] = field(default_factory=lambda: list(DEFAULT_INCLUDE_PATTERNS))
+    exclude_patterns: list[str] = field(default_factory=lambda: list(DEFAULT_EXCLUDE_PATTERNS))

jprotect/core/__init__.py

@@ -0,0 +1 @@
+"""Package core (lõi xử lý) cho jProtect."""

jprotect/core/compile/__init__.py

@@ -0,0 +1 @@
+"""Các backend compile cho jProtect."""

jprotect/core/compile/cython_backend.py

@@ -0,0 +1,106 @@
+"""Backend compile Cython (Phase 3).
+
+Nhận các file trong package _protected, build thành extension nhị phân (.so/.pyd),
+sau đó xóa file .py và .c trung gian để chỉ giữ lại artifact đã bảo vệ.
+
+Lưu ý quan trọng về Odoo: tên extension được đặt theo dạng
+``<ten_addon>.<duong_dan_tuong_doi>`` và build từ thư mục cha của module. Nhờ vậy
+``__module__`` của class compile bắt đầu bằng tên addon, giúp Odoo gán model đúng
+addon (Odoo lấy thành phần đầu của ``__module__`` để xác định addon).
+"""
+
+import os
+import shutil
+from pathlib import Path
+
+from jprotect.errors import JProtectError
+
+ARTIFACT_SUFFIXES = {".so", ".pyd"}
+
+
+def _ensure_toolchain() -> None:
+    """Kiểm tra Cython/setuptools đã sẵn sàng; nếu thiếu thì báo lỗi rõ ràng."""
+    try:
+        import Cython.Build  # noqa: F401
+        import setuptools  # noqa: F401
+    except ImportError as exc:  # pragma: no cover - phụ thuộc môi trường
+        raise JProtectError(
+            "Thieu Cython/setuptools de compile. Cai bang: pip install \".[compile]\""
+        ) from exc
+
+
+def _module_name(file: Path, base_dir: Path) -> str:
+    """Tạo tên module dạng chuỗi có dấu chấm từ đường dẫn tương đối (bỏ .py).
+
+    Ví dụ: file ``sale_ext/models/_protected/sale_order.py`` với base_dir là cha
+    của ``sale_ext`` -> 'sale_ext.models._protected.sale_order'.
+    """
+    rel = file.relative_to(base_dir).with_suffix("")
+    return ".".join(rel.parts)
+
+
+def _collect_artifacts(protected_files: list[Path]) -> list[Path]:
+    """Lấy danh sách artifact .so/.pyd bên cạnh từng file đã compile.
+
+    Ví dụ: cạnh ``sale_order.py`` tìm được ``sale_order.cp312-win_amd64.pyd``.
+    """
+    artifacts: list[Path] = []
+    for file in protected_files:
+        for candidate in file.parent.glob(file.stem + ".*"):
+            if candidate.suffix in ARTIFACT_SUFFIXES:
+                artifacts.append(candidate)
+    return artifacts
+
+
+def _cleanup_intermediates(protected_files: list[Path], base_dir: Path) -> None:
+    """Xóa file .py và .c trung gian, và thư mục build tạm sau khi compile.
+
+    Ví dụ: sau khi build ``sale_order.py`` -> xóa ``sale_order.py``, ``sale_order.c``
+    và thư mục ``build/``, chỉ giữ lại file ``.pyd``/``.so``.
+    """
+    for file in protected_files:
+        c_file = file.with_suffix(".c")
+        if c_file.exists():
+            c_file.unlink()
+        if file.exists():
+            file.unlink()
+    build_temp = base_dir / "build"
+    if build_temp.is_dir():
+        shutil.rmtree(build_temp, ignore_errors=True)
+
+
+def compile_protected_files(files: list[Path], output_root: Path) -> list[Path]:
+    """Build các file đã tách thành extension nhị phân (.so/.pyd) bằng Cython.
+
+    Ví dụ: với ``[.../_protected/sale_order.py]`` và output_root là thư mục module,
+    trả về ``[.../_protected/sale_order.cp312-win_amd64.pyd]``.
+    """
+    targets = [f for f in files if f.name != "__init__.py"]
+    if not targets:
+        return []
+    _ensure_toolchain()
+
+    from Cython.Build import cythonize
+    from setuptools import Extension, setup
+
+    # Build từ thư mục cha của module để tên extension có tiền tố là tên addon.
+    base_dir = output_root.parent
+
+    cwd = Path.cwd()
+    os.chdir(base_dir)
+    try:
+        extensions = [
+            Extension(_module_name(f, base_dir), [f.relative_to(base_dir).as_posix()])
+            for f in targets
+        ]
+        setup(
+            name="jprotect_build",
+            ext_modules=cythonize(extensions, language_level=3, quiet=True),
+            script_args=["build_ext", "--inplace"],
+        )
+    finally:
+        os.chdir(cwd)
+
+    artifacts = _collect_artifacts(targets)
+    _cleanup_intermediates(targets, base_dir)
+    return artifacts

jprotect/core/discovery.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+
+from jprotect.errors import ConfigError
+
+
+def discover_module_root(input_path: Path) -> Path:
+    """Xác minh thư mục đầu vào là module Odoo (có __manifest__.py).
+
+    Ví dụ: input ``/addons/sale_ext`` có ``__manifest__.py`` -> trả về chính nó;
+    nếu thiếu manifest -> ném ConfigError.
+    """
+    manifest = input_path / "__manifest__.py"
+    if not manifest.exists():
+        raise ConfigError(f"No __manifest__.py found in module root: {input_path}")
+    return input_path
+
+
+def list_python_files(module_root: Path) -> list[Path]:
+    """Quét và trả về danh sách tất cả file .py trong module (đệ quy).
+
+    Ví dụ: trả về ``[models/__init__.py, models/sale_order.py, ...]``.
+    """
+    files: list[Path] = []
+    for path in module_root.rglob("*.py"):
+        if path.is_file():
+            files.append(path)
+    return sorted(files)

jprotect/core/filtering.py

@@ -0,0 +1,37 @@
+from pathlib import Path
+
+
+def _glob_matches(module_root: Path, patterns: list[str]) -> set[Path]:
+    """Trả về tập file dưới ``module_root`` khớp với bất kỳ glob nào.
+
+    Dùng ``Path.glob`` (hỗ trợ wildcard đệ quy ``**``), nên một pattern duy nhất
+    ``models/**/*.py`` khớp cả file ngay trong ``models`` lẫn thư mục con lồng sâu.
+    """
+    matched: set[Path] = set()
+    for pattern in patterns:
+        for path in module_root.glob(pattern):
+            if path.is_file():
+                matched.add(path)
+    return matched
+
+
+def select_targets(
+    files: list[Path],
+    module_root: Path,
+    include_patterns: list[str],
+    exclude_patterns: list[str],
+) -> tuple[list[Path], list[Path]]:
+    """Chia ``files`` thành (selected, skipped) theo glob include/exclude.
+
+    Ví dụ: include=['models/**/*.py'], exclude=['**/__init__.py'] ->
+    ``models/sale_order.py`` vào selected, ``models/__init__.py`` vào skipped.
+    """
+    included = _glob_matches(module_root, include_patterns)
+    excluded = _glob_matches(module_root, exclude_patterns)
+
+    candidate_set = set(files)
+    selected = sorted((included & candidate_set) - excluded)
+
+    selected_lookup = set(selected)
+    skipped = [path for path in files if path not in selected_lookup]
+    return selected, skipped

jprotect/core/pipeline.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+from shutil import copytree
+
+from jprotect.config.schema import ProtectConfig
+from jprotect.core.compile.cython_backend import compile_protected_files
+from jprotect.core.discovery import discover_module_root, list_python_files
+from jprotect.core.filtering import select_targets
+from jprotect.core.report import build_report, write_manifest_json
+from jprotect.core.safety import assert_safe_output_path
+from jprotect.core.transform.transformer import transform_output_module
+from jprotect.errors import SafetyError
+
+
+def _prepare_output(config: ProtectConfig, module_root: Path) -> Path:
+    """Chuẩn bị thư mục output: giữ nguyên nếu inplace, copy nếu dist.
+
+    Ví dụ: dist mode sẽ copy toàn bộ module sang ``output_path`` (báo lỗi nếu đã tồn tại).
+    """
+    if config.mode == "inplace":
+        return module_root
+
+    output_root = config.output_path
+    if output_root.exists():
+        raise SafetyError(f"Output path already exists: {output_root}")
+
+    copytree(module_root, output_root)
+    return output_root
+
+
+def run_pipeline(config: ProtectConfig) -> dict:
+    """Điều phối toàn bộ pipeline: validate, quét, lọc, transform, compile và report.
+
+    Ví dụ: dry-run chỉ quét và trả report; chạy thật sẽ tạo output module,
+    transform method và (nếu có ``--compile``) build ra .so/.pyd.
+    """
+    module_root = discover_module_root(config.input_path)
+    assert_safe_output_path(module_root, config.output_path, config.mode)
+
+    files = list_python_files(module_root)
+    selected, skipped = select_targets(
+        files=files,
+        module_root=module_root,
+        include_patterns=config.include_patterns,
+        exclude_patterns=config.exclude_patterns,
+    )
+
+    if config.dry_run:
+        output_root = config.output_path if config.mode == "dist" else module_root
+        report = build_report(
+            module_root=module_root,
+            output_root=output_root,
+            selected=selected,
+            skipped=skipped,
+            dry_run=True,
+            mode=config.mode,
+        )
+        report["manifest_path"] = None
+        return report
+
+    output_root = _prepare_output(config, module_root)
+
+    # Phase 2: tách thân method sang _protected và viết lại method công khai (delegation).
+    transform_result = transform_output_module(output_root, module_root, selected)
+
+    # Phase 3: compile các file đã tách thành nhị phân (tùy chọn qua --compile).
+    compiled_artifacts: list[Path] = []
+    if config.compile:
+        compiled_artifacts = compile_protected_files(transform_result.protected_files, output_root)
+
+    report = build_report(
+        module_root=module_root,
+        output_root=output_root,
+        selected=selected,
+        skipped=skipped,
+        dry_run=False,
+        mode=config.mode,
+        transformed=transform_result.protected_files,
+        compiled=compiled_artifacts,
+        compiled_enabled=config.compile,
+    )
+    manifest_path = write_manifest_json(report, output_root)
+    report["manifest_path"] = str(manifest_path)
+    return report

jprotect/core/postprocess.py

@@ -0,0 +1,18 @@
+"""Các hàm hỗ trợ hậu xử lý (placeholder cho Phase 3)."""
+
+from pathlib import Path
+
+
+def normalize_artifact_names(artifacts: list[Path]) -> list[Path]:
+    """Chuẩn hóa tên file artifact sau khi compile (sẽ làm ở Phase 3).
+
+    Ví dụ: hiện tại trả về nguyên danh sách, chưa đổi tên.
+    """
+    return artifacts
+
+
+def cleanup_temp_files(paths: list[Path]) -> None:
+    """Xóa các file trung gian sinh ra trong quá trình build (Phase 3)."""
+    for _path in paths:
+        # Placeholder: chính sách dọn dẹp sẽ được bổ sung ở Phase 3.
+        pass

jprotect/core/report.py

@@ -0,0 +1,61 @@
+import json
+from pathlib import Path
+
+
+def build_report(
+    module_root: Path,
+    output_root: Path,
+    selected: list[Path],
+    skipped: list[Path],
+    dry_run: bool,
+    mode: str,
+    transformed: list[Path] | None = None,
+    compiled: list[Path] | None = None,
+    compiled_enabled: bool = False,
+) -> dict:
+    """Tạo dict report tổng hợp kết quả quét, lọc, transform và compile.
+
+    Ví dụ: trả về dict gồm số file selected/skipped/transformed/compiled và
+    danh sách đường dẫn tương ứng để ghi ra manifest.
+    """
+    transformed = transformed or []
+    compiled = compiled or []
+    return {
+        "module_root": str(module_root),
+        "output_root": str(output_root),
+        "mode": mode,
+        "dry_run": dry_run,
+        "selected_count": len(selected),
+        "skipped_count": len(skipped),
+        "transformed_count": len(transformed),
+        "compiled_enabled": compiled_enabled,
+        "compiled_count": len(compiled),
+        "selected_files": [str(p) for p in selected],
+        "skipped_files": [str(p) for p in skipped],
+        "transformed_files": [str(p) for p in transformed],
+        "compiled_artifacts": [str(p) for p in compiled],
+    }
+
+
+def write_manifest_json(report: dict, output_root: Path) -> Path:
+    """Ghi report ra file protection-manifest.json trong thư mục output.
+
+    Ví dụ: tạo ``<output_root>/protection-manifest.json``.
+    """
+    manifest_path = output_root / "protection-manifest.json"
+    manifest_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+    return manifest_path
+
+
+def print_summary(report: dict) -> None:
+    """In tóm tắt kết quả ra console cho người dùng dễ đọc."""
+    print("=== jProtect Summary ===")
+    print(f"Module root : {report['module_root']}")
+    print(f"Output root : {report['output_root']}")
+    print(f"Mode        : {report['mode']}")
+    print(f"Dry run     : {report['dry_run']}")
+    print(f"Selected    : {report['selected_count']}")
+    print(f"Skipped     : {report['skipped_count']}")
+    if not report['dry_run']:
+        print(f"Transformed : {report.get('transformed_count', 0)}")
+        print(f"Compiled    : {report.get('compiled_count', 0)}")

jprotect/core/safety.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+from jprotect.errors import SafetyError
+
+
+PROTECTED_NAMES = {"", ".", "..", "/", "\\"}
+
+
+def assert_no_destructive_target(path: Path) -> None:
+    """Chặn các đường dẫn nguy hiểm có thể gây xóa nhầm (root, '.', '..').
+
+    Ví dụ: path là '/', '.', '..' sẽ ném SafetyError.
+    """
+    path_str = str(path).strip()
+    if path_str in PROTECTED_NAMES:
+        raise SafetyError(f"Unsafe path: {path}")
+
+
+def assert_safe_output_path(input_path: Path, output_path: Path, mode: str) -> None:
+    """Đảm bảo output an toàn và không nằm bên trong input khi ở chế độ dist.
+
+    Ví dụ: input=/addons/sale_ext, output=/addons/sale_ext/dist -> bị chặn
+    (output nằm trong input).
+    """
+    assert_no_destructive_target(output_path)
+
+    if mode == "dist":
+        # Chặn việc tạo output bên trong cây thư mục input.
+        input_parts = input_path.resolve().parts
+        output_parts = output_path.resolve().parts
+        if output_parts[: len(input_parts)] == input_parts:
+            raise SafetyError("Output path must not be inside input path in dist mode.")

jprotect/core/transform/__init__.py

@@ -0,0 +1 @@
+"""Các implementation cho bước transform của jProtect."""