modwire 11.1.0__tar.gz → 12.0.0__tar.gz

{modwire-11.1.0 → modwire-12.0.0}/.dev/modwire.egg-info/SOURCES.txt

@@ -30,10 +30,12 @@ src/modwire/architecture/boundaries/__init__.py
 src/modwire/architecture/boundaries/application.py
 src/modwire/architecture/boundaries/domain.py
 src/modwire/architecture/boundaries/models/__init__.py
+src/modwire/architecture/boundaries/models/architecture_error.py
 src/modwire/architecture/boundaries/models/edge_rule_violation.py
 src/modwire/architecture/boundaries/models/flow_report.py
 src/modwire/architecture/boundaries/models/flow_violation.py
 src/modwire/architecture/boundaries/models/types.py
+src/modwire/architecture/boundaries/models/unknown_flow_analyzer_error.py
 src/modwire/architecture/boundaries/services/__init__.py
 src/modwire/architecture/boundaries/services/backward_flow_analyzer.py
 src/modwire/architecture/boundaries/services/boundaries_flow_analyzer.py
@@ -121,11 +123,14 @@ src/modwire/cli/cache/__init__.py
 src/modwire/cli/cache/application.py
 src/modwire/cli/cache/domain.py
 src/modwire/cli/cache/models/__init__.py
+src/modwire/cli/cache/models/cache_access_error.py
 src/modwire/cli/cache/models/cache_entry.py
+src/modwire/cli/cache/models/cache_error.py
 src/modwire/cli/cache/models/cache_key.py
 src/modwire/cli/cache/models/cache_kind.py
 src/modwire/cli/cache/models/cache_options.py
 src/modwire/cli/cache/models/cache_outcome.py
+src/modwire/cli/cache/models/cache_ownership_error.py
 src/modwire/cli/cache/models/cache_plan.py
 src/modwire/cli/cache/models/cache_stage.py
 src/modwire/cli/cache/models/cache_storage_state.py
@@ -142,7 +147,9 @@ src/modwire/cli/documentation/services/documentation_generator.py
 src/modwire/cli/initialization/__init__.py
 src/modwire/cli/initialization/application.py
 src/modwire/cli/initialization/models/__init__.py
+src/modwire/cli/initialization/models/initialization_error.py
 src/modwire/cli/initialization/models/initialization_result.py
+src/modwire/cli/initialization/models/invalid_initialization_target_error.py
 src/modwire/cli/initialization/services/__init__.py
 src/modwire/cli/initialization/services/initialization_service.py
 src/modwire/cli/pipeline/__init__.py
@@ -157,10 +164,18 @@ src/modwire/cli/pipeline/models/command_name.py
 src/modwire/cli/pipeline/models/command_request.py
 src/modwire/cli/pipeline/models/extractor_batch_input.py
 src/modwire/cli/pipeline/models/extractor_command_input.py
+src/modwire/cli/pipeline/models/extractor_contract_error.py
+src/modwire/cli/pipeline/models/extractor_contract_violation.py
+src/modwire/cli/pipeline/models/extractor_execution_error.py
+src/modwire/cli/pipeline/models/extractor_resource_error.py
 src/modwire/cli/pipeline/models/extractor_source_input.py
+src/modwire/cli/pipeline/models/extractor_unavailable_error.py
+src/modwire/cli/pipeline/models/invalid_source_root_error.py
 src/modwire/cli/pipeline/models/report_pipeline_context.py
+src/modwire/cli/pipeline/models/source_access_error.py
 src/modwire/cli/pipeline/models/source_entry.py
 src/modwire/cli/pipeline/models/source_observation.py
+src/modwire/cli/pipeline/models/source_observation_invalidated_error.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
@@ -211,11 +226,16 @@ 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/batch_output_format.py
+src/modwire/extraction/extractors/models/duplicate_identity_error.py
+src/modwire/extraction/extractors/models/extraction_error.py
 src/modwire/extraction/extractors/models/extraction_request.py
