modwire 2.3.0__tar.gz → 3.1.1__tar.gz

{modwire-2.3.0 → modwire-3.1.1}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,5 +1,5 @@
 name: Bug report
-description: Report incorrect extraction, graph output, architecture analysis, packaging, or runtime behavior.
+description: Report incorrect architecture analysis, graph output, package metadata, or report output.
 title: "Bug: "
 labels:
   - bug
@@ -7,7 +7,7 @@ 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.
+        Thanks for reporting a bug. Clear reproduction details make it much easier to fix issues in architecture analysis, report output, and package metadata.
 
   - type: textarea
     id: summary
@@ -23,11 +23,11 @@ body:
     attributes:
       label: Affected area
       options:
-        - Python extractor
-        - TypeScript/JavaScript extractor
-        - PHP extractor
-        - Dependency graph
+        - Dependency graph report
         - Architecture policy API
+        - Shape policy API
+        - Callable report
+        - Unused export report
         - Packaging or installation
         - Documentation
         - Other
@@ -59,7 +59,7 @@ body:
     id: expected
     attributes:
       label: Expected output
-      description: Describe the graph, source IDs, symbols, imports, or violations you expected.
+      description: Describe the graph, report entries, or violations you expected.
     validations:
       required: false
 
@@ -83,9 +83,9 @@ body:
   - 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"
+      label: modwire-extraction version, if relevant
+      description: Include the producer version when the issue depends on source metadata.
+      placeholder: "1.0.1 or not applicable"
     validations:
       required: false
 

{modwire-2.3.0 → modwire-3.1.1}/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,5 +1,5 @@
 name: Feature request
-description: Suggest a new capability, supported language, extractor improvement, graph API, or architecture rule.
+description: Suggest a new architecture, graph, shape, callable, export, or integration capability.
 title: "Feature: "
 labels:
   - enhancement
@@ -23,13 +23,12 @@ body:
     attributes:
       label: Feature area
       options:
-        - New language support
-        - Python extractor
-        - TypeScript/JavaScript extractor
-        - PHP extractor
-        - Dependency graph
+        - Dependency graph report
         - Architecture policy API
-        - Exports or integrations
+        - Shape policy API
+        - Callable report
+        - Unused export report
+        - Integrations
         - Documentation
         - Other
     validations:

{modwire-2.3.0 → modwire-3.1.1}/.github/workflows/ci.yml

