gyomu-workflow 0.4.0__tar.gz

gyomu_workflow-0.4.0/.gitignore

@@ -0,0 +1,29 @@
+venv/
+.idea/
+
+/build/
+/dist/
+/src/gyomu.egg-info/
+/.coverage
+/htmlcov/
+__pycache__/
+*.py[cod]
+
+.env
+.env.*
+!.env.example
+
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+*.egg-info/
+log/
+
+
+# gyomu ai related
+**/.gyomu/cache
+**/.gyomu/snapshot
+**/.gyomu/checkpoint
+
+# snapshot
+__snapshots__

gyomu_workflow-0.4.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: gyomu-workflow
+Version: 0.4.0
+Summary: Gyomu CLI
+Requires-Python: >=3.13
+Requires-Dist: gyomu-docstring
+Requires-Dist: gyomu-infra
+Requires-Dist: gyomu-python-analysis
+Requires-Dist: gyomu-schema
+Requires-Dist: returns
+Description-Content-Type: text/markdown
+
+# gyomu-cli
+
+workflow components for Gyomu Python.

gyomu_workflow-0.4.0/README.md

@@ -0,0 +1,3 @@
+# gyomu-cli
+
+workflow components for Gyomu Python.

gyomu_workflow-0.4.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "gyomu-workflow"
+dynamic = ["version"]
+description = "Gyomu CLI"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "gyomu-schema",
+    "gyomu-infra",
+    "returns",
+    "gyomu-python-analysis",
+    "gyomu-docstring"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.uv.sources]
+gyomu-schema = { workspace = true }
+gyomu-infra = { workspace = true }
+gyomu-python-analysis = { workspace = true }
+gyomu-docstring = { workspace = true }
+
+[tool.hatch.version]
+path = "../../version/__about__.py"
+

gyomu_workflow-0.4.0/src/gyomu_workflow/snapshot/error.py

@@ -0,0 +1,51 @@
+from collections.abc import Mapping
+
+from gyomu_schema.error.base import BaseError
+from gyomu_schema.schemas.python.types import ProjectRelativePath
+
+
+class SnapshotRequestValidationError(BaseError):
+    """SnapshotRequest validation error."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        field: str | None = None,
+        expected: object | None = None,
+        actual: object | None = None,
+        context: str | None = None,
+        details: Mapping[str, object] | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            context=context,
+            details=details,
+        )
+        self.code = code
+        self.field = field
+        self.expected = expected
+        self.actual = actual
+
+
+class PyProjectStructureValidationError(BaseError):
+    """Raised when a pyproject structure validation error occurs.
+
+    Raised when the pyproject structure validation fails.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        path: ProjectRelativePath,
+        context: str | None = None,
+        details: Mapping[str, object] | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            context=context,
+            details=details,
+        )
+        self.path = path

gyomu_workflow-0.4.0/src/gyomu_workflow/snapshot/models.py

