gyomu-python-analysis 0.5.0__tar.gz → 0.7.0__tar.gz

gyomu_python_analysis-0.7.0/.gyomu/concept/$Package.json

@@ -0,0 +1,37 @@
+{
+  "summary": "Gyomu Python Analysis is a comprehensive toolkit for statically analyzing Python projects, workspaces, and language constructs. It provides modular AST-based analyzers for examining classes, functions, types, Pydantic models, and expressions, alongside robust workspace initialization, configuration parsing, and project snapshot tracking capabilities.",
+  "responsibilities": [
+    "Analyze Python source code structures, language constructs, and metadata.",
+    "Manage project and workspace initialization, configuration parsing, and module loading contexts.",
+    "Create, diff, and manage project snapshots to track code modifications and changes over time.",
+    "Build symbol indexes, locations, and identity contexts from source code elements."
+  ],
+  "capabilities": [
+    {
+      "name": "Python Language Analysis",
+      "description": "Examines Python language constructs including classes, functions, variables, imports, dependencies, docstrings, type aliases, and Pydantic models."
+    },
+    {
+      "name": "AST Parsing and Indexing",
+      "description": "Parses Python Abstract Syntax Trees to analyze statements, expressions, and build symbol indexes and identities."
+    },
+    {
+      "name": "Workspace and Project Management",
+      "description": "Initializes project and workspace contexts, reads configurations, manages module loading, and handles caching."
+    },
+    {
+      "name": "Snapshot and Version Tracking",
+      "description": "Tracks file modifications, diffs changes between versions, and handles project snapshot creation, validation, and persistence."
+    }
+  ],
+  "design_decisions": [
+    "Employs modular AST-based analyzers to decompose Python language constructs into structured representations.",
+    "Maintains explicit project and workspace contexts to support multi-project configurations and source root resolution.",
+    "Utilizes snapshot tracking with file hashing and modification timestamps to detect and analyze project changes efficiently."
+  ],
+  "usage_guidance": [
+    "Use the workspace and project initialization modules to set up analysis contexts from project configurations.",
+    "Leverage the core analyzers and AST utilities to inspect Python source code constructs and extract symbol metadata.",
+    "Employ snapshot and diffing workflows to track modifications and analyze changes across project files."
+  ]
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/$Directory.json

@@ -0,0 +1,24 @@
+{
+  "summary": "Provides core Python analysis capabilities, including project and workspace initialization, configuration management, path conversion, custom error handling, and snapshot tracking workflows.",
+  "responsibilities": [
+    "Initialize project and workspace contexts, parse configurations, and manage file and module analysis.",
+    "Define custom error types and analysis phases for Python analysis operations.",
+    "Translate between various path formats including project-relative, source-relative, python, and full paths.",
+    "Manage project configurations and workspace structures.",
+    "Track file modifications, compute diffs, and handle snapshot creation, validation, and commit workflows."
+  ],
+  "concepts": [
+    "project analysis",
+    "configuration management",
+    "path conversion",
+    "error handling",
+    "project snapshot"
+  ],
+  "relationships": [
+    "Project and workspace contexts configure project analysis and snapshot management workflows."
+  ],
+  "design_decisions": [
+    "Modular structure organizing core analysis functions into domain-specific subpackages such as analysis, error, path, project, and snapshot."
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/analysis/$Directory.json

@@ -0,0 +1,20 @@
+{
+  "summary": "Performs project and workspace initialization, reads project configurations, manages module loading, caching, and file analysis contexts.",
+  "responsibilities": [
+    "Initialize project contexts and parse project configurations from workspace structures, load and manage module and file analysis contexts, and delete module caches."
+  ],
+  "concepts": [
+    "project initialization",
+    "module loading and analysis",
+    "workspace configuration",
+    "file analysis context",
+    "cache management"
+  ],
+  "relationships": [
+    "Project initialization handles workspace configurations and source roots."
+  ],
+  "design_decisions": [
+    "Modular functions for project initialization, module loading, caching, workspace handling, and file context loading."
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/analysis/analyzers/$Directory.json

@@ -0,0 +1,24 @@
+{
+  "summary": "Provides core analyzer modules for examining Python language constructs such as classes, functions, dependencies, docstrings, imports, Pydantic models, type aliases, types, and variables, along with symbol context management.",
+  "responsibilities": [
+    "Analyze Python classes, functions, dependencies, docstrings, imports, Pydantic models, type aliases, types, and variables, and manage symbol context and identity during code analysis."
+  ],
+  "concepts": [
+    "class analysis",
+    "function analysis",
+    "dependency analysis",
+    "docstring analysis",
+    "import analysis",
+    "pydantic analysis",
+    "type analysis",
+    "variable analysis",
+    "symbol context"
+  ],
+  "relationships": [
+    "Code analysis uses specialized analyzers for classes, functions, dependencies, docstrings, imports, pydantic models, type aliases, types, and variables alongside symbol context management."
+  ],
+  "design_decisions": [
+    "Modular analysis routines for specific Python code constructs and features"
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/analysis/analyzers/ast/$Directory.json

@@ -0,0 +1,18 @@
+{
+  "summary": "Provides AST-based code analysis capabilities, including functions to analyze Python statements and expressions as well as utilities for building symbol indexes.",
+  "responsibilities": [
+    "Provides functions to analyze statements, expressions, tuples, slices, sets, arrays, and dictionaries using Abstract Syntax Trees.",
+    "Builds class and function indexes and AST indexes from source code symbols."
+  ],
+  "concepts": [
+    "AST statement analysis",
+    "AST symbol indexing"
+  ],
+  "relationships": [
+    "Statement analysis and symbol indexing are components of AST-based code analysis."
+  ],
+  "design_decisions": [
+    "Organizes analysis routines into specialized modules for statements, expressions, and symbols."
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/analysis/analyzers/expression/$Directory.json

@@ -0,0 +1,19 @@
+{
+  "summary": "Provides functions for analyzing various types of Python expressions, including constants, subscripts, dictionaries, arrays, literals, type expressions, tuples, sets, and expression names, alongside literal value parsing.",
+  "responsibilities": [
+    "analyze Python expressions including constants, subscripts, dictionaries, arrays, literals, type expressions, tuples, sets, and expression names",
+    "parse literal values"
+  ],
+  "concepts": [
+    "expression analysis",
+    "literal parsing",
+    "type expression analysis"
+  ],
+  "relationships": [
+    "analyze expression delegates to specific analyzers for constants, subscripts, dictionaries, arrays, literals, type expressions, tuples, sets, and expression names"
+  ],
+  "design_decisions": [
+    "modular expression analysis functions"
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/analysis/analyzers/internal/$Directory.json

@@ -0,0 +1,19 @@
+{
+  "summary": "Houses internal helper utilities supporting analysis functionality, specifically providing common building blocks, location calculation, and visibility determination for code analysis.",
+  "responsibilities": [
+    "Provide internal helper utilities for code analysis including calculating symbol locations, determining visibility, and building common components."
+  ],
+  "concepts": [
+    "internal analysis helpers",
+    "symbol location calculation",
+    "visibility calculation",
+    "common analyzer components"
+  ],
+  "relationships": [
+    "Internal analysis modules provide shared calculation utilities for location, visibility, and common metadata attributes."
+  ],
+  "design_decisions": [
+    "Internal module helper functions are grouped together to support analysis logic."
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/analysis/extract/$Directory.json

@@ -0,0 +1,18 @@
+{
+  "summary": "Provides core symbol extraction capabilities and context management for analyzing Python source code.",
+  "responsibilities": [
+    "Extract symbols from Python code analysis.",
+    "Manage context used during symbol extraction."
+  ],
+  "concepts": [
+    "Symbol Extraction",
+    "Symbol Extract Context"
+  ],
+  "relationships": [
+    "SymbolExtractContext provides configuration and context for extract_symbols."
+  ],
+  "design_decisions": [
+    "Provides functional extraction logic operating within a specific context."
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/analysis/file/$Directory.json

@@ -0,0 +1,12 @@
+{
+  "summary": "Provides file-level analysis context and source file representation for Python code analysis.",
+  "responsibilities": [
+    "Manage source file context for analysis"
+  ],
+  "concepts": [
+    "source file context"
+  ],
+  "relationships": [],
+  "design_decisions": [],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/analysis/parser/$Directory.json

@@ -0,0 +1,17 @@
+{
+  "summary": "The parser directory is responsible for analyzing and parsing code documentation, specifically providing docstring parsing capabilities for python analysis.",
+  "responsibilities": [
+    "Parse docstrings to extract analysis information"
+  ],
+  "concepts": [
+    "parser",
+    "docstring parser"
+  ],
+  "relationships": [
+    "DocstringParser provides docstring analysis functionality within the parser module."
+  ],
+  "design_decisions": [
+    "modular parsing organization"
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/error/$Directory.json

@@ -0,0 +1,17 @@
+{
+  "summary": "Provides error handling and analysis phase definitions for Python analysis operations, including custom exception types.",
+  "responsibilities": [
+    "Define error types and analysis phases for Python analysis operations."
+  ],
+  "concepts": [
+    "Python Analysis error",
+    "AnalysisPhase"
+  ],
+  "relationships": [
+    "AnalysisError incorporates or references AnalysisPhase to represent Python analysis errors."
+  ],
+  "design_decisions": [
+    "Defines custom error types and analysis phases for Python analysis operations."
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/path/$Directory.json

@@ -0,0 +1,17 @@
+{
+  "summary": "Provides path conversion and manipulation utilities to translate between different path formats including project-relative paths, source-relative paths, python paths, and full paths.",
+  "responsibilities": [
+    "converts various path representations such as project-relative paths, source-relative paths, python paths, and full paths"
+  ],
+  "concepts": [
+    "path conversion",
+    "path manipulation"
+  ],
+  "relationships": [
+    "converts project-relative paths, source-relative paths, python paths, and full paths to each other using path conversion functions"
+  ],
+  "design_decisions": [
+    "provides functions to convert between project-relative paths, source-relative paths, python paths, and full paths"
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/project/$Directory.json

@@ -0,0 +1,21 @@
+{
+  "summary": "Manages project configuration, context, and workspace definitions, encapsulating settings parsed from configuration files and workspace structures.",
+  "responsibilities": [
+    "Manage project configuration settings parsed from pyproject.toml files.",
+    "Encapsulate project context including roots, configurations, and loaders.",
+    "Define workspace configurations, roots, and constituent projects."
+  ],
+  "concepts": [
+    "Project Context",
+    "Workspace Configuration",
+    "PyProject Config"
+  ],
+  "relationships": [
+    "ProjectContext encapsulates PyProjectConfig and project metadata.",
+    "WorkspaceContext contains WorkspaceConfig and WorkspaceProject instances."
+  ],
+  "design_decisions": [
+    "Encapsulates project context and workspace structures into object representations."
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/concept/src/gyomu_python_analysis/snapshot/$Directory.json

@@ -0,0 +1,25 @@
+{
+  "summary": "Manages project snapshots, tracking file modifications, diffing changes between snapshots, and handling snapshot creation, validation, and commit workflows.",
+  "responsibilities": [
+    "Create and manage project snapshots including target files, hashes, and modification timestamps.",
+    "Analyze, diff, and commit project changes by comparing snapshots.",
+    "Manage project snapshot workspaces and persistence."
+  ],
+  "concepts": [
+    "project snapshot",
+    "project changes",
+    "file snapshots",
+    "snapshot diff",
+    "snapshot workspace"
+  ],
+  "relationships": [
+    "Project changes analysis compares previous and current snapshots.",
+    "Diffing computes differences between previous and current project snapshots.",
+    "Committing validates the project snapshot and commits changes.",
+    "Creating a project snapshot enumerates target files and generates file snapshots."
+  ],
+  "design_decisions": [
+    "Exports functions for creating, validating, committing, analyzing, and diffing project snapshots."
+  ],
+  "importance": "Core"
+}

gyomu_python_analysis-0.7.0/.gyomu/knowledge/Development.yaml

@@ -0,0 +1,11 @@
+# yaml-language-server: $schema=../../../../schemas/Development.json
+
+faq:
+  - question: |
+      このパッケージは単独で利用できますか？
+    answer: |
+      いいえ。gyomu-schema, gyomu-infra に依存しています
+
+known_issues: []
+
+tips: []

gyomu_python_analysis-0.7.0/.gyomu/knowledge/Package.yaml

@@ -0,0 +1,152 @@
+# yaml-language-server: $schema=../../../../schemas/Package.json
+
+display_name: Gyomu Python Analysis
+
+mission: |
+  GyomuにおけるPythonソースコード解析基盤を提供します。
+  PythonプロジェクトおよびWorkspaceを解析し、ソースコードの構造、
+  宣言、依存関係などを構造化された解析モデルとして抽出します。
+  Project ContextやWorkspace Contextを通じて解析対象と設定を一貫して管理し、
+  解析結果とプロジェクト状態を再利用可能な形式で扱えるようにすることで、
+  Concept、Facts、Docstringなどの上位レイヤーが利用する共通の解析基盤を提供します。
+
+policies:
+  - 解析結果はソースコードおよびプロジェクト設定から決定的に導出されるものとする。
+  - Project ContextとWorkspace Contextを通じて解析対象と解析設定を一貫して管理する。
+  - プロジェクト解析とソースファイル解析は独立した責務として設計する。
+  - 解析結果は読み取り専用の構造化されたモデルとして提供し、解析処理によってソースコードを変更しない。
+  - パス解決はプロジェクトおよびWorkspace全体で一貫したルールに従う。
+  - Python固有の解析処理を共通基盤に集約し、上位レイヤーが解析ライブラリの実装詳細へ直接依存しない構造を維持する。
+  - 解析対象のプロジェクト境界とソースルートを明確に管理する。
+  - プロジェクトの状態はSnapshotとして永続化し、後続の処理から再利用できるようにする。
+  - Snapshotは解析対象の現在状態を表現する情報として扱い、ドキュメント更新などの上位処理とは分離する。
+
+constraints:
+  - ソースコードを書き換えてはならない。
+  - READMEや設計ドキュメントなどのドキュメント生成を担当してはならない。
+  - docstringの生成、更新、適用を担当してはならない。
+  - AIによる推論や意味解析を実装してはならない。
+  - 特定プロジェクト固有の解析ロジックを共通解析基盤へ持ち込んではならない。
+  - Python解析ライブラリの実装詳細を上位レイヤーの公開APIとして露出させてはならない。
+  - 解析結果を利用したアプリケーション固有の判断ロジックを実装してはならない。
+  - 解析処理とドキュメント更新処理を結合してはならない。
+
+non_goals:
+  - READMEや設計ドキュメントを生成すること。
+  - docstringを生成・更新・適用すること。
+  - ConceptやKnowledgeなどのプロジェクト知識を生成・管理すること。
+  - AIによるコード推論や意味解析を提供すること。
+  - コード変換やリファクタリングを実行すること。
+  - Pythonソースコードの品質改善やLint修正を実行すること。
+  - 解析結果を利用した重要度評価やアーキテクチャ判断を実行すること。
+  - 解析対象の変更を検出してUpdate Planを生成すること。
+
+terminology:
+  - term: Project Context
+    definition: |
+      Pythonプロジェクトのルート、ソースルート、パッケージ、
+      解析対象ファイルなど、プロジェクト解析に必要な情報を保持するコンテキスト。
+
+  - term: Workspace Context
+    definition: |
+      複数のPythonプロジェクトやパッケージを含むWorkspace全体の解析対象と
+      プロジェクト間の関係を管理するコンテキスト。
+
+  - term: File Analysis
+    definition: |
+      単一のPythonソースファイルから抽出された宣言、シンボル、
+      依存関係などの構造解析結果。
+
+  - term: Project Analysis
+    definition: |
+      Pythonプロジェクトの構造や設定、ソースファイルを解析し、
+      プロジェクト全体の解析情報を構築する処理。
+
+  - term: Snapshot
+    definition: |
+      特定時点におけるPythonプロジェクトの状態を表現する永続化された情報。
+      ファイルハッシュなどを用いて解析対象の状態を記録し、
+      後続の処理から現在のプロジェクト状態を参照できるようにする。
+
+  - term: Source Root
+    definition: |
+      Pythonプロジェクトにおいて解析対象となるソースコードのルートディレクトリ。
+
+  - term: Project Root
+    definition: |
+      Pythonプロジェクトを識別し、pyproject.tomlなどのプロジェクト設定や
+      ソースコードを解決するための基準となるディレクトリ。
+
+rationale:
+  - Pythonソースコードの解析を共通基盤化することで、上位レイヤーは解析ライブラリや解析方法を意識せず利用できる。
+  - Project ContextとWorkspace Contextを導入することで、プロジェクト境界や解析対象を一貫したルールで管理できる。
+  - 解析結果を構造化されたモデルとして提供することで、Concept、Facts、Docstringなど複数の上位処理から再利用できる。
+  - パス解決を共通化することで、プロジェクトルート、ソースルート、ファイルなどの対応を安定して管理できる。
+  - Snapshotによってプロジェクトの特定時点の状態を永続化することで、上位の状態管理処理が現在の解析対象を一貫して参照できる。
+  - Python固有の解析処理を集約することで、上位パッケージがGriffeなどの解析実装へ直接依存することを防げる。
+  - 解析処理とドキュメント生成・更新処理を分離することで、解析結果を複数の用途へ安全に再利用できる。
+
+usage:
+  - situation: Pythonプロジェクトを解析したい
+    guidance: Project Contextを初期化し、プロジェクトのソースルートと解析対象を解決して解析を実行する。
+
+  - situation: Workspace内のPythonプロジェクトを解析したい
+    guidance: Workspace Contextから対象プロジェクトを解決し、そのProject Contextを利用して解析する。
+
+  - situation: 単一のPythonソースファイルを解析したい
+    guidance: File Analysisを利用して、ファイルに含まれる宣言や依存関係などの構造情報を取得する。
+
+  - situation: Pythonプロジェクト全体の構造を取得したい
+    guidance: Project Analysisを利用して、プロジェクトのソースコードと設定から構造化された解析情報を構築する。
+
+  - situation: プロジェクトの現在状態を記録したい
+    guidance: Snapshotを生成して、解析対象の状態を永続化する。
+
+  - situation: ConceptやFactsなどの上位処理で解析結果を利用したい
+    guidance: Python Analysisが提供する構造化された解析モデルを利用し、解析ライブラリの実装へ直接依存しない。
+
+  - situation: テストでPython解析を利用したい
+    guidance: テスト用のプロジェクト構造を用意し、Project Contextを初期化して実際のファイルシステム上で解析する。
+
+examples:
+  - title: プロジェクト解析
+    input: |
+      Pythonプロジェクト全体の構造を解析したい。
+    output: |
+      Project Contextを初期化してPythonプロジェクトを解析する。
+    explanation: |
+      プロジェクトルートとソースルートを基準として解析対象を一貫して解決できる。
+
+  - title: ファイル解析
+    input: |
+      Pythonソースファイルに含まれる公開宣言や依存関係を取得したい。
+    output: |
+      File Analysisを実行して構造化された解析結果を取得する。
+    explanation: |
+      ソースコードを変更せず、ファイルの構造情報のみを取得できる。
+
+  - title: Workspace解析
+    input: |
+      複数のPythonプロジェクトを含むWorkspaceを解析したい。
+    output: |
+      Workspace Contextから対象プロジェクトを解決し、それぞれのProject Contextを利用して解析する。
+    explanation: |
+      Workspace内の複数プロジェクトを、それぞれのプロジェクト境界を維持したまま一貫して解析できる。
+
+  - title: Snapshotの作成
+    input: |
+      Pythonプロジェクトの特定時点の状態を記録したい。
+    output: |
+      Snapshotを生成して解析対象ファイルの状態を永続化する。
+    explanation: |
+      プロジェクトの状態を再利用可能な形式で記録できるため、
+      後続の状態管理処理から一貫して参照できる。
+
+  - title: 上位処理からの解析結果利用
+    input: |
+      ConceptやFactsの処理でPythonソースコードの構造を利用したい。
+    output: |
+      Python Analysisが提供する解析モデルを利用する。
+    explanation: |
+      上位レイヤーはPython解析ライブラリの実装詳細に依存せず、
+      共通化された解析結果を利用できる。

gyomu_python_analysis-0.7.0/.gyomu/knowledge/Roadmap.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=../../../../schemas/Roadmap.json
+
+planned: []
+
+in_progress: []
+
+completed: []
+
+backlog: []

gyomu_python_analysis-0.7.0/.gyomu/knowledge/Technical.yaml

@@ -0,0 +1,34 @@
+# yaml-language-server: $schema=../../../../schemas/Technical.json
+
+installation:
+  - command: uv add gyomu-python-analysis
+    description: |
+      通常のPythonパッケージと同様にインストールする。
+      特別なセットアップは不要。
+
+configuration: []
+
+dependencies:
+  - package: returns
+    description: |
+      Success / Failure / Result による明示的な成功・失敗表現に利用する。
+
+  - package: gyomu-schema
+    description: |
+      スキーマ、共通型の置き場として利用
+
+  - package: gyomu-infra
+    description: |
+      I/Oなどの基盤処理全般に利用
+
+  - package: griffelib
+    description: |
+      Pythonの構文解析に利用
+
+  - package: docstring-parser
+    description: |
+      docstring解析に利用
+
+compatibility: []
+
+migration: []

gyomu_python_analysis-0.7.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: gyomu-python-analysis
+Version: 0.7.0
+Summary: Gyomu Python Analysis
+Author: Yoshihisa Matsumoto
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: docstring-parser>=0.18.0
+Requires-Dist: griffelib>=2.2.0
+Requires-Dist: gyomu-infra
+Requires-Dist: gyomu-schema
+Requires-Dist: pydantic
+Requires-Dist: returns
+Description-Content-Type: text/markdown
+
+# Gyomu Python Analysis
+
+US English | [JP 日本語](README.ja.md)
+
+## Overview
+
+This package serves as a comprehensive static analysis foundation for Python projects and workspaces within Gyomu. Its primary purpose is to examine language constructs and extract source code structures, declarations, and dependencies into a unified, structured analysis model. 
+
+By managing targets and configurations consistently through project and workspace contexts, the toolkit enables analysis results and project states to be handled in a reusable format. This establishes a common infrastructure that empowers upper layers, such as concepts, facts, and docstrings, with reliable structural insights.
+
+## Architecture
+
+Gyomu Python Analysis is organized into modular components that divide responsibilities across language analysis, workspace management, and version tracking. The architecture centers on analyzing Python source structures through AST parsing and dedicated analyzers for language constructs, classes, functions, types, and Pydantic models.
+
+The analysis subsystem handles project and workspace initialization, reads configurations, manages module loading, and maintains file analysis contexts. Within this subsystem, specialized components focus on deep AST inspection of statements and expressions, alongside symbol indexing and identity resolution.
+
+Separately, the snapshot component manages project version tracking by creating, validating, and persisting project snapshots. It collaborates with the broader architecture by tracking file modifications and computing diffs to analyze code changes over time.
+
+## Installation
+
+Install using uv.
+
+```bash
+uv add gyomu-python-analysis
+```
+
+## Dependencies
+
+This package relies on several runtime dependencies for its core functionality. It uses `returns` for explicit success and failure representation via Success, Failure, and Result, while `gyomu-schema` and `gyomu-infra` serve as repositories for common types and general infrastructure processing such as I/O. Additionally, `griffelib` and `docstring-parser` are utilized for AST and docstring analysis, respectively.
+
+## Development
+
+Contributors must ensure that all analysis results are deterministically derived exclusively from source code and project configurations, treating the underlying code as strictly read-only to prevent any unintended modifications during execution. Project Context and Workspace Context must be maintained as the central authorities for managing parsing targets, configuration rules, and path resolution uniformly across the entire scope. To preserve clean architectural boundaries, project-level analysis and individual source file parsing must be strictly separated as independent responsibilities, ensuring that Python-specific implementation details remain encapsulated within this shared foundation and are never leaked to upper layers.
+
+State management relies on the creation, comparison, and persistence of project snapshots, which represent the exact current state of the code over time and must be handled independently of higher-level operations such as documentation updates. Contributors are required to structure all output data as immutable, read-structured models that can be efficiently reused by Concept, Facts, and Docstring layers. Furthermore, any evolution of the codebase must respect clearly defined project boundaries and source roots, maintaining a decoupled architecture where dependent layers interact solely through the provided analysis models and context interfaces rather than direct parsing libraries.
+
+## Public API
+
+- Python Language Analysis - Examines Python language constructs including classes, functions, variables, imports, dependencies, docstrings, type aliases, and Pydantic models.
+- AST Parsing and Indexing - Parses Python Abstract Syntax Trees to analyze statements, expressions, and build symbol indexes and identities.
+- Workspace and Project Management - Initializes project and workspace contexts, reads configurations, manages module loading, and handles caching.
+- Snapshot and Version Tracking - Tracks file modifications, diffs changes between versions, and handles project snapshot creation, validation, and persistence.
+
+## License
+
+MIT

gyomu_python_analysis-0.7.0/README.ja.md

@@ -0,0 +1,46 @@
+# Gyomu Python Analysis
+
+[US English](README.md) | JP 日本語
+
+## 概要
+
+本パッケージは、Gyomu内のPythonプロジェクトやワークスペースを対象とした、包括的な静態解析の基盤として機能します。その主な目的は、言語構造を検証し、ソースコードの構造、宣言、および依存関係を抽出し、統一された構造化解析モデルへと統合することです。
+
+プロジェクトやワークスペースのコンテキストを通じてターゲットと設定を統一的に管理することで、解析結果やプロジェクトの状態を再利用可能な形式で扱うことができます。これにより共通基盤が構築され、Concept、Fact、docstringsなどの上位レイヤーに対して信頼性の高い構造的洞察を提供します。
+
+## アーキテクチャ
+
+Gyomu Python Analysis は、言語分析、ワークスペース管理、バージョン追跡に責任を分割するモジュール式コンポーネントで構成されています。このアーキテクチャは、AST パースと、言語構造、クラス、関数、型、Pydantic モデル向けの専用アナライザーを通じた Python ソース構造の分析を中心としています。
+
+分析サブシステムは、プロジェクトおよびワークスペースの初期化処理、設定の読み込み、モジュール読み込みの管理、ファイル分析コンテキストの維持を行います。このサブシステム内では、専用コンポーネントが文や式の詳細な AST 検査に加えて、シンボルインデックス作成と識別子の解決に注力します。
+
+これとは別に、スナップショットコンポーネントは、プロジェクトスナップショットの作成、検証、永続化によってプロジェクトのバージョン追跡を管理します。ファイル変更の追跡と差分の計算を行い、経時的なコード変更を分析することで、より広範なアーキテクチャと連携します。
+
+## インストール
+
+uv を使用してインストールします。
+
+```bash
+uv add gyomu-python-analysis
+```
+
+## 依存関係
+
+このパッケージは、コア機能の実現にいくつかのランタイム依存関係を利用しています。成功、失敗、結果を明示的に表現するために `returns` を使用し、共通型の保持や入出力などの一般的なインフラストラクチャ処理には `gyomu-schema` および `gyomu-infra` をリポジトリとして利用します。さらに、AST（抽象構文木）およびドキュメント文字列の解析には、それぞれ `griffelib` と `docstring-parser` が使用されます。
+
+## 開発
+
+コントリビューターは、すべての解析結果がソースコードとプロジェクトの設定のみから決定論的に導出されることを確認する必要があります。実行中の意図しない変更を防ぐため、基盤となるコードは厳密に読み取り専用として扱います。Project ContextとWorkspace Contextは、解析ターゲット、設定ルール、およびパス解決をスコープ全体で一元管理するための信頼の唯一の情報源として維持されなければなりません。クリーンなアーキテクチャの境界を維持するため、プロジェクトレベルの解析と個別のソースファイル解析は独立した責務として厳密に分離し、Python固有の実装詳細がこの共有基盤内にカプセル化され、上位レイヤーに漏洩しないようにする必要があります。
+
+状態管理はプロジェクトスナップショットの作成、比較、永続化に依存します。これらは時間の経過におけるコードの正確な現在状態を表すものであり、ドキュメントの更新などの上位レイヤーの操作とは独立して処理されなければなりません。コントリビューターは、すべての出力データを、Concept、Facts、Docstringの各レイヤーによって効率的に再利用できる、不変かつ読み取り構造化されたモデルとして構築することが求められます。さらに、コードベースの変更にあたっては、明確に定義されたプロジェクト境界とソースルートを尊重し、依存レイヤーが直接的な解析ライブラリではなく、提供される解析モデルとcontextインターフェースを介してのみ相互作用する、疎結合なアーキテクチャを維持する必要があります。
+
+## Public API
+
+- Python言語解析 - クラス、関数、変数、インポート、依存関係、ドキュメント文字列、型エイリアス、PydanticモデルなどのPython言語の構文要素を検証します。
+- AST解析とインデックス作成 - Pythonの抽象構文木（AST）を解析して文や式を検証し、シンボルのインデックスと識別子を構築します。
+- ワークスペースおよびプロジェクト管理 - プロジェクトとワークスペースのコンテキストを初期化し、設定を読み込み、モジュールのロードを管理し、キャッシュを処理します。
+- スナップショットとバージョン追跡 - ファイルの変更を追跡し、バージョン間の差分を検出し、プロジェクトのスナップショットの作成、検証、永続化を処理します。
+
+## ライセンス
+
+MIT