modwire 8.0.0__tar.gz → 9.0.0__tar.gz

{modwire-8.0.0 → modwire-9.0.0}/.dev/modwire.egg-info/SOURCES.txt

@@ -10,75 +10,8 @@ setup.py
 uv.lock
 .github/workflows/ci.yml
 .github/workflows/release.yml
-.modwire/architecture.yaml
-docs/legacy/architecture/CHANGELOG.md
-docs/legacy/architecture/CONTRIBUTING.md
-docs/legacy/architecture/LICENSE
-docs/legacy/architecture/MANIFEST.in
-docs/legacy/architecture/Makefile
-docs/legacy/architecture/README.md
-docs/legacy/architecture/pyproject.toml
-docs/legacy/architecture/.github/workflows/ci.yml
-docs/legacy/architecture/.github/workflows/human-approval.yml
-docs/legacy/architecture/.github/workflows/issue-metadata-check.yml
-docs/legacy/architecture/.github/workflows/issue-metadata.yml
-docs/legacy/architecture/.github/workflows/python-package.yml
-docs/legacy/architecture/.github/workflows/python-release-assets.yml
-docs/legacy/architecture/.github/workflows/python-release-build.yml
-docs/legacy/architecture/.github/workflows/release.yml
-docs/legacy/architecture/.modwire/boundaries.yaml
-docs/legacy/architecture/.modwire/shape.yaml
-docs/legacy/architecture/docs/migration-5.md
-docs/legacy/architecture/docs/migration-6.md
-docs/legacy/architecture/docs/scaffolding/repository-contract-v1.yaml
-docs/legacy/architecture/docs/scaffolding/golden/cli.yaml
-docs/legacy/architecture/docs/scaffolding/golden/library.yaml
-docs/legacy/architecture/docs/wiki/Development-checks.md
-docs/legacy/architecture/docs/wiki/Home.md
-docs/legacy/architecture/docs/wiki/Reporting-bugs.md
-docs/legacy/architecture/docs/wiki/Requesting-features.md
-docs/legacy/cli/AGENTS.md
-docs/legacy/cli/LICENSE
-docs/legacy/cli/Makefile
-docs/legacy/cli/README.md
-docs/legacy/cli/pyproject.toml
-docs/legacy/cli/.github/workflows/ci.yml
-docs/legacy/cli/.github/workflows/release.yml
-docs/legacy/cli/.modwire/INDEX.md
-docs/legacy/cli/.modwire/architecture.yaml
-docs/legacy/cli/.modwire/docs/ARCHITECTURE.md
-docs/legacy/cli/.modwire/docs/MODWIRE.md
-docs/legacy/cli/.modwire/docs/PROJECT.md
-docs/legacy/cli/.modwire/docs/RULES.md
-docs/legacy/cli/.modwire/docs/TESTING.md
-docs/legacy/cli/.modwire/docs/WORKFLOW.md
-docs/legacy/extraction/CHANGELOG.md
-docs/legacy/extraction/CONTRIBUTING.md
-docs/legacy/extraction/LICENSE
-docs/legacy/extraction/MANIFEST.in
-docs/legacy/extraction/Makefile
-docs/legacy/extraction/README.md
-docs/legacy/extraction/RELEASE_CHECKLIST.md
-docs/legacy/extraction/pyproject.toml
-docs/legacy/extraction/.github/workflows/ci.yml
-docs/legacy/extraction/.github/workflows/human-approval.yml
-docs/legacy/extraction/.github/workflows/release.yml
-docs/legacy/extraction/docs/migration-2.md
-docs/planning/baselines.json
-docs/planning/issues.json
-docs/planning/namespace-migration.md
-docs/planning/preflight.md
-docs/planning/removed-modules.json
-docs/planning/report-model-migration.json
-docs/planning/source-imports.json
-docs/planning/diagrams/01-ownership.md
-docs/planning/diagrams/01-ownership.snapshot.json
-docs/planning/diagrams/02-issue-dependencies.md
-docs/planning/diagrams/02-issue-dependencies.snapshot.json
-docs/planning/diagrams/03-release-gates.md
-docs/planning/diagrams/03-release-gates.snapshot.json
-docs/planning/diagrams/README.md
-docs/planning/diagrams/manifest.json
+docs/target-language-ownership.md
+scripts/check_extractors.py
 scripts/generate_docs.py
 scripts/verify_consumer.py
 src/modwire/__init__.py