@@ -0,0 +1,153 @@
+from dataclasses import dataclass
+
+from gyomu_python_analysis.project.context import ProjectContext
+from gyomu_python_analysis.snapshot.models import ProjectSnapshot
+from gyomu_schema.schemas.python.types import ProjectRelativePath
+from gyomu_schema.schemas.types import FullPath
+from pydantic import BaseModel, Field
+
+
+class FileFilter(BaseModel):
+    """File filter pattern configuration.
+
+    Represents a file filter pattern configuration.
+    """
+
+    pattern: str
+    """File path matching pattern.
+
+    The file path matching pattern.
+    """
+
+
+class SnapshotTargetOption(BaseModel):
+    """Snapshot target selection options.
+
+    Represents options for selecting snapshot targets.
+    """
+
+    all: bool = Field(default=False)
+    """Whether to target all files.
+
+    Whether to target all files.
+    """
+    file_filter: FileFilter | None = Field(default=None)
+    """Optional file filter.
+
+    Optional file filter criteria.
+    """
+
+
+class DocstringExecutionOption(BaseModel):
+    """Docstring execution options.
+
+    Represents execution options for docstring generation.
+    """
+
+    enabled: bool = Field(default=True)
+    """Whether docstring generation is enabled.
+
+    Whether docstring generation is enabled.
+    """
+    log_keyword: str | None = Field(default=None)
+    """Optional log keyword.
+
+    Optional keyword to trigger logging.
+    """
+
+
+class SnapshotActionOption(BaseModel):
+    """Snapshot action configuration options.
+
+    Represents options for snapshot actions such as docstring generation, project
+    context, and unit tests.
+    """
+
+    docstring: DocstringExecutionOption
+    """Docstring execution options.
+
+    Docstring execution options.
+    """
+    project_context: bool = Field(default=False)
+    """Whether to include project context.
+
+    Whether to include project context.
+    """
+    unit_test: bool = Field(default=False)
+    """Whether to generate unit tests.
+
+    Whether to generate unit tests.
+    """
+
+
+class SnapshotExecutionOption(BaseModel):
+    """Snapshot execution options.
+
+    Represents execution options for creating a snapshot, including commit settings,
+    targets, and actions.
+    """
+
+    commit: bool
+    """Whether to commit.
+
+    Whether to commit the snapshot.
+    """
+    target: SnapshotTargetOption
+    """Target options.
+
+    Target selection options.
+    """
+    action: SnapshotActionOption
+    """Action options.
+
+    Action options.
+    """
+
+
+@dataclass(frozen=True)
+class SnapshotRequest:
+    """Snapshot request parameters.
+
+    Represents a request to create a snapshot with repository path, project context, and
+    execution options.
+    """
+
+    repository_root_path: FullPath
+    """Repository root path.
+
+    Root path of the repository.
+    """
+    project_context: ProjectContext
+    """Project context.
+
+    Project context information.
+    """
+    option: SnapshotExecutionOption
+    """Execution options.
+
+    Snapshot execution options.
+    """
+
+
+class SnapshotTarget(BaseModel):
+    """Snapshot target state.
+
+    Represents the target state of a snapshot including files, deleted files, and the
+    project snapshot.
+    """
+
+    files: frozenset[ProjectRelativePath]
+    """Target files.
+
+    Set of target files.
+    """
+    deleted_files: frozenset[ProjectRelativePath]
+    """Deleted files.
+
+    Set of deleted files.
+    """
+    snapshot: ProjectSnapshot
+    """Project snapshot.
+
+    The project snapshot.
+    """

gyomu_workflow-0.4.0/src/gyomu_workflow/snapshot/normalize.py

@@ -0,0 +1,30 @@
+from gyomu_workflow.snapshot.models import SnapshotTargetOption
+
+
+def normalize_filter(option: SnapshotTargetOption) -> None:
+    """Normalizes the file filter pattern within a snapshot target option.
+
+    Args:
+        option (SnapshotTargetOption): The snapshot target option to normalize.
+    """
+    if option.file_filter is None:
+        return
+    option.file_filter.pattern = _normalize_snapshot_filter(option.file_filter.pattern)
+
+
+def _normalize_snapshot_filter(
+    filter: str,
+) -> str:
+    """Normalizes a snapshot filter pattern string.
+
+    Args:
+        filter (str): The filter pattern string to normalize.
+
+    Returns:
+        str: The normalized filter pattern string.
+    """
+
+    if filter.endswith("/*"):
+        return f"**/{filter[:-2]}/**"
+
+    return filter

gyomu_workflow-0.4.0/src/gyomu_workflow/snapshot/run.py

