modwire-cli 1.1.0__tar.gz → 1.2.0__tar.gz

modwire_cli-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    uses: modwire/modwire-architecture/.github/workflows/python-package.yml@workflows-v1
+    with:
+      python-versions: '["3.12", "3.13", "3.14"]'
+      build-python-version: "3.12"

modwire_cli-1.2.0/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    uses: modwire/modwire-architecture/.github/workflows/python-release-build.yml@workflows-v1
+    with:
+      release-tag: ${{ github.event.release.tag_name }}
+      python-version: "3.12"
+
+  publish-github-assets:
+    needs: build
+    uses: modwire/modwire-architecture/.github/workflows/python-release-assets.yml@workflows-v1
+    with:
+      release-tag: ${{ github.event.release.tag_name }}
+    permissions:
+      contents: write
+
+  publish-pypi:
+    needs: [build, publish-github-assets]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/modwire-cli/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

{modwire_cli-1.1.0 → modwire_cli-1.2.0}/.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 *.py[cod]
 dist/
 src/modwire_cli/_version.py
+*egg*

modwire_cli-1.2.0/.modwire/INDEX.md

@@ -0,0 +1,10 @@
+# Modwire
+
+Modwire keeps software changes aligned with a project's architecture, working rules, testing expectations, and delivery workflow.
+
+- [Architecture configuration](docs/ARCHITECTURE.md)
+- [Quality loop](docs/MODWIRE.md)
+- [Project](docs/PROJECT.md)
+- [Working rules](docs/RULES.md)
+- [Testing](docs/TESTING.md)
+- [GitHub workflow](docs/WORKFLOW.md)

modwire_cli-1.2.0/.modwire/architecture.yaml

@@ -0,0 +1,38 @@
+boundaries:
+  tags:
+    - name: package
+      match: src/modwire_cli
+    - name: tests
+      match: tests
+    - name: scripts
+      match: scripts
+  flow:
+    module_tag: package
+    realms:
+      - name: tests
+        module_tag: tests
+      - name: scripts
+        module_tag: scripts
+    analyzers:
+      - module-boundaries
+      - no-cycles
+      - no-reentry
+shape:
+  max_classes_per_file: 1
+  max_interfaces_per_file: 0
+  max_types_per_file: 0
+  max_abstract_classes_per_file: -1
+  max_functions_per_file: 0
+  max_methods_per_class: -1
+  max_declared_args: -1
+  max_function_lines: -1
+  max_method_lines: -1
+  max_class_lines: -1
+  allow_optional_function_args: false
+  allow_optional_method_args: false
+  allow_optional_class_properties: false
+  allow_import_aliases: false
+  require_joined_imports: true
+  allowed_import_crossing_types:
+    - module
+    - symbol

modwire_cli-1.2.0/.modwire/docs/ARCHITECTURE.md

@@ -0,0 +1,34 @@
+# Architecture configuration
+
+`architecture.yaml` describes the source-tree boundaries and structural limits that Modwire checks. Adapt its paths and names before enforcing it in a project.
+
+## Tags
+
+Each tag gives a source-tree pattern a meaningful name. The example uses compact YAML mappings to keep the relationship visible:
+
+```yaml
+tags:
+  - {name: &module_tag module, match: src/*}
+  - {name: &shared_tag shared, match: src/shared}
+```
+
+`&module_tag` anchors the scalar value `module`; `*module_tag` inserts that same string elsewhere in the file. This avoids repeating tag names:
+
+```yaml
+rules:
+  - {source: *module_tag, disallow: [*module_tag], allow: [*shared_tag], allow_same_match: true}
+```
+
+Anchor the `name` value, not the whole tag object. Rule `source` and `allow` fields, and flow `module_tag` and `layers` fields, accept tag-name strings rather than `{name, match}` objects.
+
+## Rules and flow
+
+Rules describe which tagged modules may depend on one another. Flow groups tags into a module realm and, when needed, orders its layers:
+
+```yaml
+flow:
+  realms:
+    - {name: backend, module_tag: *backend_module_tag, layers: [*api_tag, *application_tag, *infrastructure_tag, *domain_tag]}
+```
+
+Use aliases consistently when a tag name appears in more than one place. The supplied `architecture.yaml` is a complete, adaptable example; keep its shape limits only when they suit the project.