@@ -181,8 +114,6 @@ src/modwire/cli/__init__.py
 src/modwire/cli/facade.py
 src/modwire/cli/documentation/__init__.py
 src/modwire/cli/documentation/application.py
-src/modwire/cli/documentation/models/__init__.py
-src/modwire/cli/documentation/models/defaults.py
 src/modwire/cli/documentation/services/__init__.py
 src/modwire/cli/documentation/services/documentation_generator.py
 src/modwire/cli/initialization/__init__.py
@@ -200,6 +131,7 @@ src/modwire/cli/pipeline/models/extractor_batch_input.py
 src/modwire/cli/pipeline/models/extractor_command_input.py
 src/modwire/cli/pipeline/models/extractor_source_input.py
 src/modwire/cli/pipeline/models/report_pipeline_context.py
+src/modwire/cli/pipeline/models/scan_policy.py
 src/modwire/cli/pipeline/services/__init__.py
 src/modwire/cli/pipeline/services/batch_source_reader.py
 src/modwire/cli/pipeline/services/callables_insight.py
@@ -218,20 +150,6 @@ src/modwire/cli/pipeline/services/unknown_files_warning.py
 src/modwire/cli/pipeline/services/unused_exports_insight.py
 src/modwire/cli/resources/__init__.py
 src/modwire/cli/resources/application.py
-src/modwire/cli/resources/extractors/__init__.py
-src/modwire/cli/resources/extractors/php/build.php
-src/modwire/cli/resources/extractors/php/composer.json
-src/modwire/cli/resources/extractors/php/composer.lock
-src/modwire/cli/resources/extractors/php/script.php
-src/modwire/cli/resources/extractors/php/script.src.php
-src/modwire/cli/resources/extractors/python/__init__.py
-src/modwire/cli/resources/extractors/python/script.py
-src/modwire/cli/resources/extractors/typescript/build.mjs
-src/modwire/cli/resources/extractors/typescript/package-lock.json
-src/modwire/cli/resources/extractors/typescript/package.json
-src/modwire/cli/resources/extractors/typescript/script.js
-src/modwire/cli/resources/extractors/typescript/script.ts
-src/modwire/cli/resources/extractors/typescript/tsconfig.json
 src/modwire/cli/resources/models/__init__.py
 src/modwire/cli/resources/models/defaults.py
 src/modwire/cli/resources/models/init_asset.py
@@ -251,14 +169,32 @@ src/modwire/extraction/dependency/domain.py
 src/modwire/extraction/dependency/services/__init__.py
 src/modwire/extraction/dependency/services/graph_builder.py
 src/modwire/extraction/dependency/services/import_resolver.py
+src/modwire/extraction/dependency/services/suffix_index.py
 src/modwire/extraction/extractors/__init__.py
 src/modwire/extraction/extractors/application.py
 src/modwire/extraction/extractors/domain.py
 src/modwire/extraction/extractors/models/__init__.py
 src/modwire/extraction/extractors/models/batch_config.py
 src/modwire/extraction/extractors/models/extraction_request.py
+src/modwire/extraction/extractors/models/extractor_resource.py
 src/modwire/extraction/extractors/models/extractor_runtime.py
 src/modwire/extraction/extractors/models/python_call_context.py