+src/modwire/extraction/extractors/models/extractor_error.py
 src/modwire/extraction/extractors/models/extractor_resource.py
 src/modwire/extraction/extractors/models/extractor_runtime.py
 src/modwire/extraction/extractors/models/parsed_source_batch.py
 src/modwire/extraction/extractors/models/parsed_source_file.py
+src/modwire/extraction/extractors/models/unsupported_language_error.py
+src/modwire/extraction/extractors/models/unsupported_parser_error.py
 src/modwire/extraction/extractors/php/__init__.py
 src/modwire/extraction/extractors/php/extractor.py
 src/modwire/extraction/extractors/python/__init__.py
@@ -327,6 +347,8 @@ src/modwire/implementation/manifest/contracts/manifest_serializer.py
 src/modwire/implementation/manifest/models/__init__.py
 src/modwire/implementation/manifest/models/implementation_manifest.py
 src/modwire/implementation/manifest/models/implementation_manifest_document.py
+src/modwire/implementation/manifest/models/implementation_manifest_error.py
+src/modwire/implementation/manifest/models/invalid_implementation_manifest_error.py
 src/modwire/implementation/manifest/models/manifest_annotation.py
 src/modwire/implementation/manifest/models/manifest_annotation_role.py
 src/modwire/implementation/manifest/models/manifest_attribute.py
@@ -339,6 +361,7 @@ src/modwire/implementation/manifest/models/manifest_parameter.py
 src/modwire/implementation/manifest/models/manifest_span.py
 src/modwire/implementation/manifest/models/manifest_symbol.py
 src/modwire/implementation/manifest/models/manifest_symbol_kind.py
+src/modwire/implementation/manifest/models/unsupported_manifest_format_error.py
 src/modwire/implementation/manifest/services/__init__.py
 src/modwire/implementation/manifest/services/canonical_json_manifest_serializer.py
 src/modwire/implementation/manifest/services/code_map_manifest_compiler.py
@@ -358,7 +381,6 @@ src/modwire/shared/code/models/dependency_edge_result.py
 src/modwire/shared/code/models/dependency_graph.py
 src/modwire/shared/code/models/dependency_node_result.py
 src/modwire/shared/code/models/digest_algorithm.py
-src/modwire/shared/code/models/duplicate_identity_error.py
 src/modwire/shared/code/models/edge.py
 src/modwire/shared/code/models/extractor_descriptor.py
 src/modwire/shared/code/models/fact_capability.py
@@ -415,6 +437,9 @@ src/modwire/shared/code/services/__init__.py
 src/modwire/shared/code/services/glob_path_matcher.py
 src/modwire/shared/code/services/identity_resolver.py
 src/modwire/shared/code/services/installed_package_version.py
+src/modwire/shared/failures/__init__.py
+src/modwire/shared/failures/models/__init__.py
+src/modwire/shared/failures/models/modwire_error.py
 src/modwire/shared/values/__init__.py
 src/modwire/shared/values/models/__init__.py
 src/modwire/shared/values/models/value_model.py
@@ -422,6 +447,7 @@ tests/__init__.py
 tests/conftest.py
 tests/application/__init__.py
 tests/application/base_test.py
+tests/application/failure_consumer.py
 tests/application/test_01_attacks.py
 tests/application/test_06_happy_path.py
 tests/application/test_07_cache.py