modwire_cli-1.2.0/.modwire/docs/MODWIRE.md

@@ -0,0 +1,5 @@
+# Quality loop
+
+1. Run `modwire report --language <language>` before changing code.
+2. Make the smallest coherent change.
+3. Run the report again and resolve violations before review.

modwire_cli-1.2.0/.modwire/docs/PROJECT.md

@@ -0,0 +1,16 @@
+# modwire-cli
+
+Python 3.12+ CLI for Modwire architecture reports.
+
+## Structure
+
+- `__main__.py`: argument parsing and dependency-container lifecycle.
+- `facade.py`: load config, extract code, request reports, run the output pipeline.
+- `pipeline/steps/`: independently rendered report sections, ordered by Wireup qualifiers.
+- `.modwire/architecture.yaml`: strict `ArchitectureConfig` input; unknown fields must remain invalid.
+
+## Working rules
+
+- Preserve `modwire --language <language>` report behavior unless a change explicitly replaces it.
+- Keep CLI options at the boundary; put behavior in injected services/facades.
+- Add subprocess-level coverage for every user-facing command in `tests/test_cli.py`.

modwire_cli-1.2.0/.modwire/docs/RULES.md

@@ -0,0 +1,6 @@
+# Working rules
+
+- Use comments only as docstrings that document public API classes or functions.
+- Keep documentation focused on its readers' tasks; do not generate internal implementation inventories for end users.
+- When running local CLI commands, use host mode or an execution mode with privileges equivalent to the user's.
+- Read the local guidance before changing code.

modwire_cli-1.2.0/.modwire/docs/TESTING.md

@@ -0,0 +1,7 @@
+# Testing
+
+If a local Modwire MCP tool is available, consult it first for project-specific testing rules.
+
+Test only public interfaces and assert observable outcomes such as returned values, exit codes, output, or files.
+
+Write scenarios in Auntie order: attacks, invariants, interruption, cleanup, recovery, then happy paths.

modwire_cli-1.2.0/.modwire/docs/WORKFLOW.md

@@ -0,0 +1,8 @@
+# GitHub workflow
+
+1. Start with both the local and remote workspaces clean and with only the `main` branch.
+2. Make changes only in the local workspace, under user supervision.
+3. The user may create multiple local checkpoint commits while the work is in progress.
+4. Before pushing the feature branch, squash all of its current commits into one commit with a clear, appropriate message.
+5. Submit a pull request. It becomes ready to merge only after its QA checks succeed.
+6. After the user merges the pull request, clean up both workspaces so that only the `main` branch remains.

modwire_cli-1.2.0/AGENTS.md

@@ -0,0 +1 @@
+Check `.modwire/INDEX.md` before making changes.

modwire_cli-1.2.0/Makefile

@@ -0,0 +1,14 @@
+.PHONY: docs docs-check verify
+
+check:
+	uv run modwire --language python --summary
+
+docs:
+	uv run python scripts/generate_docs.py
+
+docs-check:
+	uv run python scripts/generate_docs.py --check
+
+verify: docs-check
+	uv run ruff check .
+	uv run pytest

{modwire_cli-1.1.0 → modwire_cli-1.2.0}/PKG-INFO

@@ -1,17 +1,15 @@
 Metadata-Version: 2.4
 Name: modwire-cli
-Version: 1.1.0
+Version: 1.2.0
 Summary: Command-line interface for the Modwire ecosystem.
+Author: Tomasz Szpak
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/modwire/modwire-cli
 Project-URL: Repository, https://github.com/modwire/modwire-cli
 Project-URL: Issues, https://github.com/modwire/modwire-cli/issues
-Author: Tomasz Szpak
-License-Expression: MIT
-License-File: LICENSE
 Keywords: cli,modwire
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
@@ -21,17 +19,19 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: modwire-architecture<7,>=6
 Requires-Dist: modwire-extraction<3,>=2
 Requires-Dist: pydantic-yaml>=1.7
 Requires-Dist: rich>=13
 Requires-Dist: wireup>=2.12.0
 Provides-Extra: dev