+src/modwire/extraction/extractors/resources/__init__.py
+src/modwire/extraction/extractors/resources/php/build.php
+src/modwire/extraction/extractors/resources/php/build.py
+src/modwire/extraction/extractors/resources/php/composer.json
+src/modwire/extraction/extractors/resources/php/composer.lock
+src/modwire/extraction/extractors/resources/php/script.php
+src/modwire/extraction/extractors/resources/php/script.src.php
+src/modwire/extraction/extractors/resources/python/__init__.py
+src/modwire/extraction/extractors/resources/python/script.py
+src/modwire/extraction/extractors/resources/typescript/build.mjs
+src/modwire/extraction/extractors/resources/typescript/build.py
+src/modwire/extraction/extractors/resources/typescript/package-lock.json
+src/modwire/extraction/extractors/resources/typescript/package.json
+src/modwire/extraction/extractors/resources/typescript/script.js
+src/modwire/extraction/extractors/resources/typescript/script.ts
+src/modwire/extraction/extractors/resources/typescript/tsconfig.json
 src/modwire/extraction/extractors/services/__init__.py
 src/modwire/extraction/extractors/services/php_extractor.py
 src/modwire/extraction/extractors/services/python_call_reader.py
@@ -359,12 +295,22 @@ tests/cli/pipeline/test_05_recovery.py
 tests/cli/pipeline/test_06_happy_path.py
 tests/extraction/__init__.py
 tests/extraction/base_test.py
+tests/extraction/big_projects/__init__.py
+tests/extraction/big_projects/project.py
+tests/extraction/big_projects/projects.json
+tests/extraction/big_projects/resolution_results.json
+tests/extraction/big_projects/results.json
+tests/extraction/big_projects/run.py
 tests/extraction/dependency/__init__.py
 tests/extraction/dependency/test_02_invariants.py
 tests/extraction/extractors/__init__.py
 tests/extraction/extractors/test_01_attacks.py
 tests/extraction/extractors/test_02_invariants.py
 tests/extraction/extractors/test_03_native_symbols.py
+tests/extraction/scan_benchmark/__init__.py
+tests/extraction/scan_benchmark/prepare.py
+tests/extraction/scan_benchmark/results.json
+tests/extraction/scan_benchmark/run.py
 tests/fixtures/languages/php/ignored/example_generated.php
 tests/fixtures/languages/php/src/example_application/example_actions/example_action.php
 tests/fixtures/languages/php/src/example_domain/example_model/example_record.php
@@ -392,4 +338,5 @@ tests/shared/code/__init__.py
 tests/shared/code/test_02_invariants.py
 tests/support/__init__.py
 tests/support/base_test.py
+tests/support/code_map.py
 tests/support/service_test.py

{modwire-8.0.0 → modwire-9.0.0}/.github/workflows/ci.yml

@@ -10,8 +10,8 @@ permissions:
   contents: read
 
 jobs:
-  verify:
-    name: Python ${{ matrix.python-version }}
+  package:
+    name: Package on Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -26,20 +26,11 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - run: python -m pip install uv
       - run: uv sync --all-groups --locked
-      - run: make python-ci
+      - run: make host-check
 
-  native-extractors:
-    name: Native extractors
+  extractors:
+    name: Extractor resources
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: "24"
-          cache: npm
-          cache-dependency-path: src/modwire/cli/resources/extractors/typescript/package-lock.json
-      - uses: shivammathur/setup-php@v2
-        with:
-          php-version: "8.4"
-          tools: composer
-      - run: make native-check
+      - run: make extractor-check

{modwire-8.0.0 → modwire-9.0.0}/MANIFEST.in

@@ -2,8 +2,6 @@ include LICENSE
 include README.md
 recursive-include src *.py *.typed *.php *.js *.mjs *.ts *.json *.lock *.md *.yaml
 recursive-include tests *.py *.json *.ts *.tsx *.js *.jsx *.php
-recursive-include docs *.md *.yaml *.json
-recursive-include .modwire *.yaml *.md
 recursive-include scripts *.py
 prune verification
 prune .dev