{modwire-11.1.0 → modwire-12.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modwire
-Version: 11.1.0
+Version: 12.0.0
 Summary: Code extraction, architecture analysis and the Modwire CLI.
 Author: Tomasz Szpak
 License-Expression: MIT
@@ -347,3 +347,103 @@ Declared completeness of an extractor's support for a fact family.
 ## `CapabilityCoverage`
 
 An extractor's explicit support status for one implementation fact family.
+
+## `ModwireError`
+
+Base class for every expected failure exposed by Modwire.
+
+## `ArchitectureError`
+
+Base class for architecture configuration and analysis failures.
+
+## `UnknownFlowAnalyzerError`
+
+Report a configured flow analyzer that is not registered.
+
+## `CacheError`
+
+Base class for persistent-cache ownership and access failures.
+
+## `CacheOwnershipError`
+
+Report a cache path that cannot be safely used by Modwire.
+
+## `CacheAccessError`
+
+Report an operating-system failure while accessing persistent cache state.
+
+## `ExtractionError`
+
+Base class for failures while discovering, extracting, or parsing source code.
+
+## `UnsupportedLanguageError`
+
+Report a language for which no source extractor is registered.
+
+## `UnsupportedParserError`
+
+Report a language for which no in-process source parser is registered.
+
+## `InvalidSourceRootError`
+
+Report a requested source root that is not a directory.
+
+## `SourceAccessError`
+
+Report an operating-system failure while reading a source tree.
+
+## `SourceObservationInvalidatedError`
+
+Report exact source identities that changed after their observation.
+
+## `DuplicateIdentityError`
+
+Report two source files that claim the same extracted identity.
+
+### `as_dict`
+
+Return stable machine-readable evidence for the duplicate identity.
+
+## `ExtractorError`
+
+Base class for failures at a native extractor boundary.
+
+## `ExtractorUnavailableError`
+
+Report a required extractor executable that is unavailable on PATH.
+
+## `ExtractorResourceError`
+
+Report a missing or unreadable packaged extractor resource.
+
+## `ExtractorExecutionError`
+
+Report a native extractor process that exited unsuccessfully.
+
+## `ExtractorContractError`
+
+Report extractor output that violates the registered runtime contract.
+
+## `ExtractorContractViolation`
+
+Identify the extractor contract clause violated by runtime output.
+
+## `ImplementationManifestError`
+
+Base class for implementation-manifest contract failures.
+
+## `UnsupportedManifestFormatError`
+
+Report an implementation-manifest format with no matching serializer.
+
+## `InvalidImplementationManifestError`
+
+Report a manifest document or serializer that violates its declared format contract.
+
+## `InitializationError`
+
+Base class for project initialization failures.
+
+## `InvalidInitializationTargetError`
+
+Report an initialization target outside the accepted project boundary.

{modwire-11.1.0 → modwire-12.0.0}/README.md

@@ -319,3 +319,103 @@ Declared completeness of an extractor's support for a fact family.
 ## `CapabilityCoverage`
 
 An extractor's explicit support status for one implementation fact family.
+
+## `ModwireError`
+
+Base class for every expected failure exposed by Modwire.
+
+## `ArchitectureError`
+
+Base class for architecture configuration and analysis failures.
+
+## `UnknownFlowAnalyzerError`
+
+Report a configured flow analyzer that is not registered.
+
+## `CacheError`
+
+Base class for persistent-cache ownership and access failures.
+
+## `CacheOwnershipError`
+
+Report a cache path that cannot be safely used by Modwire.
+
+## `CacheAccessError`
+
+Report an operating-system failure while accessing persistent cache state.
+
+## `ExtractionError`
+
+Base class for failures while discovering, extracting, or parsing source code.
+
+## `UnsupportedLanguageError`
+
+Report a language for which no source extractor is registered.
+
+## `UnsupportedParserError`
+
+Report a language for which no in-process source parser is registered.
+
+## `InvalidSourceRootError`
+
+Report a requested source root that is not a directory.
+
+## `SourceAccessError`
+
+Report an operating-system failure while reading a source tree.
+
+## `SourceObservationInvalidatedError`
+
+Report exact source identities that changed after their observation.
+
+## `DuplicateIdentityError`
+
+Report two source files that claim the same extracted identity.
+
+### `as_dict`
+
+Return stable machine-readable evidence for the duplicate identity.
+
+## `ExtractorError`
+
+Base class for failures at a native extractor boundary.
+
+## `ExtractorUnavailableError`
+
+Report a required extractor executable that is unavailable on PATH.
+
+## `ExtractorResourceError`
+
+Report a missing or unreadable packaged extractor resource.
+
+## `ExtractorExecutionError`
+
+Report a native extractor process that exited unsuccessfully.
+
+## `ExtractorContractError`
+
+Report extractor output that violates the registered runtime contract.
+
+## `ExtractorContractViolation`
+
+Identify the extractor contract clause violated by runtime output.
+
+## `ImplementationManifestError`
+
+Base class for implementation-manifest contract failures.
+
+## `UnsupportedManifestFormatError`
+
+Report an implementation-manifest format with no matching serializer.
+
+## `InvalidImplementationManifestError`
+
+Report a manifest document or serializer that violates its declared format contract.
+
+## `InitializationError`
+
+Base class for project initialization failures.
+
+## `InvalidInitializationTargetError`
+
+Report an initialization target outside the accepted project boundary.

{modwire-11.1.0 → modwire-12.0.0}/src/modwire/application.py

@@ -6,21 +6,44 @@ from wireup import create_sync_container
 
 import modwire
 
+from .architecture.boundaries.models.architecture_error import ArchitectureError
+from .architecture.boundaries.models.unknown_flow_analyzer_error import UnknownFlowAnalyzerError
 from .architecture.config.models.architecture_config import ArchitectureConfig
 from .architecture.facade import ArchitectureFacade
 from .architecture.report.models.report_catalog import ReportCatalog
 from .architecture.report.models.report_node import ReportNode
+from .cli.cache.models.cache_access_error import CacheAccessError
+from .cli.cache.models.cache_error import CacheError
 from .cli.cache.models.cache_options import CacheOptions
 from .cli.cache.models.cache_outcome import CacheOutcome
+from .cli.cache.models.cache_ownership_error import CacheOwnershipError
 from .cli.cache.models.cache_stage import CacheStage
 from .cli.cache.models.cached_result import CachedResult
 from .cli.facade import CliFacade
+from .cli.initialization.models.initialization_error import InitializationError
+from .cli.initialization.models.invalid_initialization_target_error import InvalidInitializationTargetError
+from .cli.pipeline.models.extractor_contract_error import ExtractorContractError
+from .cli.pipeline.models.extractor_contract_violation import ExtractorContractViolation
+from .cli.pipeline.models.extractor_execution_error import ExtractorExecutionError
+from .cli.pipeline.models.extractor_resource_error import ExtractorResourceError
+from .cli.pipeline.models.extractor_unavailable_error import ExtractorUnavailableError
+from .cli.pipeline.models.invalid_source_root_error import InvalidSourceRootError
+from .cli.pipeline.models.source_access_error import SourceAccessError
 from .cli.pipeline.models.source_observation import SourceObservation
+from .cli.pipeline.models.source_observation_invalidated_error import SourceObservationInvalidatedError
+from .extraction.extractors.models.duplicate_identity_error import DuplicateIdentityError
+from .extraction.extractors.models.extraction_error import ExtractionError
+from .extraction.extractors.models.extractor_error import ExtractorError
+from .extraction.extractors.models.unsupported_language_error import UnsupportedLanguageError
+from .extraction.extractors.models.unsupported_parser_error import UnsupportedParserError
 from .extraction.facade import ExtractionFacade
 from .implementation.facade import ImplementationFacade
 from .implementation.manifest.models.implementation_manifest import ImplementationManifest
 from .implementation.manifest.models.implementation_manifest_document import ImplementationManifestDocument
+from .implementation.manifest.models.implementation_manifest_error import ImplementationManifestError
+from .implementation.manifest.models.invalid_implementation_manifest_error import InvalidImplementationManifestError
 from .implementation.manifest.models.manifest_format import ManifestFormat
+from .implementation.manifest.models.unsupported_manifest_format_error import UnsupportedManifestFormatError
 from .shared.code.models.capability_coverage import CapabilityCoverage
 from .shared.code.models.capability_status import CapabilityStatus
 from .shared.code.models.code_map import CodeMap
@@ -35,10 +58,15 @@ from .shared.code.models.source_assigned_value_kind import SourceAssignedValueKi
 from .shared.code.models.source_manifest_identity import SourceManifestIdentity
 from .shared.code.models.source_member_kind import SourceMemberKind
 from .shared.code.models.source_relation_kind import SourceRelationKind
+from .shared.failures.models.modwire_error import ModwireError
 
 __all__ = [
+    "ArchitectureError",
+    "CacheAccessError",
+    "CacheError",
     "CacheOptions",
     "CacheOutcome",
+    "CacheOwnershipError",
     "CacheStage",
     "CachedResult",
     "CodeMap",
@@ -47,19 +75,39 @@ __all__ = [
     "DeclarationFamily",
     "DeclarationIdentity",
     "DigestAlgorithm",
+    "DuplicateIdentityError",
+    "ExtractionError",
+    "ExtractorContractError",
+    "ExtractorContractViolation",
+    "ExtractorError",
+    "ExtractorExecutionError",
+    "ExtractorResourceError",
+    "ExtractorUnavailableError",
     "FactCapability",
     "ImplementationManifest",
     "ImplementationManifestDocument",
+    "ImplementationManifestError",
+    "InitializationError",
+    "InvalidImplementationManifestError",
+    "InvalidInitializationTargetError",
+    "InvalidSourceRootError",
     "ManifestFormat",
+    "ModwireError",
     "ModwireApplication",
     "QueryableCodeMap",
     "ScanPolicy",
     "SourceAssignedValue",
     "SourceAssignedValueKind",
+    "SourceAccessError",
     "SourceMemberKind",
     "SourceManifestIdentity",
     "SourceObservation",
+    "SourceObservationInvalidatedError",
     "SourceRelationKind",
+    "UnknownFlowAnalyzerError",
+    "UnsupportedLanguageError",
+    "UnsupportedManifestFormatError",
+    "UnsupportedParserError",
 ]
 
 
@@ -170,6 +218,7 @@ class ModwireApplication:
         """Return a cached code map derived from the exact supplied source observation."""
 
         request = observation.request
+        self.cli.validate_observation(observation)
         plan = self.cli.prepare_cache(observation)
         cached = self.cli.cached_code_map(plan, options)
         outcome = cached.outcome(CacheStage.CODE_MAP)
@@ -287,6 +336,30 @@ class ModwireApplication:
                 FactCapability,
                 CapabilityStatus,
                 CapabilityCoverage,
+                ModwireError,
+                ArchitectureError,
+                UnknownFlowAnalyzerError,
+                CacheError,
+                CacheOwnershipError,
+                CacheAccessError,
+                ExtractionError,
+                UnsupportedLanguageError,
+                UnsupportedParserError,
+                InvalidSourceRootError,
+                SourceAccessError,
+                SourceObservationInvalidatedError,
+                DuplicateIdentityError,
+                ExtractorError,
+                ExtractorUnavailableError,
+                ExtractorResourceError,
+                ExtractorExecutionError,
+                ExtractorContractError,
+                ExtractorContractViolation,
+                ImplementationManifestError,
+                UnsupportedManifestFormatError,
+                InvalidImplementationManifestError,
+                InitializationError,
+                InvalidInitializationTargetError,
             ),
             check,
         )

