modwire 1.1.0__tar.gz → 2.0.0__tar.gz

modwire-2.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,106 @@
+name: Bug report
+description: Report incorrect extraction, graph output, architecture analysis, packaging, or runtime behavior.
+title: "Bug: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Clear reproduction details make it much easier to fix issues in extractors and graph analysis.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Describe the bug and the behavior you expected instead.
+      placeholder: Modwire returned...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      options:
+        - Python extractor
+        - TypeScript/JavaScript extractor
+        - PHP extractor
+        - Dependency graph
+        - Architecture policy API
+        - Packaging or installation
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How can we reproduce it?
+      description: Include the smallest source tree, snippet, command, or test case that shows the problem.
+      placeholder: |
+        1. Create this file...
+        2. Run this code...
+        3. Observe...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual output
+      description: Paste the returned objects, graph edges, violation output, traceback, or command output.
+      render: text
+    validations:
+      required: false
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected output
+      description: Describe the graph, source IDs, symbols, imports, or violations you expected.
+    validations:
+      required: false
+
+  - type: input
+    id: modwire-version
+    attributes:
+      label: Modwire version
+      description: Run `python -m pip show modwire` or identify the commit SHA if installed from source.
+      placeholder: 0.0.0 or commit SHA
+    validations:
+      required: false
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.11, 3.12, or 3.13"
+    validations:
+      required: true
+
+  - type: input
+    id: runtime-versions
+    attributes:
+      label: Node.js or PHP version, if relevant
+      description: TypeScript/JavaScript extraction requires Node.js. PHP extraction requires PHP.
+      placeholder: "Node.js 20.x, PHP 8.3, or not applicable"
+    validations:
+      required: false
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 15, Ubuntu 24.04, Windows 11, etc."
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add anything else that may help explain the problem.
+    validations:
+      required: false

modwire-2.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

modwire-2.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,70 @@
+name: Feature request
+description: Suggest a new capability, supported language, extractor improvement, graph API, or architecture rule.
+title: "Feature: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for new capabilities or behavior changes. For incorrect current behavior, please open a bug report instead.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem should this solve?
+      description: Describe the workflow, codebase shape, or analysis gap that motivates the request.
+      placeholder: I want to use Modwire to...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Feature area
+      options:
+        - New language support
+        - Python extractor
+        - TypeScript/JavaScript extractor
+        - PHP extractor
+        - Dependency graph
+        - Architecture policy API
+        - Exports or integrations
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: Explain the API, CLI, output shape, analyzer, or documentation you would like to see.
+      placeholder: Modwire should...
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Example usage or input
+      description: Include a short source snippet, desired graph shape, policy example, or Python API sketch if useful.
+      render: python
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Mention any workaround or different API shape you have considered.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would be interested in working on this.
+          required: false

modwire-2.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+- 
+
+## Validation
+
+- [ ] `uv run ruff check`
+- [ ] `uv run pytest`
+- [ ] `uv run python -m build --outdir dist`
+- [ ] `uv run twine check dist/*`
+
+## Notes
+
+- 

modwire-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to Modwire
+
+Modwire is a Python package for extracting source-code dependencies and
+evaluating architecture rules across Python, TypeScript/JavaScript, and PHP
+projects.
+
+## Requesting Features
+
+Use the `Feature request` issue form for new capabilities, such as:
+
+- support for another language or framework convention
+- richer symbol, import, or graph metadata
+- new architecture analyzers or policy matching behavior
+- export formats or integrations with other tools
+- documentation examples for common workflows
+
+Feature requests are easiest to evaluate when they include the problem being
+solved, a small example input, and the desired API or output shape.
+
+## Reporting Bugs
+
+Use the `Bug report` issue form for incorrect current behavior, such as:
+
+- missing or incorrect imports, symbols, source IDs, or graph edges
+- incorrect architecture-policy violations
+- extractor crashes or runtime failures
+- packaging, installation, or compatibility problems
+- documentation that contradicts the implemented behavior
+
+Bug reports should include a minimal reproduction, the expected output, the
+actual output, and relevant versions for Python, Modwire, Node.js, or PHP.
+
+## Pull Requests
+
+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/`.
+
+Keep pull requests scoped to one behavior change. If an issue exists, link it in
+the pull request description.

modwire-2.0.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: modwire
+Version: 2.0.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.0.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.