modwire-9.0.0/Makefile

@@ -0,0 +1,55 @@
+DEV_DIR := .dev
+BUILD_DIR := $(DEV_DIR)/build
+DIST_DIR := $(DEV_DIR)/dist
+EGG_INFO_DIR := src/modwire.egg-info
+PROJECT_ROOT := $(CURDIR)
+
+export PYTHONPYCACHEPREFIX := $(PROJECT_ROOT)/$(DEV_DIR)/cache/python
+export UV_CACHE_DIR := $(PROJECT_ROOT)/$(DEV_DIR)/cache/uv
+
+.PHONY: big-projects build ci docs docs-check extractor-check format format-check host-check lint package-check scan-benchmark scan-benchmark-fixture test type-check
+
+format:
+	uv run ruff format src tests scripts
+
+format-check:
+	uv run ruff format --check src tests scripts
+
+lint:
+	uv run ruff check src tests scripts
+
+type-check:
+	uv run pyright src/modwire
+
+test:
+	mkdir -p $(DEV_DIR)/testing
+	uv run pytest
+
+big-projects:
+	uv run python -m tests.extraction.big_projects.run
+
+scan-benchmark-fixture:
+	uv run python -m tests.extraction.scan_benchmark.prepare --root .dev/benchmarks/scan-project --source-template "$(SCAN_BENCHMARK_SOURCE)"
+
+scan-benchmark:
+	uv run python -m tests.extraction.scan_benchmark.run --root .dev/benchmarks/scan-project --language "$(SCAN_BENCHMARK_LANGUAGE)" --excluded-pattern 'example_excluded/**'
+
+docs-check:
+	uv run python scripts/generate_docs.py --check
+
+docs:
+	uv run python scripts/generate_docs.py
+
+build:
+	rm -rf $(BUILD_DIR) $(DIST_DIR) $(EGG_INFO_DIR)
+	uv build --out-dir $(DIST_DIR)
+
+package-check: build
+	uv run twine check $(DIST_DIR)/*
+
+extractor-check:
+	python3 scripts/check_extractors.py
+
+host-check: format-check lint type-check test docs-check package-check
+
+ci: host-check extractor-check

modwire-9.0.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: modwire
+Version: 9.0.0
+Summary: Code extraction, architecture analysis and the Modwire CLI.
+Author: Tomasz Szpak
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/szpak-dev/modwire
+Project-URL: Repository, https://github.com/szpak-dev/modwire
+Project-URL: Issues, https://github.com/szpak-dev/modwire/issues
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.12
+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.16,>=0.14; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# Modwire
+
+## `ModwireApplication`
+
+Public entry point for source discovery, extraction, architecture analysis, and the Modwire CLI.
+
+### `create`
+
+Create an isolated application with all services resolved through Wireup.
+
+### `configure`
+
+Validate architecture configuration values.
+
+### `catalog`
+
+Return the available architecture reports.
+
+### `analyze`
+
+Analyze a code map with a validated architecture configuration.
+
+### `discover`
+
+Discover supported source languages beneath a root using the caller's scan policy.
+
+### `generate_map`
+
+Extract one language and return its code map with honest scan metrics.
+
+``files_excluded`` counts only source files encountered and excluded directly.
+``directories_pruned`` counts directories rejected before descent; their
+descendants are deliberately unobserved and are not included in file counts.
+
+### `generate_queryable_map`
+
+Extract source files and return a queryable code map.
+
+### `load_configuration`
+
+Load and validate an architecture configuration from a directory.
+
+### `initialize`
+
+Create project-local Modwire configuration and agent guidance.
+
+### `generate_documentation`
+
+Generate this README from the published interface docstrings, or check that it is current.
+
+### `run_extractor`
+
+Run the native extractor transport for one supported language.
+
+### `run`
+
+Run the Modwire command line interface and return its process status.
+
+## `ScanPolicy`
+
+Caller-owned filesystem traversal policy with explicit exclusions and opt-in symlink following.

modwire-9.0.0/README.md

@@ -0,0 +1,61 @@
+# Modwire
+
+## `ModwireApplication`
+
+Public entry point for source discovery, extraction, architecture analysis, and the Modwire CLI.
+
+### `create`
+
+Create an isolated application with all services resolved through Wireup.
+
+### `configure`
+
+Validate architecture configuration values.
+
+### `catalog`
+
+Return the available architecture reports.
+
+### `analyze`
+
+Analyze a code map with a validated architecture configuration.
+
+### `discover`
+
+Discover supported source languages beneath a root using the caller's scan policy.
+
+### `generate_map`
+
+Extract one language and return its code map with honest scan metrics.
+
+``files_excluded`` counts only source files encountered and excluded directly.
+``directories_pruned`` counts directories rejected before descent; their
+descendants are deliberately unobserved and are not included in file counts.
+
+### `generate_queryable_map`
+
+Extract source files and return a queryable code map.
+
+### `load_configuration`
+
+Load and validate an architecture configuration from a directory.
+
+### `initialize`
+
+Create project-local Modwire configuration and agent guidance.
+
+### `generate_documentation`
+
+Generate this README from the published interface docstrings, or check that it is current.
+
+### `run_extractor`
+
+Run the native extractor transport for one supported language.
+
+### `run`
+
+Run the Modwire command line interface and return its process status.
+
+## `ScanPolicy`
+
+Caller-owned filesystem traversal policy with explicit exclusions and opt-in symlink following.

modwire-9.0.0/docs/target-language-ownership.md

@@ -0,0 +1,34 @@
+# Target-language ownership
+
+Modwire is hosted and distributed as a Python package. References to Python versions, Python packaging, type checking,
+and Python-based development commands are host concerns rather than analyzed-language behavior.
+
+All analyzed-language facts belong to extractor-owned locations:
+
+- `src/modwire/extraction/extractors/services/` owns extractor registration, target identity, file extensions, runtime
+  commands, parser selection, and batch policy.
+- `src/modwire/extraction/extractors/resources/` owns parser programs, dependency manifests, generated executables,
+  and build adapters.
+- `tests/fixtures/languages/` and extractor integration tests own language-specific validation inputs.
+- `tests/extraction/big_projects/projects.json` owns pinned language-specific production fixtures.
+
+Shared code, dependency resolution, architecture analysis, traversal, consumer verification, benchmarks, and CI
+orchestration must not contain supported-language tables, runtime commands, extension tables, or language-selection
+branches. Callers select a registered extractor explicitly.
+
+## Shared contract version 2
+
+The class-level `CodeMap.schema_version` is `2` while the existing serialized envelope remains stable. Callable kinds
+are `function`, `instance_method`, `type_method`, `static_method`,
+`constructor`, `callable_value`, and `anonymous`. Parameter kinds are `positional`, `variadic_positional`,
+`named_only`, and `variadic_named`.
+
+Version 1 serialized maps used extractor-specific callable and parameter vocabulary. They are not accepted as version
+2 values. Regenerate them from their source with the same registered extractor; persistent reuse does not yet exist,
+so there is no cache migration or silent compatibility alias.
+
+## Adding an extractor
+
+Add one automatic Wireup `SourceExtractor` registration, its extractor-owned resources and optional `build.py`
+adapter, and extractor integration fixtures. Package data and the generic build runner discover those resources without
+changes to shared services, CLI traversal, architecture analysis, the top-level Makefile, or CI orchestration.

{modwire-8.0.0 → modwire-9.0.0}/pyproject.toml

@@ -43,7 +43,11 @@ exclude = ["*.__pycache__", "*.__pycache__.*"]
 
 [tool.setuptools.package-data]
 "modwire" = ["py.typed"]
-"modwire.cli.resources" = ["templates/*", "extractors/php/*", "extractors/typescript/*", "extractors/python/*.py"]
+"modwire.cli.resources" = ["templates/*"]
+"modwire.extraction.extractors.resources" = ["**/*"]
+
+[tool.setuptools.exclude-package-data]
+"*" = ["**/__pycache__/*", "**/*.pyc"]
 
 [tool.setuptools_scm]
 tag_regex = '^v(?P<version>\d+\.\d+\.\d+)$'