modwire-12.0.0/src/modwire/architecture/boundaries/models/architecture_error.py

@@ -0,0 +1,7 @@
+from ....shared.failures.models.modwire_error import ModwireError
+
+
+class ArchitectureError(ModwireError):
+    """Base class for architecture configuration and analysis failures."""
+
+    code = "architecture_error"

modwire-12.0.0/src/modwire/architecture/boundaries/models/unknown_flow_analyzer_error.py

@@ -0,0 +1,13 @@
+from .architecture_error import ArchitectureError
+
+
+class UnknownFlowAnalyzerError(ArchitectureError):
+    """Report a configured flow analyzer that is not registered."""
+
+    code = "unknown_flow_analyzer"
+
+    def __init__(self, analyzer: str, known_analyzers: tuple[str, ...]) -> None:
+        self.analyzer = analyzer
+        self.known_analyzers = known_analyzers
+        known = ", ".join(known_analyzers) or "none"
+        super().__init__(f"Unknown flow analyzer {analyzer!r}. Known analyzers: {known}")

{modwire-11.1.0 → modwire-12.0.0}/src/modwire/architecture/boundaries/services/boundaries_flow_analyzer.py

@@ -9,6 +9,7 @@ from ...map.models.architecture_map import ArchitectureMap
 from ...map.models.architecture_realm import ArchitectureRealm
 from ..domain import FlowAnalyzerInterface
 from ..models.flow_violation import FlowViolation