@@ -27,16 +27,6 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
-      - name: Set up PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: "8.3"
-
       - name: Clean packaging artifacts
         run: rm -rf .dev build dist src/*.egg-info
 
@@ -48,11 +38,6 @@ jobs:
       - name: Run unit tests
         run: python -m pytest
 
-      - name: Validate extractor syntax
-        run: |
-          node --check src/modwire/extractors/scripts/typescript_extractor.js
-          php -l src/modwire/extractors/scripts/php_extractor.php
-
       - name: Build distributions
         run: python -m build --outdir dist
 

{modwire-2.3.0 → modwire-3.1.1}/.github/workflows/release.yml

@@ -46,21 +46,20 @@ jobs:
             exit 1
           fi
 
+      - name: Use release tag as package version
+        if: github.event_name == 'release'
+        run: |
+          tag_name="${{ github.event.release.tag_name }}"
+          release_version="${tag_name#v}"
+
+          echo "MODWIRE_RELEASE_VERSION=$release_version" >> "$GITHUB_ENV"
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION_FOR_MODWIRE=$release_version" >> "$GITHUB_ENV"
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
-      - name: Set up PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: "8.3"
-
       - name: Clean packaging artifacts
         run: rm -rf .dev build dist src/*.egg-info
 
@@ -93,11 +92,6 @@ jobs:
       - name: Run tests
         run: python -m pytest
 
-      - name: Validate extractor syntax
-        run: |
-          node --check src/modwire/extractors/scripts/typescript_extractor.js
-          php -l src/modwire/extractors/scripts/php_extractor.php
-
       - name: Build distributions
         run: python -m build --outdir dist
 
@@ -105,12 +99,13 @@ jobs:
         if: github.event_name == 'release'
         run: |
           python - <<'PY'
+          import os
           import sys
           import zipfile
           from email.parser import Parser
           from pathlib import Path
 
-          expected_version = "${{ github.event.release.tag_name }}".removeprefix("v")
+          expected_version = os.environ["MODWIRE_RELEASE_VERSION"]
           wheels = sorted(Path("dist").glob("*.whl"))
           versions: dict[str, str] = {}
 

modwire-3.1.1/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 3.0.0 - Unreleased
+
+### Breaking Changes
+
+- Replaced the previous function-style public API with an OOP-first architecture
+  reporting API.
+- Removed legacy helper entry points documented by older releases, including
+  `evaluate_shape`, `render_callable_report`, `structured_callable_report`,
+  `find_unused_exports`, `map_code`, `find_hotspots`, and `coherence_summary`.
+- Consolidated architecture mapping, flow violations, shape violations, and
+  insights into `ArchitectureReportRunner`.
+
+### Added
+
+- `ArchitectureReportRunner`, returning a typed `ArchitectureReport`.
+- Normalized report sections for map data, violations, and insights.
+- Public exports for the configuration objects needed to build reports from
+  `modwire.architecture`.
+
+### Migration
+
+Use `ArchitectureReportRunner(config).run(code_map)` instead of calling
+individual helper functions:
+
+```python
+from modwire.architecture import ArchitectureConfig, ArchitectureReportRunner
+
+report = ArchitectureReportRunner(ArchitectureConfig(language="python")).run(code_map)
+```

{modwire-2.3.0 → modwire-3.1.1}/CONTRIBUTING.md

@@ -1,15 +1,14 @@
 # Contributing to Modwire
 
-Modwire is a Python package for extracting source-code dependencies and
-evaluating architecture rules across Python, TypeScript/JavaScript, and PHP
-projects.
+Modwire is a Python package for architecture mapping, violation evaluation, and
+code-map reports produced from `modwire-extraction` data.
 
 ## 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
+- architecture mapping for another framework convention
+- richer architecture analysis, shape reports, callable reports, or export checks
 - new architecture analyzers or policy matching behavior
 - export formats or integrations with other tools
 - documentation examples for common workflows
@@ -21,22 +20,18 @@ solved, a small example input, and the desired API or output shape.
 
 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
+- incorrect shape, callable, unused-export, or graph reports
 - 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.
+actual output, and relevant versions for Python, Modwire, and modwire-extraction.
 
 ## 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-3.1.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: modwire
+Version: 3.1.1
+Summary: Map architecture boundaries and analyze extracted code maps.
+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: copier>=9.16.0
+Requires-Dist: modwire-extraction>=1.0.1
+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` turns code maps from
+[`modwire-extraction`](https://github.com/9orky/modwire-extraction) into
+architecture reports: boundary maps, dependency-flow violations, shape-policy
+violations, and architecture insights.
+
+## Installation
+
+```bash
+python -m pip install modwire
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from modwire.architecture import (
+    ArchitectureConfig,
+    ArchitectureReportRunner,
+    BoundariesConfig,
+    FlowRealm,
+    FlowRules,
+    ShapeConfig,
+    TagRule,
+)
+from modwire_extraction import ModwireExtraction
+
+code_map = ModwireExtraction(Path("src")).generate_map("python")
+
+config = ArchitectureConfig(
+    language="python",
+    boundaries=BoundariesConfig(
+        tags=(
+            TagRule(name="module", match="features/*"),
+            TagRule(name="ui", match="features/*/ui"),
+            TagRule(name="domain", match="features/*/domain"),
+        ),
+        flow=FlowRules(
+            module_tag="module",
+            realms=(
+                FlowRealm(
+                    name="feature",
+                    layers=("domain", "ui"),
+                ),
+            ),
+        ),
+    ),
+    shape=ShapeConfig(
+        max_functions_per_file=8,
+        max_methods_per_class=12,
+        allow_import_aliases=False,
+    ),
+)
+
+report = ArchitectureReportRunner(config).run(code_map)
+
+print(report.map.modules)
+print(report.violations.flow.violations)
+print(report.violations.shape.violations)
+print(report.insights.hotspots[:5])
+```
+
+## Report Sections
+
+`ArchitectureReportRunner` returns a typed `ArchitectureReport` with three
+top-level sections:
+
+- `map`: normalized module and layer groupings plus unknown files
+- `violations`: dependency-flow and shape-policy violations
+- `insights`: clusters, hotspots, dependency coherence, callable graph, and
+  unused exports
+
+Reports are Pydantic models, so they can be serialized with `model_dump()` or
+`model_dump_json()`.
+
+```python
+payload = report.model_dump(mode="json")
+```
+
+## Module Generation
+
+`modwire.modules` can generate a module from any Copier template. A caller only
+needs to create a normal Copier template directory and pass it to
+`generate_module`.
+
+```python
+from pathlib import Path
+
+from modwire.modules import generate_module
+
+generate_module(
+    "billing",
+    Path("src/features"),
+    Path("templates/modwire-module"),
+    data={"service_name": "BillingService"},
+)
+```
+
+If no template path is provided, `generate_module` uses the bundled `layered`
+scaffolding. Bundled scaffoldings are packaged with the distribution wheel.
+
+## Configuration
+
+Boundary tags classify source IDs. Flow rules then use those tags to detect
+backward dependencies, module cycles, and module re-entry.
+
+```python
+from modwire.architecture import BoundariesConfig, FlowRules, TagRule
+
+boundaries = BoundariesConfig(
+    tags=(
+        TagRule(name="module", match="features/*"),
+        TagRule(name="api", match="features/*/api"),
+        TagRule(name="domain", match="features/*/domain"),
+    ),
+    flow=FlowRules(
+        module_tag="module",
+        layers=("domain", "api"),
+    ),
+)
+```
+
+Shape limits are disabled with `-1` and enabled with non-negative integers.
+
+```python
+from modwire.architecture import ShapeConfig
+
+shape = ShapeConfig(
+    max_classes_per_file=3,
+    max_function_lines=40,
+    require_joined_imports=True,
+)
+```
+
+## Migration
+
+The current API is intentionally OOP-first. Older helper functions such as
+`evaluate_shape`, `render_callable_report`, `structured_callable_report`,
+`find_unused_exports`, `map_code`, `find_hotspots`, and
+`coherence_summary` have been replaced by `ArchitectureReportRunner`.
+
+See [CHANGELOG.md](CHANGELOG.md) before publishing or upgrading across the next
+major release.
+
+## 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 architecture analyzers, output formats, or
+  integrations.
+- Open a bug report for incorrect architecture violations, graph output, shape
+  reports, callable reports, unused export reports, packaging problems, or
+  documentation mismatches.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the information to include and the
+checks to run before opening a pull request.

modwire-3.1.1/README.md

@@ -0,0 +1,163 @@
+# modwire
+
+`modwire` turns code maps from
+[`modwire-extraction`](https://github.com/9orky/modwire-extraction) into
+architecture reports: boundary maps, dependency-flow violations, shape-policy
+violations, and architecture insights.
+
+## Installation
+
+```bash
+python -m pip install modwire
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from modwire.architecture import (
+    ArchitectureConfig,
+    ArchitectureReportRunner,
+    BoundariesConfig,
+    FlowRealm,
+    FlowRules,
+    ShapeConfig,
+    TagRule,
+)
+from modwire_extraction import ModwireExtraction
+
+code_map = ModwireExtraction(Path("src")).generate_map("python")
+
+config = ArchitectureConfig(
+    language="python",
+    boundaries=BoundariesConfig(
+        tags=(
+            TagRule(name="module", match="features/*"),
+            TagRule(name="ui", match="features/*/ui"),
+            TagRule(name="domain", match="features/*/domain"),
+        ),
+        flow=FlowRules(
+            module_tag="module",
+            realms=(
+                FlowRealm(
+                    name="feature",
+                    layers=("domain", "ui"),
+                ),
+            ),
+        ),
+    ),
+    shape=ShapeConfig(
+        max_functions_per_file=8,
+        max_methods_per_class=12,
+        allow_import_aliases=False,
+    ),
+)
+
+report = ArchitectureReportRunner(config).run(code_map)
+
+print(report.map.modules)
+print(report.violations.flow.violations)
+print(report.violations.shape.violations)
+print(report.insights.hotspots[:5])
+```
+
+## Report Sections
+
+`ArchitectureReportRunner` returns a typed `ArchitectureReport` with three
+top-level sections:
+
+- `map`: normalized module and layer groupings plus unknown files
+- `violations`: dependency-flow and shape-policy violations
+- `insights`: clusters, hotspots, dependency coherence, callable graph, and
+  unused exports
+
+Reports are Pydantic models, so they can be serialized with `model_dump()` or
+`model_dump_json()`.
+
+```python
+payload = report.model_dump(mode="json")
+```
+
+## Module Generation
+
+`modwire.modules` can generate a module from any Copier template. A caller only
+needs to create a normal Copier template directory and pass it to
+`generate_module`.
+
+```python
+from pathlib import Path
+
+from modwire.modules import generate_module
+
+generate_module(
+    "billing",
+    Path("src/features"),
+    Path("templates/modwire-module"),
+    data={"service_name": "BillingService"},
+)
+```
+
+If no template path is provided, `generate_module` uses the bundled `layered`
+scaffolding. Bundled scaffoldings are packaged with the distribution wheel.
+
+## Configuration
+
+Boundary tags classify source IDs. Flow rules then use those tags to detect
+backward dependencies, module cycles, and module re-entry.
+
+```python
+from modwire.architecture import BoundariesConfig, FlowRules, TagRule
+
+boundaries = BoundariesConfig(
+    tags=(
+        TagRule(name="module", match="features/*"),
+        TagRule(name="api", match="features/*/api"),
+        TagRule(name="domain", match="features/*/domain"),
+    ),
+    flow=FlowRules(
+        module_tag="module",
+        layers=("domain", "api"),
+    ),
+)
+```
+
+Shape limits are disabled with `-1` and enabled with non-negative integers.
+
+```python
+from modwire.architecture import ShapeConfig
+
+shape = ShapeConfig(
+    max_classes_per_file=3,
+    max_function_lines=40,
+    require_joined_imports=True,
+)
+```
+
+## Migration
+
+The current API is intentionally OOP-first. Older helper functions such as
+`evaluate_shape`, `render_callable_report`, `structured_callable_report`,
+`find_unused_exports`, `map_code`, `find_hotspots`, and
+`coherence_summary` have been replaced by `ArchitectureReportRunner`.
+
+See [CHANGELOG.md](CHANGELOG.md) before publishing or upgrading across the next
+major release.
+
+## 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 architecture analyzers, output formats, or
+  integrations.
+- Open a bug report for incorrect architecture violations, graph output, shape
+  reports, callable reports, unused export reports, packaging problems, or
+  documentation mismatches.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the information to include and the
+checks to run before opening a pull request.

modwire-3.1.1/docs/wiki/Development-checks.md

@@ -0,0 +1,18 @@
+# Development Checks
+
+Run these checks before opening a pull request:
+
+```bash
+uv run ruff check .
+uv run --with pytest python -m pytest
+uv run --with build python -m build --outdir dist
+uv run --with twine python -m twine check dist/*
+```
+
+This page is the canonical local-check list; README and contributor guidance
+link here to avoid release-process drift.
+
+The CI workflow currently validates:
+
+- Python 3.11, 3.12, and 3.13
+- package build and distribution metadata

modwire-3.1.1/docs/wiki/Home.md

@@ -0,0 +1,25 @@
+# Modwire Wiki
+
+Modwire maps architecture boundaries and evaluates policies from code maps
+produced by `modwire-extraction`.
+
+## Start Here
+
+- README examples cover the OOP architecture report runner, including boundary
+  maps, flow violations, shape violations, callable insights, hotspots, and
+  unused export checks.
+- [Reporting bugs](Reporting-bugs.md)
+- [Requesting features](Requesting-features.md)
+- [Development checks](Development-checks.md)
+
+## Useful Project Links
+
+- Repository: https://github.com/9orky/modwire
+- Issues: https://github.com/9orky/modwire/issues
+- Bug report form: https://github.com/9orky/modwire/issues/new?template=bug_report.yml
+- Feature request form: https://github.com/9orky/modwire/issues/new?template=feature_request.yml
+
+## Code Maps
+
+Use `modwire-extraction` to produce `CodeMap` objects. Pass those maps into
+`ArchitectureReportRunner` to produce a full architecture report.

{modwire-2.3.0 → modwire-3.1.1}/docs/wiki/Reporting-bugs.md

@@ -5,20 +5,18 @@ Use the GitHub `Bug report` issue form when Modwire behaves incorrectly.
 ## Good Bug Reports Include
 
 - a short summary of what went wrong
-- the affected area, such as an extractor, dependency graph, or architecture
-  analyzer
+- the affected area, such as architecture mapping, dependency graph reporting,
+  shape policy, callable reports, or unused exports
 - the smallest source snippet or fixture that reproduces the problem
 - the actual output, traceback, graph edges, or violations
 - the expected output
-- Modwire, Python, Node.js, PHP, and operating-system versions where relevant
+- Modwire, modwire-extraction, Python, and operating-system versions where relevant
 
 ## Examples of Bugs
 
-- an import is missed or linked to the wrong source ID
-- a symbol is extracted with incorrect metadata
 - graph edges are missing, duplicated, or pointed at the wrong node
-- an architecture policy reports the wrong violation
-- extraction crashes on valid Python, TypeScript/JavaScript, or PHP source
+- an architecture policy returns the wrong violation
+- shape, callable, or unused-export reports omit or misclassify source metadata
 - package installation or distribution metadata is broken
 
 Open a bug report at: