modwire 1.1.1__tar.gz → 2.1.0__tar.gz

{modwire-1.1.1 → modwire-2.1.0}/CONTRIBUTING.md

@@ -32,14 +32,8 @@ actual output, and relevant versions for Python, Modwire, Node.js, or PHP.
 
 ## Pull Requests
 
-Before opening a pull request, run the local checks:
-
-```bash
-uv run ruff check
-uv run pytest
-uv run python -m build --outdir dist
-uv run twine check dist/*
-```
+Before opening a pull request, run the local checks documented in
+[Development checks](docs/wiki/Development-checks.md).
 
 Extractor changes should include focused tests under `tests/` and, when
 relevant, a small fixture under `tests/apps/`.

modwire-2.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: modwire
+Version: 2.1.0
+Summary: Extract source-code dependencies and build dependency graphs.
+Author: Tomasz Szpak
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/9orky/modwire
+Project-URL: Repository, https://github.com/9orky/modwire
+Project-URL: Issues, https://github.com/9orky/modwire/issues
+Keywords: architecture,code-analysis,dependency-graph,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# modwire
+
+`modwire` extracts source-code structure and import dependencies from Python,
+TypeScript/JavaScript, and PHP projects. It returns typed Python objects that
+you can use to build dependency graphs, inspect symbols, and evaluate
+architecture rules.
+
+## Installation
+
+```bash
+python -m pip install modwire
+```
+
+The Python extractor works with Python alone. TypeScript/JavaScript extraction
+requires Node.js at runtime, and PHP extraction requires PHP at runtime.
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from modwire import discover_sources, extract_code
+
+manifest = discover_sources(
+    "python",
+    Path("src"),
+    exclusions=("**/__pycache__/**",),
+)
+result = extract_code("python", Path("src"), exclusions=manifest.exclusions)
+
+print(result.extraction_result.summary.files_checked)
+print(result.graph.node_ids())
+print([(edge.from_id, edge.to_id) for edge in result.graph.edges])
+```
+
+Graph nodes use canonical extensionless source IDs, so equivalent Python,
+TypeScript, and PHP projects can be compared through the same graph shape.
+
+## Supported Languages
+
+
+```python
+from modwire import supported_languages
+
+print(supported_languages())
+# ("python", "typescript", "php")
+```
+
+Language-specific source IDs can be normalized without running a full
+extraction:
+
+```python
+from modwire import normalize_source_id
+
+print(normalize_source_id("typescript", "src/view.tsx"))
+# "src/view"
+```
+
+## Extraction Options
+
+Use `SourceRoots` when source IDs should be relative to a workspace root or to a
+logical package prefix:
+
+```python
+from pathlib import Path
+
+from modwire import SourceRoots, extract_code
+
+code_map = extract_code(
+    "python",
+    Path("packages/billing/src"),
+    source_roots=SourceRoots(
+        workspace_root=Path("."),
+        source_id_mode="relative_to_workspace_root",
+    ),
+)
+```
+
+Use `ExtractionCache` to reuse extraction output when files and extractor
+implementations have not changed:
+
+```python
+from pathlib import Path
+
+from modwire import ExtractionCache, extract_code
+
+code_map = extract_code(
+    "python",
+    Path("src"),
+    cache=ExtractionCache(Path(".modwire-cache")),
+)
+
+print(code_map.cache_status)
+```
+
+## Architecture Policy API
+
+`modwire.architecture` exposes policy evaluation helpers for checking import
+boundaries and common dependency-flow rules.
+
+```python
+from modwire import extract_code
+from modwire.architecture import (
+    ArchitectureBoundaryRule,
+    ArchitectureConfig,
+    ArchitectureFlowRules,
+    ArchitecturePolicyEvaluator,
+    ArchitectureRules,
+    ArchitectureTagRule,
+    render_violations,
+    supported_analyzers,
+)
+
+print(supported_analyzers())
+# ("backward-flow", "no-reentry", "no-cycles")
+
+code_map = extract_code("python", "src")
+config = ArchitectureConfig(
+    language="python",
+    architecture_root="src",
+    rules=ArchitectureRules(
+        tags=(
+            ArchitectureTagRule(name="module", match="features/*"),
+            ArchitectureTagRule(name="ui", match="features/*/ui"),
+            ArchitectureTagRule(name="domain", match="features/*/domain"),
+        ),
+        boundaries=(
+            ArchitectureBoundaryRule(
+                source="features/*/ui",
+                disallow=("features/*/domain",),
+                allow_same_match=True,
+            ),
+        ),
+        flow=ArchitectureFlowRules(
+            layers=("domain", "ui"),
+            module_tag="module",
+            analyzers=("no-cycles",),
+        ),
+    ),
+)
+
+violations = ArchitecturePolicyEvaluator().evaluate(code_map.graph, config)
+print(render_violations(tuple(violations)))
+```
+
+Architecture insight helpers summarize ownership and graph pressure:
+
+```python
+from modwire.architecture import coherence_summary, find_hotspots, map_code
+
+architecture_map = map_code(code_map, config)
+hotspots = find_hotspots(code_map, limit=5)
+coherence = coherence_summary(code_map)
+
+print(architecture_map.cross_module_dependencies)
+print(hotspots)
+print(coherence.external_dependencies)
+```
+
+## Shape Policy API
+
+Shape policies evaluate file, symbol, callable, property, and import metadata:
+
+```python
+from modwire import ShapePolicyEvaluator, evaluate_shape
+
+violations = evaluate_shape(
+    code_map,
+    {
+        "max_functions_per_file": 5,
+        "max_methods_per_class": 10,
+        "allow_import_aliases": False,
+        "require_joined_imports": True,
+    },
+)
+
+same_result = ShapePolicyEvaluator().evaluate(code_map, {})
+print([violation.to_dict() for violation in violations])
+print(same_result)
+```
+
+## Serialization And Exports
+
+`CodeMap` results can be serialized for later analysis, and export metadata can
+be used to find currently unused public symbols:
+
+```python
+from modwire import (
+    deserialize_code_map,
+    find_unused_exports,
+    serialize_code_map,
+)
+
+payload = serialize_code_map(code_map)
+loaded = deserialize_code_map(payload)
+
+unused = find_unused_exports(loaded.extraction_result)
+print([(export.source_id, export.name) for export in unused])
+```
+
+## Development
+
+See [Development checks](docs/wiki/Development-checks.md) for the local command
+set used before pull requests and releases.
+
+## Contributing
+
+Feature requests and bug reports are tracked through GitHub Issues:
+
+- Open a feature request for new language support, graph metadata, architecture
+  rules, export formats, or documentation examples.
+- Open a bug report for incorrect extraction results, graph edges, architecture
+  violations, packaging problems, or runtime failures.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the information to include and the
+checks to run before opening a pull request.
+
+Starter wiki pages are tracked under [docs/wiki](docs/wiki) so the GitHub Wiki
+can be initialized with the same guidance.

modwire-2.1.0/README.md

@@ -0,0 +1,219 @@
+# modwire
+
+`modwire` extracts source-code structure and import dependencies from Python,
+TypeScript/JavaScript, and PHP projects. It returns typed Python objects that
+you can use to build dependency graphs, inspect symbols, and evaluate
+architecture rules.
+
+## Installation
+
+```bash
+python -m pip install modwire
+```
+
+The Python extractor works with Python alone. TypeScript/JavaScript extraction
+requires Node.js at runtime, and PHP extraction requires PHP at runtime.
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from modwire import discover_sources, extract_code
+
+manifest = discover_sources(
+    "python",
+    Path("src"),
+    exclusions=("**/__pycache__/**",),
+)
+result = extract_code("python", Path("src"), exclusions=manifest.exclusions)
+
+print(result.extraction_result.summary.files_checked)
+print(result.graph.node_ids())
+print([(edge.from_id, edge.to_id) for edge in result.graph.edges])
+```
+
+Graph nodes use canonical extensionless source IDs, so equivalent Python,
+TypeScript, and PHP projects can be compared through the same graph shape.
+
+## Supported Languages
+
+
+```python
+from modwire import supported_languages
+
+print(supported_languages())
+# ("python", "typescript", "php")
+```
+
+Language-specific source IDs can be normalized without running a full
+extraction:
+
+```python
+from modwire import normalize_source_id
+
+print(normalize_source_id("typescript", "src/view.tsx"))
+# "src/view"
+```
+
+## Extraction Options
+
+Use `SourceRoots` when source IDs should be relative to a workspace root or to a
+logical package prefix:
+
+```python
+from pathlib import Path
+
+from modwire import SourceRoots, extract_code
+
+code_map = extract_code(
+    "python",
+    Path("packages/billing/src"),
+    source_roots=SourceRoots(
+        workspace_root=Path("."),
+        source_id_mode="relative_to_workspace_root",
+    ),
+)
+```
+
+Use `ExtractionCache` to reuse extraction output when files and extractor
+implementations have not changed:
+
+```python
+from pathlib import Path
+
+from modwire import ExtractionCache, extract_code
+
+code_map = extract_code(
+    "python",
+    Path("src"),
+    cache=ExtractionCache(Path(".modwire-cache")),
+)
+
+print(code_map.cache_status)
+```
+
+## Architecture Policy API
+
+`modwire.architecture` exposes policy evaluation helpers for checking import
+boundaries and common dependency-flow rules.
+
+```python
+from modwire import extract_code
+from modwire.architecture import (
+    ArchitectureBoundaryRule,
+    ArchitectureConfig,
+    ArchitectureFlowRules,
+    ArchitecturePolicyEvaluator,
+    ArchitectureRules,
+    ArchitectureTagRule,
+    render_violations,
+    supported_analyzers,
+)
+
+print(supported_analyzers())
+# ("backward-flow", "no-reentry", "no-cycles")
+
+code_map = extract_code("python", "src")
+config = ArchitectureConfig(
+    language="python",
+    architecture_root="src",
+    rules=ArchitectureRules(
+        tags=(
+            ArchitectureTagRule(name="module", match="features/*"),
+            ArchitectureTagRule(name="ui", match="features/*/ui"),
+            ArchitectureTagRule(name="domain", match="features/*/domain"),
+        ),
+        boundaries=(
+            ArchitectureBoundaryRule(
+                source="features/*/ui",
+                disallow=("features/*/domain",),
+                allow_same_match=True,
+            ),
+        ),
+        flow=ArchitectureFlowRules(
+            layers=("domain", "ui"),
+            module_tag="module",
+            analyzers=("no-cycles",),
+        ),
+    ),
+)
+
+violations = ArchitecturePolicyEvaluator().evaluate(code_map.graph, config)
+print(render_violations(tuple(violations)))
+```
+
+Architecture insight helpers summarize ownership and graph pressure:
+
+```python
+from modwire.architecture import coherence_summary, find_hotspots, map_code
+
+architecture_map = map_code(code_map, config)
+hotspots = find_hotspots(code_map, limit=5)
+coherence = coherence_summary(code_map)
+
+print(architecture_map.cross_module_dependencies)
+print(hotspots)
+print(coherence.external_dependencies)
+```
+
+## Shape Policy API
+
+Shape policies evaluate file, symbol, callable, property, and import metadata:
+
+```python
+from modwire import ShapePolicyEvaluator, evaluate_shape
+
+violations = evaluate_shape(
+    code_map,
+    {
+        "max_functions_per_file": 5,
+        "max_methods_per_class": 10,
+        "allow_import_aliases": False,
+        "require_joined_imports": True,
+    },
+)
+
+same_result = ShapePolicyEvaluator().evaluate(code_map, {})
+print([violation.to_dict() for violation in violations])
+print(same_result)
+```
+
+## Serialization And Exports
+
+`CodeMap` results can be serialized for later analysis, and export metadata can
+be used to find currently unused public symbols:
+
+```python
+from modwire import (
+    deserialize_code_map,
+    find_unused_exports,
+    serialize_code_map,
+)
+
+payload = serialize_code_map(code_map)
+loaded = deserialize_code_map(payload)
+
+unused = find_unused_exports(loaded.extraction_result)
+print([(export.source_id, export.name) for export in unused])
+```
+
+## Development
+
+See [Development checks](docs/wiki/Development-checks.md) for the local command
+set used before pull requests and releases.
+
+## Contributing
+
+Feature requests and bug reports are tracked through GitHub Issues:
+
+- Open a feature request for new language support, graph metadata, architecture
+  rules, export formats, or documentation examples.
+- Open a bug report for incorrect extraction results, graph edges, architecture
+  violations, packaging problems, or runtime failures.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the information to include and the
+checks to run before opening a pull request.
+
+Starter wiki pages are tracked under [docs/wiki](docs/wiki) so the GitHub Wiki
+can be initialized with the same guidance.