+from ..models.unknown_flow_analyzer_error import UnknownFlowAnalyzerError
 
 
 @injectable()
@@ -39,8 +40,7 @@ class BoundariesFlowAnalyzer:
         try:
             return self._analyzers[name]
         except KeyError as error:
-            known = ", ".join(sorted(self._analyzers))
-            raise ValueError(f"Unknown flow analyzer {name!r}. Known analyzers: {known}") from error
+            raise UnknownFlowAnalyzerError(name, tuple(sorted(self._analyzers))) from error
 
     def realms(self, flow: FlowRules) -> tuple[ArchitectureRealm, ...]:
         if flow.realms:

{modwire-11.1.0 → modwire-12.0.0}/src/modwire/cli/cache/application.py

@@ -7,9 +7,9 @@ from wireup import injectable
 
 from ...architecture.config.models.architecture_config import ArchitectureConfig
 from ...architecture.report.models.report_node import ReportNode
+from ...extraction.extractors.models.duplicate_identity_error import DuplicateIdentityError
 from ...extraction.extractors.models.extraction_request import ExtractionRequest
 from ...shared.code.models.code_map import CodeMap
-from ...shared.code.models.duplicate_identity_error import DuplicateIdentityError
 from ...shared.code.models.identity import FileId, ModuleId
 from ...shared.code.models.identity_kind import IdentityKind
 from ...shared.code.models.scan_policy import ScanPolicy