-Requires-Dist: build>=1.3; extra == 'dev'
-Requires-Dist: pytest>=9; extra == 'dev'
-Requires-Dist: ruff>=0.14; extra == 'dev'
-Requires-Dist: twine>=6; extra == 'dev'
-Description-Content-Type: text/markdown
+Requires-Dist: build>=1.3; extra == "dev"
+Requires-Dist: pytest>=9; extra == "dev"
+Requires-Dist: ruff>=0.14; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
 
 # modwire-cli
 
@@ -46,28 +46,51 @@ pip install modwire-cli
 ## Usage
 
 ```sh
-modwire --language python
+modwire init
+modwire report --language python
 ```
 
 By default, Modwire reads its configuration from `.modwire/architecture.yaml`
 and analyses the current directory. Override either path when needed:
 
 ```sh
-modwire --language typescript --dot-dir path/to/.modwire --architecture-root path/to/source
+modwire report --language typescript --dot-dir path/to/.modwire --architecture-root path/to/source
 ```
 
 Use `--summary` for a compact module → layer map that omits individual source files:
 
 ```sh
-modwire --language python --summary
+modwire report --language python --summary
+```
+
+The original option-only command remains supported for existing automation:
+
+```sh
+modwire --language python
 ```
 
 To check this repository's architecture:
 
 ```sh
-uv run modwire --language python
+uv run modwire report --language python
 ```
 
+<!-- generated:public-api:start -->
+## Command reference
+
+Provide `modwire init` for setup and `modwire report` for architecture feedback.
+
+Existing `modwire --language <language>` automation continues to run reports.
+
+| Command | Purpose |
+| --- | --- |
+| `modwire init` | Create `.modwire/` guidance and a strict architecture template. |
+| `modwire report --language <language>` | Analyse the configured project and render violations. |
+| `modwire --language <language>` | Backwards-compatible form of `report`. |
+
+Use `--summary` with `report` to render module-to-layer membership without files.
+<!-- generated:public-api:end -->
+
 ## Development
 
 ```sh
@@ -76,3 +99,10 @@ uv run pytest
 uv run ruff check .
 uv build
 ```
+
+The README command reference is generated from the public CLI docstring:
+
+```sh
+make docs
+make verify
+```

modwire_cli-1.2.0/README.md