@@ -0,0 +1,181 @@
+from gyomu_infra.logger import logger
+from gyomu_python_analysis.analysis.delete_cache import delete_module_cache
+from gyomu_python_analysis.snapshot.analyze import analyze_project_changes
+from gyomu_python_analysis.snapshot.commit import commit_project_changes
+from gyomu_python_analysis.snapshot.models import ProjectSnapshot
+from gyomu_schema.error.gyomu import GyomuError
+from gyomu_schema.option.update import UpdateDebugInfoOption, UpdateOption
+from gyomu_schema.schemas.python.types import ProjectRelativePath
+from gyomu_schema.utility.context import caller_context
+from returns.result import Failure, Result, Success
+
+from gyomu_workflow.snapshot.models import SnapshotRequest, SnapshotTarget
+from gyomu_workflow.snapshot.normalize import normalize_filter
+from gyomu_workflow.snapshot.run_docstring import run_docstring_action
+from gyomu_workflow.snapshot.target import resolve_snapshot_target
+
+
+async def run_snapshot(request: SnapshotRequest) -> Result[None, GyomuError]:
+    """Run the snapshot workflow based on the provided request.
+
+    Args:
+        request (SnapshotRequest): The snapshot request configuration and context.
+
+    Returns:
+        Result[None, GyomuError]: A Result indicating success with None or failure with
+            GyomuError.
+    """
+    normalize_filter(request.option.target)
+    logger.debug(f"file_filter: {repr(request.option.target.file_filter)}")
+    target_result = resolve_snapshot_target(
+        repository_root_path=request.repository_root_path,
+        project_context=request.project_context,
+        option=request.option.target,
+    )
+    if isinstance(target_result, Failure):
+        return target_result
+
+    target = target_result.unwrap()
+
+    logger.debug(repr(target.files))
+    if len(target.files) == 0:
+        logger.debug_object(target.snapshot.files)
+    current_snapshot = target.snapshot
+
+    action_result = await run_actions(request=request, target=target)
+
+    if isinstance(action_result, Failure):
+        return action_result
+    current_snapshot = action_result.unwrap()
+
+    if request.option.commit:
+        commit_result = commit_project_changes(
+            repository_root_path=request.repository_root_path,
+            project_context=request.project_context,
+            expected_snapshot=current_snapshot,
+        )
+        if isinstance(commit_result, Failure):
+            context = caller_context()
+            return commit_result.alt(
+                lambda error: GyomuError(
+                    message="fail to commit project changes",
+                    domain="snapshot",
+                    operation="run_snapshot",
+                    reason="external_failure",
+                    context=context,
+                ).chain(error)
+            )
+    return Success(None)
+
+
+async def run_actions(
+    request: SnapshotRequest, target: SnapshotTarget
+) -> Result[ProjectSnapshot, GyomuError]:
+    """Execute requested actions on the snapshot target files.
+
+    Args:
+        request (SnapshotRequest): The snapshot request configuration.
+        target (SnapshotTarget): The target snapshot data and file lists.
+
+    Returns:
+        Result[ProjectSnapshot, GyomuError]: A Result containing the updated
+            ProjectSnapshot or a GyomuError.
+    """
+    current_snapshot = target.snapshot
+    context = caller_context()
+    option = build_docstring_update_option(request.option.action.docstring.log_keyword)
+    # Do Action
+
+    for deleted in target.deleted_files:
+        if is_source_file(deleted, request.project_context.source_root):
+            delete_result = delete_module_cache(
+                request.project_context, file_path=deleted
+            )
+            if isinstance(delete_result, Failure):
+                return delete_result.alt(
+                    lambda error: GyomuError(
+                        "fail to delete unnecessary module cache",
+                        domain="snapshot",
+                        operation="run_actions",
+                        reason="external_failure",
+                        context=context,
+                    ).chain(error)
+                )
+    project_context = request.project_context
+
+    for file in target.files:
+        if is_source_file(file, request.project_context.source_root):
+            if request.option.action.docstring.enabled:
+                docstring_action_result = await run_docstring_action(
+                    project_context=project_context,
+                    source_project_relative_path=file,
+                    option=option,
+                )
+                if isinstance(docstring_action_result, Failure):
+                    return docstring_action_result
+            if request.option.action.unit_test:
+                pass
+
+    # Post Action
+    if (
+        request.option.action.docstring.enabled
+        or request.option.action.project_context
+        or request.option.action.unit_test
+    ):
+        analysis_result = analyze_project_changes(
+            repository_root_path=request.repository_root_path,
+            project_context=request.project_context,
+        )
+        if isinstance(analysis_result, Failure):
+            return analysis_result.alt(
+                lambda error: GyomuError(
+                    message="fail to analyze project change",
+                    domain="snapshot",
+                    operation="run_actions",
+                    reason="external_failure",
+                    context=context,
+                ).chain(error)
+            )
+        current_snapshot = analysis_result.unwrap().current_snapshot
+
+    return Success(current_snapshot)
+
+
+def build_docstring_update_option(
+    log_keyword: str | None,
+) -> UpdateOption:
+    """Construct the docstring update option configuration.
+
+    Args:
+        log_keyword (str | None): Optional keyword for logging.
+
+    Returns:
+        UpdateOption: The constructed UpdateOption configuration.
+    """
+    return UpdateOption(
+        debug_info=UpdateDebugInfoOption(
+            dump_to_file=True,
+            updated_symbol_docstring=True,
+            file_update_plan=True,
+            rendered_symbol_docstring=True,
+            docstring_update_plan=True,
+            docstring_update_context=True,
+            keyword=log_keyword,
+        ),
+        no_check_cache=True,
+    )
+
+
+def is_source_file(
+    file_path: ProjectRelativePath, source_root: ProjectRelativePath
+) -> bool:
+    """Check whether a file path is a source file.
+
+    Args:
+        file_path (ProjectRelativePath): Path of the file to check.
+        source_root (ProjectRelativePath): Root directory path of the source files.
+
+    Returns:
+        bool: True if the file is a source file, False otherwise.
+    """
+    return file_path.is_relative_to(source_root)