modwire-9.0.0/scripts/check_extractors.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import importlib.util
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+from types import ModuleType
+
+
+def load_adapter(path: Path) -> ModuleType:
+    spec = importlib.util.spec_from_file_location(f"modwire_extractor_build_{path.parent.name}", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Cannot load extractor build adapter: {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def main() -> int:
+    repository = Path(__file__).resolve().parents[1]
+    resources = repository / "src/modwire/extraction/extractors/resources"
+    work_root = repository / ".dev/native"
+    adapters = tuple(sorted(resources.glob("*/build.py")))
+    if not adapters:
+        raise RuntimeError(f"No extractor build adapters found beneath: {resources}")
+    for path in adapters:
+        work = work_root / path.parent.name
+        shutil.rmtree(work, ignore_errors=True)
+        adapter = getattr(load_adapter(path), "BuildAdapter", None)
+        check = getattr(adapter, "check", None)
+        if not callable(check):
+            raise RuntimeError(f"Extractor build adapter has no BuildAdapter.check method: {path}")
+        typed_check: Callable[[Path, Path], None] = check
+        typed_check(path.parent, work)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{modwire-8.0.0 → modwire-9.0.0}/scripts/verify_consumer.py

@@ -1,9 +1,10 @@
+import argparse
 import sys
 
 from wireup import create_sync_container, injectable
 from wireup.errors import UnknownServiceRequestedError
 
-from modwire.application import ModwireApplication
+from modwire.application import ModwireApplication, ScanPolicy
 
 
 @injectable
@@ -24,9 +25,14 @@ try:
 finally:
     container.close()
 
+parser = argparse.ArgumentParser()
+parser.add_argument("root")
+parser.add_argument("--language", required=True)
+arguments = parser.parse_args()
+
 application = ModwireApplication.create()
 config = application.configure({"shape": {"realms": [{"name": "example-source", "match": "src"}]}})
-code_map = application.generate_queryable_map("python", sys.argv[1], ())
+code_map = application.generate_queryable_map(arguments.language, arguments.root, ScanPolicy())
 reports = application.analyze(code_map, config)
 assert code_map.files().count() == 1
 assert len(reports) == 4

{modwire-8.0.0 → modwire-9.0.0}/src/modwire/application.py

@@ -11,19 +11,26 @@ from .architecture.facade import ArchitectureFacade
 from .architecture.report.models.report_catalog import ReportCatalog
 from .architecture.report.models.report_node import ReportNode
 from .cli.facade import CliFacade
+from .cli.pipeline.models.scan_policy import ScanPolicy
 from .extraction.facade import ExtractionFacade
 from .shared.code.models.code_map import CodeMap
 from .shared.code.models.queryable_code_map import QueryableCodeMap
 
+__all__ = ["CodeMap", "ModwireApplication", "QueryableCodeMap", "ScanPolicy"]
+
 
 @dataclass(frozen=True)
 class ModwireApplication:
+    """Public entry point for source discovery, extraction, architecture analysis, and the Modwire CLI."""
+
     architecture: ArchitectureFacade
     cli: CliFacade
     extraction: ExtractionFacade
 
     @classmethod
     def create(cls) -> Self:
+        """Create an isolated application with all services resolved through Wireup."""
+
         container = create_sync_container(injectables=[modwire])
         try:
             return cls(
@@ -35,43 +42,66 @@ class ModwireApplication:
             container.close()
 
     def configure(self, values: Mapping[str, object]) -> ArchitectureConfig:
+        """Validate architecture configuration values."""
+
         return self.architecture.configure(values)
 
     def catalog(self) -> ReportCatalog:
+        """Return the available architecture reports."""
+
         return self.architecture.catalog()
 
     def analyze(self, code_map: QueryableCodeMap, config: ArchitectureConfig) -> tuple[ReportNode, ...]:
+        """Analyze a code map with a validated architecture configuration."""
+
         return self.architecture.analyze(code_map, config)
 
-    def discover(self, root: str, excluded_patterns: tuple[str, ...]) -> tuple[str, ...]:
+    def discover(self, root: str, policy: ScanPolicy) -> tuple[str, ...]:
+        """Discover supported source languages beneath a root using the caller's scan policy."""
+
         return tuple(
             language
             for language in self.extraction.supported_languages()
-            if self.cli.has_source_files(
-                self.extraction.request(language, str(root)).model_copy(update={"excluded_patterns": excluded_patterns})
-            )
+            if self.cli.has_source_files(self.extraction.request(language, str(root)), policy)
         )
 
-    def generate_map(self, language: str, root: str, excluded_patterns: tuple[str, ...]) -> CodeMap:
-        request = self.extraction.request(language, str(root)).model_copy(
-            update={"excluded_patterns": excluded_patterns}
-        )
-        return self.extraction.generate_map(language, self.cli.extract(request))
+    def generate_map(self, language: str, root: str, policy: ScanPolicy) -> CodeMap:
+        """Extract one language and return its code map with honest scan metrics.
 
-    def generate_queryable_map(self, language: str, root: str, excluded_patterns: tuple[str, ...]) -> QueryableCodeMap:
-        return QueryableCodeMap(code_map=self.generate_map(language, root, excluded_patterns))
+        ``files_excluded`` counts only source files encountered and excluded directly.
+        ``directories_pruned`` counts directories rejected before descent; their
+        descendants are deliberately unobserved and are not included in file counts.
+        """
+
+        request = self.extraction.request(language, str(root))
+        return self.extraction.generate_map(language, self.cli.extract(request, policy))
+
+    def generate_queryable_map(self, language: str, root: str, policy: ScanPolicy) -> QueryableCodeMap:
+        """Extract source files and return a queryable code map."""
+
+        return QueryableCodeMap(code_map=self.generate_map(language, root, policy))
 
     def load_configuration(self, dot_dir: str) -> ArchitectureConfig:
+        """Load and validate an architecture configuration from a directory."""
+
         return self.cli.load_configuration(str(dot_dir))
 
     def initialize(self, root: str, dot_dir: str, force: bool) -> int:
+        """Create project-local Modwire configuration and agent guidance."""
+
         return self.cli.initialize(str(root), str(dot_dir), force)
 
     def generate_documentation(self, readme: str, check: bool) -> int:
-        return self.cli.generate_documentation(str(readme), check)
+        """Generate this README from the published interface docstrings, or check that it is current."""
+
+        return self.cli.generate_documentation(str(readme), (type(self), ScanPolicy), check)
 
     def run_extractor(self, language: str) -> int:
+        """Run the native extractor transport for one supported language."""
+
         return self.cli.run_extractor(language)
 
     def run(self, argv: Sequence[str]) -> int:
+        """Run the Modwire command line interface and return its process status."""
+
         return self.cli.run(argv)

{modwire-8.0.0 → modwire-9.0.0}/src/modwire/cli/documentation/application.py

@@ -11,8 +11,8 @@ from .services.documentation_generator import DocumentationGenerator
 class DocumentationApplication:
     generator: DocumentationGenerator
 
-    def generate(self, readme: Path, check: bool) -> int:
-        if self.generator.update(readme, check):
+    def generate(self, readme: Path, public_interfaces: tuple[type[object], ...], check: bool) -> int:
+        if self.generator.update(readme, public_interfaces, check):
             return 0
         if check:
             print("Generated documentation is stale. Run `make docs` and commit the result.")