@@ -0,0 +1,73 @@
+# modwire-cli
+
+The command-line interface for the Modwire ecosystem.
+
+## Install
+
+```sh
+pip install modwire-cli
+```
+
+## Usage
+
+```sh
+modwire init
+modwire report --language python
+```
+
+By default, Modwire reads its configuration from `.modwire/architecture.yaml`
+and analyses the current directory. Override either path when needed:
+
+```sh
+modwire report --language typescript --dot-dir path/to/.modwire --architecture-root path/to/source
+```
+
+Use `--summary` for a compact module → layer map that omits individual source files:
+
+```sh
+modwire report --language python --summary
+```
+
+The original option-only command remains supported for existing automation:
+
+```sh
+modwire --language python
+```
+
+To check this repository's architecture:
+
+```sh
+uv run modwire report --language python
+```
+
+<!-- generated:public-api:start -->
+## Command reference
+
+Provide `modwire init` for setup and `modwire report` for architecture feedback.
+
+Existing `modwire --language <language>` automation continues to run reports.
+
+| Command | Purpose |
+| --- | --- |
+| `modwire init` | Create `.modwire/` guidance and a strict architecture template. |
+| `modwire report --language <language>` | Analyse the configured project and render violations. |
+| `modwire --language <language>` | Backwards-compatible form of `report`. |
+
+Use `--summary` with `report` to render module-to-layer membership without files.
+<!-- generated:public-api:end -->
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run pytest
+uv run ruff check .
+uv build
+```
+
+The README command reference is generated from the public CLI docstring:
+
+```sh
+make docs
+make verify
+```

{modwire_cli-1.1.0 → modwire_cli-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
-requires = ["hatchling>=1.28", "hatch-vcs>=0.5"]
-build-backend = "hatchling.build"
+requires = ["setuptools>=77", "setuptools-scm[toml]>=8", "wheel"]
+build-backend = "setuptools.build_meta"
 
 [project]
 name = "modwire-cli"
@@ -13,7 +13,6 @@ authors = [{ name = "Tomasz Szpak" }]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
@@ -33,7 +32,7 @@ dependencies = [
 ]
 
 [project.scripts]
-modwire = "modwire_cli.__main__:main"
+modwire = "modwire_cli.cli:main"
 
 [project.optional-dependencies]
 dev = [
@@ -56,19 +55,21 @@ dev = [
     "twine>=6",
 ]
 
-[tool.hatch.version]
-source = "vcs"
-tag-pattern = '^v(?P<version>\d+\.\d+\.\d+)$'
-fallback-version = "0.0.0"
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
 
-[tool.hatch.build.hooks.vcs]
-version-file = "src/modwire_cli/_version.py"
+[tool.setuptools.packages.find]
+where = ["src"]
 
-[tool.hatch.build.targets.wheel]
-packages = ["src/modwire_cli"]
+[tool.setuptools.package-data]
+"modwire_cli" = ["py.typed", "resources/init/*"]
 
-[tool.hatch.build.targets.sdist]
-include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+[tool.setuptools_scm]
+tag_regex = '^v(?P<version>\d+\.\d+\.\d+)$'
+fallback_version = "0.0.0.dev0"
+local_scheme = "no-local-version"
+version_file = "src/modwire_cli/_version.py"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

modwire_cli-1.2.0/scripts/generate_docs.py

@@ -0,0 +1,4 @@
+from modwire_cli.documentation import DocumentationCommand
+
+if __name__ == "__main__":
+    raise SystemExit(DocumentationCommand().run())

modwire_cli-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

modwire_cli-1.2.0/src/modwire_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{modwire_cli-1.1.0 → modwire_cli-1.2.0}/src/modwire_cli/_version.py

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

modwire_cli-1.2.0/src/modwire_cli/cli.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from rich.console import Console
+from wireup import create_sync_container, instance
+
+import modwire_cli
+
+from .facade import FitnessFacade
+from .initialization import InitializationFacade
+
+
+class CommandLine:
+    """Provide `modwire init` for setup and `modwire report` for architecture feedback.
+
+    Existing `modwire --language <language>` automation continues to run reports.
+    """
+
+    def __call__(self) -> int:
+        """Run the command supplied by the process argument vector."""
+        return self.run(sys.argv[1:])
+
+    def run(self, argv: Sequence[str]) -> int:
+        """Run one command and return its shell-compatible status code."""
+        arguments = self._parser().parse_args(self._legacy_report_arguments(argv))
+        container = create_sync_container(injectables=[modwire_cli, instance(Console(), as_type=Console)])
+        try:
+            if arguments.command == "init":
+                return container.get(InitializationFacade).initialize(Path.cwd(), arguments.dot_dir, arguments.force)
+            return container.get(FitnessFacade).reports(
+                arguments.dot_dir,
+                arguments.architecture_root,
+                arguments.language,
+                arguments.summary,
+            )
+        finally:
+            container.close()
+
+    @staticmethod
+    def _parser() -> argparse.ArgumentParser:
+        parser = argparse.ArgumentParser()
+        commands = parser.add_subparsers(dest="command", required=True)
+        init = commands.add_parser("init", help="Create project-local Modwire configuration.")
+        init.add_argument("--dot-dir", type=Path, default=Path(".modwire"))
+        init.add_argument("--force", action="store_true", help="Replace existing generated assets.")
+        report = commands.add_parser("report", help="Run architecture reports.")
+        report.add_argument("--dot-dir", type=Path, default=Path(".modwire"))
+        report.add_argument("--architecture-root", type=Path, default=Path("."))
+        report.add_argument("--language", required=True)
+        report.add_argument("--summary", action="store_true", help="Render modules without individual files.")
+        return parser
+
+    @staticmethod
+    def _legacy_report_arguments(argv: Sequence[str]) -> Sequence[str]:
+        command_names = {"init", "report", "-h", "--help"}
+        return ("report", *argv) if argv and argv[0] not in command_names else argv
+
+
+main = CommandLine()

{modwire_cli-1.1.0 → modwire_cli-1.2.0}/src/modwire_cli/config.py

@@ -11,5 +11,7 @@ from wireup import injectable
 @injectable
 @dataclass(frozen=True)
 class ConfigService:
+    """Load validated architecture configuration from the project dot directory."""
+
     def load(self, dot_dir: Path) -> ArchitectureConfig:
         return parse_yaml_file_as(ArchitectureConfig, dot_dir / "architecture.yaml")

modwire_cli-1.2.0/src/modwire_cli/documentation/__init__.py

@@ -0,0 +1,4 @@
+from .command import DocumentationCommand
+from .generator import DocumentationGenerator
+
+__all__ = ["DocumentationCommand", "DocumentationGenerator"]

modwire_cli-1.2.0/src/modwire_cli/documentation/command.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .generator import DocumentationGenerator
+
+
+class DocumentationCommand:
+    """Update or validate the generated README class reference."""
+
+    def run(self) -> int:
+        """Run the documentation command from the process argument vector."""
+        parser = argparse.ArgumentParser(description="Generate README class reference documentation.")
+        parser.add_argument("--check", action="store_true", help="Fail instead of updating stale documentation.")
+        arguments = parser.parse_args()
+        readme = Path(__file__).parents[3] / "README.md"
+        if DocumentationGenerator().update(readme, arguments.check):
+            return 0
+        if arguments.check:
+            print("Generated documentation is stale. Run `make docs` and commit the result.")
+            return 1
+        return 0

modwire_cli-1.2.0/src/modwire_cli/documentation/generator.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from inspect import cleandoc
+from pathlib import Path
+
+from ..cli import CommandLine
+
+START = "<!-- generated:public-api:start -->"
+END = "<!-- generated:public-api:end -->"
+
+
+class DocumentationGenerator:
+    """Render a concise README command reference from the public CLI docstring."""
+
+    def render(self) -> str:
+        """Render the marked README section for people using the CLI."""
+        return "\n".join(
+            (
+                START,
+                "## Command reference",
+                "",
+                cleandoc(CommandLine.__doc__ or ""),
+                "",
+                "| Command | Purpose |",
+                "| --- | --- |",
+                "| `modwire init` | Create `.modwire/` guidance and a strict architecture template. |",
+                "| `modwire report --language <language>` | Analyse the configured project and render violations. |",
+                "| `modwire --language <language>` | Backwards-compatible form of `report`. |",
+                "",
+                "Use `--summary` with `report` to render module-to-layer membership without files.",
+                END,
+            )
+        )
+
+    def update(self, readme: Path, check: bool) -> bool:
+        """Update the README section, or report whether it is current."""
+        current = readme.read_text(encoding="utf-8")
+        if START not in current or END not in current:
+            raise ValueError(f"Missing generated documentation markers in {readme}")
+        prefix, remainder = current.split(START, 1)
+        _, suffix = remainder.split(END, 1)
+        expected = f"{prefix}{self.render()}{suffix}"
+        if current == expected:
+            return True
+        if not check:
+            readme.write_text(expected, encoding="utf-8")
+        return False

{modwire_cli-1.1.0 → modwire_cli-1.2.0}/src/modwire_cli/extraction.py

@@ -10,5 +10,7 @@ from wireup import injectable
 @injectable
 @dataclass(frozen=True)
 class ExtractionService:
+    """Extract a queryable code map for one source root and language."""
+
     def load(self, architecture_root: Path, language: str) -> QueryableCodeMap:
         return ModwireExtraction(architecture_root).generate_queryable_map(language)

{modwire_cli-1.1.0 → modwire_cli-1.2.0}/src/modwire_cli/facade.py

@@ -14,6 +14,8 @@ from .pipeline.runner import ReportPipelineRunner
 @injectable
 @dataclass(frozen=True)
 class FitnessFacade:
+    """Coordinate configuration, extraction, reporting, and report rendering."""
+
     config_service: ConfigService
     extraction_service: ExtractionService
     pipeline_runner: ReportPipelineRunner
@@ -23,7 +25,7 @@ class FitnessFacade:
         dot_dir: Path,
         architecture_root: Path,
         language: str,
-        summary: bool = False,
+        summary: bool,
     ) -> int:
         config = self.config_service.load(dot_dir)
         code_map = self.extraction_service.load(architecture_root, language)