gyomu_workflow-0.4.0/src/gyomu_workflow/snapshot/run_docstring.py

@@ -0,0 +1,101 @@
+from pathlib import Path
+
+from gyomu_docstring.update.process import process_docstring_update
+from gyomu_infra.logger import logger
+from gyomu_python_analysis.analysis.load_file_context import load_file_analysis_context
+from gyomu_python_analysis.project.context import ProjectContext
+from gyomu_schema.error.gyomu import GyomuError
+from gyomu_schema.option.update import UpdateOption
+from gyomu_schema.schemas.python.types import ProjectRelativePath
+from gyomu_schema.utility.context import caller_context
+from returns.result import Failure, Result, Success
+
+
+def is_source_docstring_target(
+    project_context: ProjectContext,
+    source_project_relative_path: ProjectRelativePath,
+) -> bool:
+    """Determine if a source path is a target for docstring processing.
+
+    Determines whether a source file is a target for docstring generation based on
+    project exclusion configurations.
+
+    Args:
+        project_context (ProjectContext): The project context containing configuration
+            settings.
+        source_project_relative_path (ProjectRelativePath): The relative path of the
+            source file within the project.
+
+    Returns:
+        bool: True if the source file is a docstring target, otherwise False.
+    """
+    exclude_path_list = project_context.config.get_attribute(
+        "tool.gyomu.exclude", list[str]
+    )
+    if exclude_path_list is None:
+        return True
+    return not any(
+        source_project_relative_path.is_relative_to(Path(exclude_path))
+        for exclude_path in exclude_path_list
+    )
+
+
+async def run_docstring_action(
+    project_context: ProjectContext,
+    source_project_relative_path: ProjectRelativePath,
+    option: UpdateOption,
+) -> Result[None, GyomuError]:
+    """Run the docstring update action for a specified source file.
+
+    Executes the docstring update action for a given source file within the project.
+
+    Args:
+        project_context (ProjectContext): The project context containing configuration
+            and analysis settings.
+        source_project_relative_path (ProjectRelativePath): The relative path of the
+            source file to process.
+        option (UpdateOption): The update options controlling analysis and modification
+            behavior.
+
+    Returns:
+        Result[None, GyomuError]: A Result indicating success with None or a GyomuError
+            on failure.
+    """
+    if not is_source_docstring_target(project_context, source_project_relative_path):
+        logger.info(f"Not Scope of Docstring:{source_project_relative_path}")
+        return Success(None)
+
+    file_path = source_project_relative_path
+    context = caller_context()
+
+    file_analysis_result = load_file_analysis_context(
+        context=project_context, file_path=file_path, option=option
+    )
+    if isinstance(file_analysis_result, Failure):
+        return file_analysis_result.alt(
+            lambda error: GyomuError(
+                "fail to analyze source file",
+                domain="snapshot",
+                operation="run_docstring_action",
+                reason="external_failure",
+                context=context,
+                details={"file_path": file_path},
+            ).chain(error)
+        )
+
+    file_context = file_analysis_result.unwrap()
+    docstring_update_result = await process_docstring_update(
+        context=project_context, file_context=file_context, option=option
+    )
+    if isinstance(docstring_update_result, Failure):
+        return docstring_update_result.alt(
+            lambda error: GyomuError(
+                "fail to update docstring",
+                domain="snapshot",
+                operation="run_docstring_action",
+                reason="external_failure",
+                context=context,
+                details={"file_path": file_path},
+            ).chain(error)
+        )
+    return Success(None)