@@ -92,9 +92,7 @@ class CacheApplication:
         extracted = self.reader.extract_entries(observation, tuple(misses))
         writes: list[tuple[CacheKey, bytes]] = []
         for source_id in misses:
-            source_file = extracted.get(source_id)
-            if source_file is None:
-                raise RuntimeError(f"Extractor omitted a requested source file: {source_id}")
+            source_file = extracted[source_id]
             files[source_id] = source_file
             source = sources_by_id[source_id]
             writes.append((source.key, self.codec.encode(source.key, source_file.model_dump(mode="json"))))

modwire-12.0.0/src/modwire/cli/cache/models/cache_access_error.py

@@ -0,0 +1,12 @@
+from .cache_error import CacheError
+
+
+class CacheAccessError(CacheError):
+    """Report an operating-system failure while accessing persistent cache state."""
+
+    code = "cache_access"
+
+    def __init__(self, path: str, operation: str) -> None:
+        self.path = path
+        self.operation = operation
+        super().__init__(f"Could not {operation} cache path: {path}")

modwire-12.0.0/src/modwire/cli/cache/models/cache_error.py

@@ -0,0 +1,7 @@
+from ....shared.failures.models.modwire_error import ModwireError
+
+
+class CacheError(ModwireError):
+    """Base class for persistent-cache ownership and access failures."""
+
+    code = "cache_error"

modwire-12.0.0/src/modwire/cli/cache/models/cache_ownership_error.py

@@ -0,0 +1,12 @@
+from .cache_error import CacheError
+
+
+class CacheOwnershipError(CacheError):
+    """Report a cache path that cannot be safely used by Modwire."""
+
+    code = "cache_ownership"
+
+    def __init__(self, path: str, reason: str) -> None:
+        self.path = path
+        self.reason = reason
+        super().__init__(f"Cache ownership rejected for {path}: {reason}")