{modwire-1.1.1 → modwire-2.1.0}/docs/wiki/Development-checks.md

@@ -9,6 +9,9 @@ uv run python -m build --outdir dist
 uv run twine check dist/*
 ```
 
+This page is the canonical local-check list; README and contributor guidance
+link here to avoid release-process drift.
+
 Extractor changes should include focused tests under `tests/` and, when useful,
 small source fixtures under `tests/apps/`.
 

{modwire-1.1.1 → modwire-2.1.0}/docs/wiki/Home.md

@@ -7,6 +7,9 @@ rules.
 
 ## Start Here
 
+- README examples cover extraction manifests, source roots, caching,
+  architecture policies, architecture insights, shape policies, serialization,
+  and unused export checks.
 - [Reporting bugs](Reporting-bugs.md)
 - [Requesting features](Requesting-features.md)
 - [Development checks](Development-checks.md)

modwire-2.1.0/src/modwire/__init__.py

@@ -0,0 +1,96 @@
+from ._version import __version__
+from .callables import (
+    CallableReportEntry,
+    callable_report_entries,
+    render_callable_report,
+    structured_callable_report,
+)
+from .extraction import (
+    CodeMap,
+    CodeMapSerializationError,
+    ExtractionCache,
+    SourceChangedDuringExtractionError,
+    SourceManifest,
+    SourceManifestEntry,
+    SourceRoots,
+    deserialize_code_map,
+    discover_sources,
+    extract_code,
+    serialize_code_map,
+)
+from .extractors.loader import (
+    UnsupportedLanguageError,
+    normalize_source_id,
+    supported_languages,
+)
+from .exports import UnusedExport, find_unused_exports
+from .graph import DependencyGraph, Edge, Node, build_dependency_graph
+from .metadata import (
+    EXTRACTION_SCHEMA_VERSION,
+    PUBLIC_API_STABILITY,
+    ExtractorRuntimeError,
+    LanguageInfo,
+    MissingRuntimeError,
+    RuntimeInfo,
+    extraction_implementation_stamp,
+    language,
+    languages,
+    require_runtime,
+    runtime_diagnostics,
+)
+from .shape import (
+    ShapeConfig,
+    ShapeConfigError,
+    ShapeConfigIssue,
+    ShapePolicyEvaluator,
+    ShapeViolation,
+    evaluate_shape,
+    validate_shape_config,
+)
+
+
+__all__ = [
+    "CodeMap",
+    "CodeMapSerializationError",
+    "CallableReportEntry",
+    "DependencyGraph",
+    "Edge",
+    "EXTRACTION_SCHEMA_VERSION",
+    "ExtractionCache",
+    "ExtractorRuntimeError",
+    "LanguageInfo",
+    "MissingRuntimeError",
+    "Node",
+    "PUBLIC_API_STABILITY",
+    "RuntimeInfo",
+    "ShapeConfig",
+    "ShapeConfigError",
+    "ShapeConfigIssue",
+    "ShapePolicyEvaluator",
+    "ShapeViolation",
+    "SourceChangedDuringExtractionError",
+    "SourceManifest",
+    "SourceManifestEntry",
+    "SourceRoots",
+    "UnsupportedLanguageError",
+    "UnusedExport",
+    "__version__",
+    "build_dependency_graph",
+    "callable_report_entries",
+    "deserialize_code_map",
+    "discover_sources",
+    "evaluate_shape",
+    "extraction_implementation_stamp",
+    "extract_code",
+    "find_unused_exports",
+    "language",
+    "languages",
+    "normalize_source_id",
+    "require_runtime",
+    "render_callable_report",
+    "runtime_diagnostics",
+    "serialize_code_map",
+    "structured_callable_report",
+    "supported_languages",
+    "validate_shape_config",
+]

{modwire-1.1.1 → modwire-2.1.0}/src/modwire/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.1'
-__version_tuple__ = version_tuple = (1, 1, 1)
+__version__ = version = '2.1.0'
+__version_tuple__ = version_tuple = (2, 1, 0)
 
-__commit_id__ = commit_id = 'gbfbd18f94'
+__commit_id__ = commit_id = 'g54f33f5a3'

modwire-2.1.0/src/modwire/architecture/__init__.py

@@ -0,0 +1,59 @@
+from .analyzers import AnalyzerInfo, analyzer_metadata, supported_analyzers
+from .config import (
+    ArchitectureBoundaryRule,
+    ArchitectureConfig,
+    ArchitectureConfigError,
+    ArchitectureConfigIssue,
+    ArchitectureFlowRules,
+    ArchitectureRules,
+    ArchitectureTagRule,
+    validate_policy_config,
+)
+from .insights import (
+    ArchitectureCluster,
+    ArchitectureMap,
+    CoherenceSummary,
+    CrossModuleDependency,
+    DependencyHotspot,
+    cluster_code,
+    coherence_summary,
+    find_hotspots,
+    map_code,
+)
+from .matching import TagMap, TagMatch, TagMatcher
+from .policy import ArchitecturePolicyEvaluator
+from .render import render_violation_payload, render_violations, structured_groups
+from .violations import EdgeRuleViolation, FlowViolation, violation_to_dict
+
+__all__ = [
+    "AnalyzerInfo",
+    "ArchitectureCluster",
+    "ArchitectureBoundaryRule",
+    "ArchitectureConfig",
+    "ArchitectureConfigError",
+    "ArchitectureConfigIssue",
+    "ArchitectureFlowRules",
+    "ArchitectureMap",
+    "ArchitecturePolicyEvaluator",
+    "ArchitectureRules",
+    "ArchitectureTagRule",
+    "CoherenceSummary",
+    "CrossModuleDependency",
+    "DependencyHotspot",
+    "EdgeRuleViolation",
+    "FlowViolation",
+    "TagMap",
+    "TagMatch",
+    "TagMatcher",
+    "analyzer_metadata",
+    "cluster_code",
+    "coherence_summary",
+    "find_hotspots",
+    "map_code",
+    "render_violation_payload",
+    "render_violations",
+    "structured_groups",
+    "supported_analyzers",
+    "validate_policy_config",
+    "violation_to_dict",
+]

{modwire-1.1.1 → modwire-2.1.0}/src/modwire/architecture/analyzers.py

@@ -13,10 +13,29 @@ class FlowAnalyzer:
     run: Callable
 
 
+@dataclass(frozen=True)
+class AnalyzerInfo:
+    name: str
+    title: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "name": self.name,
+            "title": self.title,
+        }
+
+
 def supported_analyzers() -> tuple[str, ...]:
     return tuple(_ANALYZERS)
 
 
+def analyzer_metadata() -> tuple[AnalyzerInfo, ...]:
+    return tuple(
+        AnalyzerInfo(name=analyzer.name, title=analyzer.title)
+        for analyzer in _ANALYZERS.values()
+    )
+
+
 def analyzer_title(name: str) -> str:
     return _ANALYZERS[name].title