periplus-map 0.2.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (272) hide show
  1. periplus/__init__.py +70 -0
  2. periplus/checkmap.py +80 -0
  3. periplus/cli.py +658 -0
  4. periplus/contract/schema/map.schema.json +138 -0
  5. periplus/contract/schema/navigation.schema.json +200 -0
  6. periplus/contract/schema/pack-file.schema.json +1405 -0
  7. periplus/contract/schema/pack-manifest.schema.json +245 -0
  8. periplus/contract/schema/project-settings.schema.json +85 -0
  9. periplus/contract/spec/engine.md +151 -0
  10. periplus/contract/spec/rules.md +352 -0
  11. periplus/detect.py +228 -0
  12. periplus/engine/__init__.py +5 -0
  13. periplus/engine/check.py +481 -0
  14. periplus/engine/emit.py +368 -0
  15. periplus/engine/packload.py +2321 -0
  16. periplus/engine/pattern.py +27 -0
  17. periplus/engine/rules.py +1946 -0
  18. periplus/engine/select.py +491 -0
  19. periplus/engine/source.py +172 -0
  20. periplus/engine/tree.py +424 -0
  21. periplus/errors.py +332 -0
  22. periplus/init.py +358 -0
  23. periplus/layout.py +28 -0
  24. periplus/manifest.py +498 -0
  25. periplus/map.py +364 -0
  26. periplus/navigate/__init__.py +1 -0
  27. periplus/navigate/find.py +143 -0
  28. periplus/navigate/ids.py +30 -0
  29. periplus/navigate/listing.py +42 -0
  30. periplus/navigate/mapfile.py +189 -0
  31. periplus/navigate/path.py +175 -0
  32. periplus/navigate/show.py +175 -0
  33. periplus/navigate/types.py +83 -0
  34. periplus/navigate/walk.py +138 -0
  35. periplus/packs/advancedqueue_basic@0.0.1/pack.yaml +14 -0
  36. periplus/packs/advancedqueue_basic@0.0.1/queue_job_type/queue_job_type.yaml +9 -0
  37. periplus/packs/advancedqueue_basic@0.0.1/queue_job_type/queue_job_type_annotation.yaml +43 -0
  38. periplus/packs/advancedqueue_basic@0.0.1/queue_job_type/queue_job_type_attribute.yaml +43 -0
  39. periplus/packs/ai_basic@0.0.1/ai_agent/ai_agent.yaml +8 -0
  40. periplus/packs/ai_basic@0.0.1/ai_agent/ai_agent_attribute.yaml +43 -0
  41. periplus/packs/ai_basic@0.0.1/ai_function_call/ai_function_call.yaml +8 -0
  42. periplus/packs/ai_basic@0.0.1/ai_function_call/ai_function_call_attribute.yaml +43 -0
  43. periplus/packs/ai_basic@0.0.1/pack.yaml +15 -0
  44. periplus/packs/config_pages_basic@0.0.1/bundle/config_pages_bundle_config.yaml +54 -0
  45. periplus/packs/config_pages_basic@0.0.1/pack.yaml +11 -0
  46. periplus/packs/crop_basic@0.0.1/bundle/crop_bundle_config.yaml +54 -0
  47. periplus/packs/crop_basic@0.0.1/pack.yaml +11 -0
  48. periplus/packs/drupal@0.1.0/block/block_placement.yaml +25 -0
  49. periplus/packs/drupal@0.1.0/block/block_placement_code.yaml +58 -0
  50. periplus/packs/drupal@0.1.0/block/block_placement_config.yaml +53 -0
  51. periplus/packs/drupal@0.1.0/block/block_plugin.yaml +52 -0
  52. periplus/packs/drupal@0.1.0/block/block_plugin_altered.yaml +61 -0
  53. periplus/packs/drupal@0.1.0/block/block_plugin_annotation.yaml +69 -0
  54. periplus/packs/drupal@0.1.0/block/block_plugin_attribute.yaml +56 -0
  55. periplus/packs/drupal@0.1.0/block/block_plugin_content.yaml +46 -0
  56. periplus/packs/drupal@0.1.0/block/block_plugin_derived.yaml +110 -0
  57. periplus/packs/drupal@0.1.0/block/block_plugin_deriver.yaml +30 -0
  58. periplus/packs/drupal@0.1.0/block/block_type.yaml +14 -0
  59. periplus/packs/drupal@0.1.0/block/block_type_code.yaml +43 -0
  60. periplus/packs/drupal@0.1.0/block/block_type_config.yaml +45 -0
  61. periplus/packs/drupal@0.1.0/cache/cache.yaml +18 -0
  62. periplus/packs/drupal@0.1.0/cache/cache_backend.yaml +31 -0
  63. periplus/packs/drupal@0.1.0/component/sdc.yaml +19 -0
  64. periplus/packs/drupal@0.1.0/component/sdc_definition.yaml +25 -0
  65. periplus/packs/drupal@0.1.0/component/sdc_use.yaml +25 -0
  66. periplus/packs/drupal@0.1.0/config/config_object.yaml +65 -0
  67. periplus/packs/drupal@0.1.0/display/display.yaml +32 -0
  68. periplus/packs/drupal@0.1.0/display/display_code.yaml +53 -0
  69. periplus/packs/drupal@0.1.0/display/display_config.yaml +95 -0
  70. periplus/packs/drupal@0.1.0/entity/entity.yaml +33 -0
  71. periplus/packs/drupal@0.1.0/entity/entity_class.yaml +60 -0
  72. periplus/packs/drupal@0.1.0/entity/entity_save.yaml +27 -0
  73. periplus/packs/drupal@0.1.0/entity/entity_type_annotation.yaml +85 -0
  74. periplus/packs/drupal@0.1.0/entity/entity_type_attribute.yaml +76 -0
  75. periplus/packs/drupal@0.1.0/field/field_instance_code.yaml +40 -0
  76. periplus/packs/drupal@0.1.0/field/field_instance_config.yaml +58 -0
  77. periplus/packs/drupal@0.1.0/field/field_storage.yaml +37 -0
  78. periplus/packs/drupal@0.1.0/field/field_storage_code.yaml +39 -0
  79. periplus/packs/drupal@0.1.0/field/field_storage_config.yaml +24 -0
  80. periplus/packs/drupal@0.1.0/form/form.yaml +48 -0
  81. periplus/packs/drupal@0.1.0/form/form_class.yaml +50 -0
  82. periplus/packs/drupal@0.1.0/form/form_id.yaml +48 -0
  83. periplus/packs/drupal@0.1.0/form/form_methods.yaml +39 -0
  84. periplus/packs/drupal@0.1.0/hook/hook.yaml +8 -0
  85. periplus/packs/drupal@0.1.0/hook/hook_attribute.yaml +28 -0
  86. periplus/packs/drupal@0.1.0/module/module.yaml +8 -0
  87. periplus/packs/drupal@0.1.0/module/module_info.yaml +50 -0
  88. periplus/packs/drupal@0.1.0/pack.yaml +184 -0
  89. periplus/packs/drupal@0.1.0/plugin/plugin.yaml +17 -0
  90. periplus/packs/drupal@0.1.0/plugin/plugin_annotation.yaml +120 -0
  91. periplus/packs/drupal@0.1.0/recommendations/recommendations.yaml +14 -0
  92. periplus/packs/drupal@0.1.0/service/service.yaml +19 -0
  93. periplus/packs/drupal@0.1.0/service/service_autowire.yaml +28 -0
  94. periplus/packs/drupal@0.1.0/service/service_definition.yaml +24 -0
  95. periplus/packs/drupal@0.1.0/service/service_use.yaml +43 -0
  96. periplus/packs/drupal_basic@0.3.0/action/action.yaml +9 -0
  97. periplus/packs/drupal_basic@0.3.0/action/action_annotation.yaml +43 -0
  98. periplus/packs/drupal_basic@0.3.0/action/action_attribute.yaml +43 -0
  99. periplus/packs/drupal_basic@0.3.0/block/block_placement.yaml +16 -0
  100. periplus/packs/drupal_basic@0.3.0/block/block_placement_config.yaml +51 -0
  101. periplus/packs/drupal_basic@0.3.0/block_plugin/block_plugin.yaml +14 -0
  102. periplus/packs/drupal_basic@0.3.0/block_plugin/block_plugin_annotation.yaml +47 -0
  103. periplus/packs/drupal_basic@0.3.0/block_plugin/block_plugin_attribute.yaml +43 -0
  104. periplus/packs/drupal_basic@0.3.0/block_type/block_type.yaml +8 -0
  105. periplus/packs/drupal_basic@0.3.0/block_type/block_type_config.yaml +54 -0
  106. periplus/packs/drupal_basic@0.3.0/boundary/boundary_types.yaml +19 -0
  107. periplus/packs/drupal_basic@0.3.0/bundle/bundle.yaml +20 -0
  108. periplus/packs/drupal_basic@0.3.0/bundle/bundle_config.yaml +393 -0
  109. periplus/packs/drupal_basic@0.3.0/call/call.yaml +349 -0
  110. periplus/packs/drupal_basic@0.3.0/component/component.yaml +30 -0
  111. periplus/packs/drupal_basic@0.3.0/config/config_object.yaml +119 -0
  112. periplus/packs/drupal_basic@0.3.0/constraint/constraint.yaml +8 -0
  113. periplus/packs/drupal_basic@0.3.0/constraint/constraint_annotation.yaml +43 -0
  114. periplus/packs/drupal_basic@0.3.0/constraint/constraint_attribute.yaml +43 -0
  115. periplus/packs/drupal_basic@0.3.0/display/display.yaml +30 -0
  116. periplus/packs/drupal_basic@0.3.0/display/display_config.yaml +203 -0
  117. periplus/packs/drupal_basic@0.3.0/display/display_mode_config.yaml +60 -0
  118. periplus/packs/drupal_basic@0.3.0/entity_type/config_entity_type_annotation.yaml +46 -0
  119. periplus/packs/drupal_basic@0.3.0/entity_type/config_entity_type_attribute.yaml +43 -0
  120. periplus/packs/drupal_basic@0.3.0/entity_type/content_entity_type_annotation.yaml +46 -0
  121. periplus/packs/drupal_basic@0.3.0/entity_type/content_entity_type_attribute.yaml +43 -0
  122. periplus/packs/drupal_basic@0.3.0/entity_type/entity_type.yaml +16 -0
  123. periplus/packs/drupal_basic@0.3.0/field/field_instance_config.yaml +116 -0
  124. periplus/packs/drupal_basic@0.3.0/field/field_storage.yaml +21 -0
  125. periplus/packs/drupal_basic@0.3.0/field/field_storage_config.yaml +45 -0
  126. periplus/packs/drupal_basic@0.3.0/field_formatter/field_formatter.yaml +8 -0
  127. periplus/packs/drupal_basic@0.3.0/field_formatter/field_formatter_annotation.yaml +46 -0
  128. periplus/packs/drupal_basic@0.3.0/field_formatter/field_formatter_attribute.yaml +43 -0
  129. periplus/packs/drupal_basic@0.3.0/field_type/field_type_annotation.yaml +46 -0
  130. periplus/packs/drupal_basic@0.3.0/field_type/field_type_attribute.yaml +50 -0
  131. periplus/packs/drupal_basic@0.3.0/field_widget/field_widget_annotation.yaml +46 -0
  132. periplus/packs/drupal_basic@0.3.0/field_widget/field_widget_attribute.yaml +50 -0
  133. periplus/packs/drupal_basic@0.3.0/form/form_id.yaml +80 -0
  134. periplus/packs/drupal_basic@0.3.0/hook/hook.yaml +100 -0
  135. periplus/packs/drupal_basic@0.3.0/hook/hook_attribute.yaml +64 -0
  136. periplus/packs/drupal_basic@0.3.0/hook/hook_theme_include.yaml +34 -0
  137. periplus/packs/drupal_basic@0.3.0/library/library.yaml +12 -0
  138. periplus/packs/drupal_basic@0.3.0/library/library_definition.yaml +58 -0
  139. periplus/packs/drupal_basic@0.3.0/local_action/local_action.yaml +12 -0
  140. periplus/packs/drupal_basic@0.3.0/local_action/local_action_definition.yaml +49 -0
  141. periplus/packs/drupal_basic@0.3.0/mail/mail.yaml +8 -0
  142. periplus/packs/drupal_basic@0.3.0/mail/mail_attribute.yaml +43 -0
  143. periplus/packs/drupal_basic@0.3.0/media_source/media_source.yaml +8 -0
  144. periplus/packs/drupal_basic@0.3.0/media_source/media_source_annotation.yaml +43 -0
  145. periplus/packs/drupal_basic@0.3.0/media_source/media_source_attribute.yaml +79 -0
  146. periplus/packs/drupal_basic@0.3.0/menu_link/menu_link.yaml +18 -0
  147. periplus/packs/drupal_basic@0.3.0/menu_link/menu_link_definition.yaml +48 -0
  148. periplus/packs/drupal_basic@0.3.0/module/module.yaml +7 -0
  149. periplus/packs/drupal_basic@0.3.0/module/module_info.yaml +58 -0
  150. periplus/packs/drupal_basic@0.3.0/pack.yaml +528 -0
  151. periplus/packs/drupal_basic@0.3.0/permission/permission.yaml +7 -0
  152. periplus/packs/drupal_basic@0.3.0/permission/permission_definition.yaml +27 -0
  153. periplus/packs/drupal_basic@0.3.0/queue_worker/queue_worker.yaml +9 -0
  154. periplus/packs/drupal_basic@0.3.0/queue_worker/queue_worker_annotation.yaml +43 -0
  155. periplus/packs/drupal_basic@0.3.0/queue_worker/queue_worker_attribute.yaml +43 -0
  156. periplus/packs/drupal_basic@0.3.0/rest_resource/rest_resource.yaml +8 -0
  157. periplus/packs/drupal_basic@0.3.0/rest_resource/rest_resource_annotation.yaml +43 -0
  158. periplus/packs/drupal_basic@0.3.0/rest_resource/rest_resource_attribute.yaml +43 -0
  159. periplus/packs/drupal_basic@0.3.0/role/role.yaml +14 -0
  160. periplus/packs/drupal_basic@0.3.0/role/role_config.yaml +44 -0
  161. periplus/packs/drupal_basic@0.3.0/route/route.yaml +42 -0
  162. periplus/packs/drupal_basic@0.3.0/route/route_definition.yaml +113 -0
  163. periplus/packs/drupal_basic@0.3.0/route/route_options.yaml +55 -0
  164. periplus/packs/drupal_basic@0.3.0/route/route_requirements.yaml +108 -0
  165. periplus/packs/drupal_basic@0.3.0/service/service.yaml +56 -0
  166. periplus/packs/drupal_basic@0.3.0/service/service_definition.yaml +181 -0
  167. periplus/packs/drupal_basic@0.3.0/template/template.yaml +86 -0
  168. periplus/packs/drupal_basic@0.3.0/template/template_route_link.yaml +30 -0
  169. periplus/packs/drupal_basic@0.3.0/theme/theme.yaml +15 -0
  170. periplus/packs/drupal_basic@0.3.0/theme/theme_info.yaml +61 -0
  171. periplus/packs/drupal_basic@0.3.0/theme_hook/template_suggestion.yaml +29 -0
  172. periplus/packs/drupal_basic@0.3.0/theme_hook/theme_hook.yaml +87 -0
  173. periplus/packs/drupal_basic@0.3.0/theme_hook/theme_hook_render.yaml +20 -0
  174. periplus/packs/drupal_basic@0.3.0/url/url.yaml +88 -0
  175. periplus/packs/drupal_basic@0.3.0/views_plugin/views_field_attribute.yaml +80 -0
  176. periplus/packs/drupal_basic@0.3.0/views_plugin/views_filter_attribute.yaml +80 -0
  177. periplus/packs/drupal_basic@0.3.0/views_plugin/views_plugin.yaml +15 -0
  178. periplus/packs/drupal_basic@0.3.0/views_plugin/views_style_attribute.yaml +80 -0
  179. periplus/packs/drupal_js_basic@0.0.1/attachment/attachment.yaml +12 -0
  180. periplus/packs/drupal_js_basic@0.0.1/attachment/attachment_in_php.yaml +15 -0
  181. periplus/packs/drupal_js_basic@0.0.1/attachment/attachment_in_php_array.yaml +52 -0
  182. periplus/packs/drupal_js_basic@0.0.1/attachment/attachment_in_twig.yaml +26 -0
  183. periplus/packs/drupal_js_basic@0.0.1/attachment/php_function_holder.yaml +13 -0
  184. periplus/packs/drupal_js_basic@0.0.1/behavior/behavior.yaml +198 -0
  185. periplus/packs/drupal_js_basic@0.0.1/pack.yaml +153 -0
  186. periplus/packs/drupal_js_basic@0.0.1/setting/setting.yaml +13 -0
  187. periplus/packs/drupal_js_basic@0.0.1/setting/setting_in_js.yaml +15 -0
  188. periplus/packs/drupal_js_basic@0.0.1/setting/setting_in_php.yaml +92 -0
  189. periplus/packs/drush_basic@0.0.1/command/command.yaml +15 -0
  190. periplus/packs/drush_basic@0.0.1/command/command_annotation.yaml +60 -0
  191. periplus/packs/drush_basic@0.0.1/command/command_attribute.yaml +88 -0
  192. periplus/packs/drush_basic@0.0.1/pack.yaml +29 -0
  193. periplus/packs/eck_basic@0.0.1/bundle/eck_bundle_config.yaml +56 -0
  194. periplus/packs/eck_basic@0.0.1/entity_type/eck_entity_type_config.yaml +26 -0
  195. periplus/packs/eck_basic@0.0.1/pack.yaml +28 -0
  196. periplus/packs/go@0.0.2/interfaces/satisfies.yaml +47 -0
  197. periplus/packs/go@0.0.2/pack.yaml +51 -0
  198. periplus/packs/go@0.0.2/types/find_declarations.yaml +137 -0
  199. periplus/packs/go@0.0.2/types/node_types.yaml +36 -0
  200. periplus/packs/go_basic@0.0.3/pack.yaml +104 -0
  201. periplus/packs/go_basic@0.0.3/rules/calls.yaml +25 -0
  202. periplus/packs/go_basic@0.0.3/rules/declarations.yaml +40 -0
  203. periplus/packs/go_basic@0.0.3/rules/imports.yaml +16 -0
  204. periplus/packs/go_basic@0.0.3/types/node_types.yaml +15 -0
  205. periplus/packs/js_basic@0.0.1/function/function.yaml +68 -0
  206. periplus/packs/js_basic@0.0.1/pack.yaml +50 -0
  207. periplus/packs/laravel_basic@0.0.5/pack.yaml +313 -0
  208. periplus/packs/laravel_basic@0.0.5/rules/classes.yaml +42 -0
  209. periplus/packs/laravel_basic@0.0.5/rules/config.yaml +229 -0
  210. periplus/packs/laravel_basic@0.0.5/rules/routes.yaml +210 -0
  211. periplus/packs/laravel_basic@0.0.5/rules/types.yaml +50 -0
  212. periplus/packs/laravel_basic@0.0.5/rules/views.yaml +100 -0
  213. periplus/packs/paragraphs_basic@0.0.1/bundle/paragraph_bundle_config.yaml +54 -0
  214. periplus/packs/paragraphs_basic@0.0.1/pack.yaml +12 -0
  215. periplus/packs/php@0.1.0/edges/edge_kinds.yaml +64 -0
  216. periplus/packs/php@0.1.0/edges/find_calls.yaml +34 -0
  217. periplus/packs/php@0.1.0/edges/find_imports.yaml +18 -0
  218. periplus/packs/php@0.1.0/edges/find_member_access.yaml +22 -0
  219. periplus/packs/php@0.1.0/edges/find_structure.yaml +38 -0
  220. periplus/packs/php@0.1.0/embedded/embedded_regions.yaml +19 -0
  221. periplus/packs/php@0.1.0/imports/imports.yaml +20 -0
  222. periplus/packs/php@0.1.0/pack.yaml +117 -0
  223. periplus/packs/php@0.1.0/resolution/excluded_tokens.yaml +23 -0
  224. periplus/packs/php@0.1.0/resolution/resolution.yaml +35 -0
  225. periplus/packs/php@0.1.0/types/find_declarations.yaml +102 -0
  226. periplus/packs/php@0.1.0/types/node_types.yaml +55 -0
  227. periplus/packs/php_basic@0.2.0/edges/edge_kinds.yaml +48 -0
  228. periplus/packs/php_basic@0.2.0/edges/find_structure.yaml +750 -0
  229. periplus/packs/php_basic@0.2.0/imports/imports.yaml +19 -0
  230. periplus/packs/php_basic@0.2.0/pack.yaml +94 -0
  231. periplus/packs/php_basic@0.2.0/types/find_declarations.yaml +267 -0
  232. periplus/packs/php_basic@0.2.0/types/node_types.yaml +55 -0
  233. periplus/packs/profile_basic@0.0.1/bundle/profile_bundle_config.yaml +54 -0
  234. periplus/packs/profile_basic@0.0.1/pack.yaml +12 -0
  235. periplus/packs/salesforce_basic@0.0.1/event/salesforce_event.yaml +36 -0
  236. periplus/packs/salesforce_basic@0.0.1/pack.yaml +31 -0
  237. periplus/packs/salesforce_basic@0.0.1/salesforce_mapping/salesforce_mapping.yaml +19 -0
  238. periplus/packs/salesforce_basic@0.0.1/salesforce_mapping/salesforce_mapping_config.yaml +83 -0
  239. periplus/packs/salesforce_basic@0.0.1/salesforce_mapping_field/salesforce_mapping_field.yaml +8 -0
  240. periplus/packs/salesforce_basic@0.0.1/salesforce_mapping_field/salesforce_mapping_field_annotation.yaml +43 -0
  241. periplus/packs/twig@0.0.1/pack.yaml +26 -0
  242. periplus/packs/twig@0.0.1/types/template.yaml +57 -0
  243. periplus/packs/twig_basic@0.1.0/pack.yaml +11 -0
  244. periplus/packs/twig_tweak_basic@0.0.1/pack.yaml +27 -0
  245. periplus/packs/twig_tweak_basic@0.0.1/rules/block.yaml +20 -0
  246. periplus/packs/twig_tweak_basic@0.0.1/rules/entity.yaml +35 -0
  247. periplus/packs/twig_tweak_basic@0.0.1/rules/field.yaml +21 -0
  248. periplus/packs/twig_tweak_basic@0.0.1/rules/menu.yaml +21 -0
  249. periplus/packs/webform_basic@0.0.1/bundle/webform_submission_bundle_config.yaml +54 -0
  250. periplus/packs/webform_basic@0.0.1/pack.yaml +20 -0
  251. periplus/packs/webform_basic@0.0.1/webform_handler/webform_handler.yaml +8 -0
  252. periplus/packs/webform_basic@0.0.1/webform_handler/webform_handler_annotation.yaml +43 -0
  253. periplus/packs/yaml@0.0.1/pack.yaml +72 -0
  254. periplus/packs/yaml@0.0.1/types/find_mapping_entry.yaml +21 -0
  255. periplus/packs/yaml@0.0.1/types/yaml_types.yaml +44 -0
  256. periplus/packs/yaml_basic@0.1.0/pack.yaml +10 -0
  257. periplus/packs.py +447 -0
  258. periplus/preflight.py +102 -0
  259. periplus/py.typed +0 -0
  260. periplus/report.py +596 -0
  261. periplus/resolution.py +355 -0
  262. periplus/settings.py +617 -0
  263. periplus/settings.stub.yml +99 -0
  264. periplus/spec.py +774 -0
  265. periplus/update.py +197 -0
  266. periplus/validate.py +655 -0
  267. periplus_map-0.2.1.dist-info/METADATA +566 -0
  268. periplus_map-0.2.1.dist-info/RECORD +272 -0
  269. periplus_map-0.2.1.dist-info/WHEEL +4 -0
  270. periplus_map-0.2.1.dist-info/entry_points.txt +2 -0
  271. periplus_map-0.2.1.dist-info/licenses/LICENSE +202 -0
  272. periplus_map-0.2.1.dist-info/licenses/NOTICE +2 -0
periplus/errors.py ADDED
@@ -0,0 +1,332 @@
1
+ """The error vocabulary: the exit-code table, the record a failure renders into, and the base
2
+ class every failing module raises.
3
+
4
+ Every module in the package imports this one, and ``cli`` imports it at module level — before the
5
+ dependency check has run. That places one constraint on this file, and the constraint is its whole
6
+ shape:
7
+
8
+ ``errors`` and ``preflight`` import only the standard library, and nothing on ``cli``'s
9
+ module-level import path imports ``ruamel.yaml``, ``platformdirs`` or ``jsonschema``.
10
+
11
+ Two clauses, because they are two different properties. The first is about this file and can be
12
+ read off the header below. The second is about a graph, and it is the one a missing dependency
13
+ reported by name actually needs: a first-party ``from periplus.settings import ...``
14
+ here would satisfy "standard library only" while pulling ``ruamel.yaml`` onto the very path the
15
+ dependency check exists to keep clear. ``jsonschema`` is the third name in that clause since
16
+ ``periplus validate`` grew a reference validator, and it is why ``cli`` imports that module inside
17
+ ``main()`` rather than at module level. The file would look clean and the startup check would be
18
+ broken. Declaring ``Problem`` in ``resolution.py`` would have exactly that defect.
19
+
20
+ An earlier wording of this constraint said this module "imports nothing". That is literally false
21
+ and cannot be satisfied — ``ExitCode`` needs ``enum``, ``Problem`` needs ``dataclasses``,
22
+ ``ClassVar`` needs ``typing`` and ``Mapping`` needs ``collections.abc``. The two-clause form above
23
+ replaced it.
24
+
25
+ ``tests/test_console_script.py`` asserts the graph property directly: it imports ``periplus.cli`` in
26
+ a subprocess with every runtime distribution blocked at ``sys.meta_path``, having first confirmed in
27
+ that same subprocess that the block works.
28
+
29
+ What this module costs, recorded because it is paid on every invocation and the trade is
30
+ deliberate rather than overlooked. ``dataclasses`` is about 8.6 ms of import subtree on this
31
+ project's interpreter, against ``argparse`` at about 1.6 ms, because it pulls ``inspect``, ``ast``,
32
+ ``dis`` and ``tokenize``. ``Problem`` is a frozen dataclass anyway: nothing in this package crosses
33
+ a boundary as a dictionary with implied keys, which is what lets a JSON renderer be a mechanical
34
+ walk rather than a place where the record's shape is re-decided. Startup time is not a
35
+ measured requirement.
36
+
37
+ The distribution name is not here. It is in ``__init__.py``, which needs it to resolve
38
+ ``__version__`` and which imports nothing at all; taking it from here would pull ``enum`` and
39
+ ``dataclasses`` into every ``import periplus``, and the reverse edge would be a cycle. It was never
40
+ error vocabulary — it sat in the design here only because this was to be the module importing
41
+ nothing, and ``__init__.py`` is now that module.
42
+ """
43
+
44
+ from __future__ import annotations
45
+
46
+ from collections.abc import Mapping
47
+ from dataclasses import dataclass
48
+ from enum import IntEnum
49
+ from types import MappingProxyType
50
+ from typing import ClassVar
51
+
52
+ __all__ = ["ExitCode", "HarnessError", "Problem"]
53
+
54
+
55
+ class ExitCode(IntEnum):
56
+ """Every status the process can return, one per class of failure.
57
+
58
+ One code per class, and each is a different thing for a person to do about it: install
59
+ something, fix a pin, delete a copy, fix a name, break a cycle. There is no code for a pin
60
+ disagreeing with a manifest, because that check belongs to the validator: ``packs.py`` assigns
61
+ it there by name, and ``manifest.py`` — which does open a ``pack.yaml`` — deliberately declines
62
+ it, carrying the directory's name and the manifest's own ``pack`` side by side rather than
63
+ choosing between them. Pin matching itself opens nothing inside a pack directory and could not
64
+ make the check; the reader that could is not its owner.
65
+
66
+ All of them are declared here although nothing in this package raises ``INTERNAL`` and nothing
67
+ returns ``USAGE`` as a value — both are statuses the process produces anyway, an uncaught
68
+ exception through the interpreter and a usage error through ``parser.error``. A code table
69
+ costs nothing to declare and withholding members would mean editing this enum in five later
70
+ components — which is the edit the open-closed principle says should never be needed. What
71
+ each member traces to is written beside it.
72
+
73
+ 7 and 8 are absent rather than free. They were declared for a folder component, forecasting
74
+ ``FOLDER_UNKNOWN`` and ``FOLDER_CYCLE``, and were deleted because nothing
75
+ folder-shaped was ever built and this file's own rule is that a failure class arrives with the
76
+ module that raises it. Neither number is reused: renumbering would change a status a person
77
+ may already have scripted against.
78
+ """
79
+
80
+ #: Resolved. Implied by every command that produces a report.
81
+ OK = 0
82
+
83
+ #: An exception that is not a ``HarnessError``. Nothing raises it:
84
+ #: an uncaught Python exception already exits 1, so a top-level handler here would only
85
+ #: swallow the traceback that makes an internal error diagnosable. The member documents what
86
+ #: the status means. Adding the handler is a separate decision.
87
+ INTERNAL = 1
88
+
89
+ #: A usage error — argparse's own status, and the one ``cli`` already returned as a literal
90
+ #: before this enum existed.
91
+ USAGE = 2
92
+
93
+ #: A settings file that was **asked for** is not there. Raised by
94
+ #: ``resolution._refuse_a_named_file_that_is_not_there``, and by nothing else.
95
+ #:
96
+ #: It used to mean "no settings file at either level", which ``_merge`` raised on every
97
+ #: unconfigured run — so a fresh install exited 3 and printed a ``Problems`` section, reporting
98
+ #: its own normal starting condition as a fault. That is gone: for a command whose job is to
99
+ #: describe a state, an empty one is the state. What is left is the narrower case with the
100
+ #: opposite remedy — a path a person typed that does not exist, where exit 0 would tell them a
101
+ #: file was read that never was.
102
+ #:
103
+ #: The number is unchanged through both, which is the point of declaring the table up front.
104
+ NO_SETTINGS = 3
105
+
106
+ #: A settings file could not be read or parsed. It follows
107
+ #: from the decision to parse with ``ruamel.yaml`` at ``typ='safe'``, which raises on a
108
+ #: duplicate key where PyYAML silently keeps the last value. That refusal has to surface.
109
+ UNREADABLE_SETTINGS = 4
110
+
111
+ #: A pin matched no directory name. The *report* is required — "a named pin with no
112
+ #: matching directory is reported missing"; that the status is non-zero, and that it is 5, is a
113
+ #: design decision.
114
+ PIN_UNMATCHED = 5
115
+
116
+ #: One pin matched a directory name under two roots. Same split as above: "reported twice
117
+ #: rather than resolved" is the requirement, the status is the decision.
118
+ PIN_DUPLICATED = 6
119
+
120
+ #: A required distribution is absent. A non-zero status naming which one is required; the
121
+ #: number 9 is design.
122
+ MISSING_DEPENDENCY = 9
123
+
124
+ #: A path a command had to create is already there, and nothing was overwritten. Raised by
125
+ #: ``init.TargetExists``, which enumerates its causes: a settings file that already exists, a
126
+ #: regular file where either directory belongs, or a symlink where either belongs, refused
127
+ #: rather than followed. All are one thing to do about it: look at the named path. The number
128
+ #: 10 is design; it is the first member added after the original table.
129
+ TARGET_EXISTS = 10
130
+
131
+ #: A pack manifest exists as a path and could not be turned into a mapping. Raised by
132
+ #: ``manifest.ManifestUnreadable``, whose ``detail`` names which of the five causes it was.
133
+ #: The same shape as ``UNREADABLE_SETTINGS`` and a separate number, because the two name
134
+ #: different files with different owners: a person edits their own settings file, and a pack
135
+ #: manifest is shipped by whoever wrote the pack.
136
+ UNREADABLE_MANIFEST = 11
137
+
138
+ #: A ``depends`` entry names a pack no directory on the search path carries. One thing to do
139
+ #: about it: install that pack, or fix the name. The number 12 is design.
140
+ #:
141
+ #: ``DEPENDS_`` and not ``DEPENDENCY_``, throughout: ``MISSING_DEPENDENCY`` above already
142
+ #: means a runtime *distribution*, and so does ``preflight.DependencyStatus``. The three
143
+ #: members below are named for the manifest key they read, which is the one word that cannot
144
+ #: be confused with the other meaning.
145
+ DEPENDS_UNMATCHED = 12
146
+
147
+ #: A ``depends`` entry names a pack two directories on the search path both carry — ``php``
148
+ #: with a ``php@0.1.0`` and a ``php@0.2.0`` beside it. The same split as ``PIN_DUPLICATED``:
149
+ #: it is reported rather than resolved, because a ``depends`` entry carries no version and
150
+ #: nothing in the manifest says which of the two the author meant.
151
+ DEPENDS_DUPLICATED = 13
152
+
153
+ #: A pack's ``depends`` chain reaches back to a pack already on the path being walked, itself
154
+ #: included. One thing to do about it: break the cycle. The manifest schema does not forbid
155
+ #: it — ``depends`` items are matched against a name pattern and nothing compares them to the
156
+ #: declaring pack — so it is detected here rather than assumed away.
157
+ DEPENDS_CYCLE = 14
158
+
159
+ #: A pack named on the command line is not on the pack search path. Returned by
160
+ #: ``spec._unknown_pack``, and reachable the first time somebody types ``periplus spec`` and
161
+ #: misspells a pack.
162
+ #:
163
+ #: Its own number, and not ``DEPENDS_UNMATCHED``, although the remedy is the same sentence —
164
+ #: install that pack, or fix the name. That member says a *manifest* names a pack nothing
165
+ #: carries, which is a fault in a file somebody wrote and shipped; this one says an *argument*
166
+ #: does, which is a typo at a prompt. Different file, different owner, and a report printing
167
+ #: one number for both would tell a reader less than it knows.
168
+ #:
169
+ #: **It is a code in the report first, and on the process status it is often not there at
170
+ #: all.** Two facts about where it can appear, both read off the code rather than argued:
171
+ #:
172
+ #: * It never co-occurs with a ``DEPENDS_*`` code. ``spec._describe_pack`` appends this
173
+ #: problem and returns *before* ``resolve_pack_order`` is called, so a run that produced 15
174
+ #: walked no dependency graph, and a run that walked one found the pack. The two are
175
+ #: mutually exclusive by construction, and an earlier version of this docblock justified the
176
+ #: member with a run — a misspelled ``drupal`` whose ``yaml`` dependency is also missing —
177
+ #: that cannot happen.
178
+ #: * It does co-occur with a settings or pin fault, because ``spec`` resolves the search path
179
+ #: exactly as ``status`` does and inherits every problem resolution found. A report's status
180
+ #: is the *lowest* code among its problems and 15 is the highest number any report reaches
181
+ #: this way, so any such fault takes the status and this one is masked: ``periplus spec
182
+ #: twigg`` exits 5 in a project pinning a pack that is not installed, and 15 in a directory
183
+ #: that is not a project. Measured, both. (16 below is higher still and is never reached by
184
+ #: ``min()`` at all; that is the whole of its own note.)
185
+ #:
186
+ #: So the process status of a project that has any other fault does not tell a broken pack
187
+ #: name from a broken invocation, and a script that needs to must read the report rather than
188
+ #: ``$?``. That is where the two stay distinguishable: the problem is carried in
189
+ #: ``SpecReport.problems`` under this code with a ``detail`` naming the pack asked for and
190
+ #: every pack that is there, printed beside its number in the text form and under ``problems``
191
+ #: in ``--format json``. The status says a run had a fault; the report says which faults.
192
+ PACK_UNKNOWN = 15
193
+
194
+ #: A file inside a pack disagrees with the schema that pack file is written against. Returned
195
+ #: by ``validate.ValidationReport.exit_code``, and by nothing else.
196
+ #:
197
+ #: Its own number, and not one of the ``UNREADABLE_`` codes: those say a file could not be
198
+ #: turned into a mapping at all, and this one says the mapping is there and says the wrong
199
+ #: thing. One remedy either way — open the named file — but a different fault, and the report
200
+ #: names a key and a pointer inside the document for this one and cannot for those.
201
+ #:
202
+ #: **It is the one code with its own aggregation rule, and it needs one.** Every other report
203
+ #: takes ``min()`` over its problems, for the reason ``ResolutionReport.exit_code`` gives: the
204
+ #: status must not depend on the order the stages appended in. 16 is the highest number in this
205
+ #: table, so under ``min()`` it would be masked by every existing code — a ``validate`` run in a
206
+ #: project that also pins a pack nobody installed would exit 5, answering a question about a
207
+ #: pack with a fault in a settings file. So ``validate`` departs: **any schema error yields 16,
208
+ #: and with none the resolution problems aggregate by ``min()`` exactly as they do elsewhere.**
209
+ #: That departure is a property of one report and not of this table, which is why it is stated
210
+ #: here beside the member and asserted by a pair of tests — one run with both faults at once,
211
+ #: one with only the resolution fault — because either alone is satisfied by the wrong rule.
212
+ #:
213
+ #: A schema error is never dropped from the report to make the status say something. Both
214
+ #: kinds are carried side by side: ``ValidationReport.errors`` and ``ValidationReport.problems``
215
+ #: are separate fields because they are faults in different files with different owners.
216
+ SCHEMA_INVALID = 16
217
+
218
+ #: ``periplus map`` built a document its own schema refuses, an engine defect; or the project
219
+ #: pins no rutter, which stops the run before anything is built. Nothing is written.
220
+ MAP_INVALID = 17
221
+
222
+ #: A folder name is unknown, cyclic, in conflict between packs, or leaves the project root.
223
+ FOLDER_UNRESOLVED = 18
224
+
225
+ #: A pack's rule file cannot be read, or its types or rules disagree.
226
+ PACK_RULES_UNREADABLE = 19
227
+
228
+ #: A source file cannot be read as data: a parse error, bytes that are not UTF-8, a root that
229
+ #: is not a mapping, a tag outside the core set, or a key written twice in one mapping.
230
+ SOURCE_UNREADABLE = 20
231
+
232
+ #: Rules found types for one id that do not lie on one ancestor chain.
233
+ TYPE_COLLISION = 21
234
+
235
+ #: An edge's end has a type the edge kind does not allow there.
236
+ EDGE_ILLEGAL = 22
237
+
238
+ #: A pack names a type that neither it nor a pack it depends on declares.
239
+ UNDECLARED_TYPE = 23
240
+
241
+ #: An edge rule names a kind that neither its pack nor a pack it depends on declares.
242
+ UNDECLARED_EDGE_KIND = 24
243
+
244
+ #: Two rules of one pack carry one name.
245
+ RULE_DUPLICATED = 25
246
+
247
+ #: A rule has a shape the engine cannot execute, so the run is refused rather than partial.
248
+ RULE_NOT_EXECUTABLE = 26
249
+
250
+ #: The map could not be written to the path asked for.
251
+ OUTPUT_UNWRITABLE = 27
252
+
253
+ #: A pack's grammar pins a parser runtime or a grammar version other than the one installed,
254
+ #: or one that is not installed at all. Found before any source file is opened.
255
+ GRAMMAR_MISMATCH = 28
256
+
257
+ #: A navigation command found no map to read: no project above the working directory, or no
258
+ #: file at the default path or at the ``--map`` path. Remedy: run ``periplus map``.
259
+ MAP_NOT_FOUND = 29
260
+
261
+ #: The file a navigation command read is not JSON, or fails the map schema.
262
+ NOT_A_MAP = 30
263
+
264
+ #: An id given to a navigation command names no node in the map.
265
+ NODE_NOT_FOUND = 31
266
+
267
+
268
+ @dataclass(frozen=True, slots=True)
269
+ class Problem:
270
+ """One failure, as a record rather than as a formatted string.
271
+
272
+ ``message`` is the one line a person reads. ``detail`` is the same failure as named facts, so a
273
+ consumer of ``--format json`` reads keys rather than parsing prose. Both are populated at the
274
+ point the failure is found, where the facts are still in scope.
275
+
276
+ Frozen and slotted so that a report is assembled from records that cannot be edited after the
277
+ stage that produced them has returned, and so that a renderer walking a report cannot silently
278
+ depend on a key nobody declared.
279
+ """
280
+
281
+ code: ExitCode
282
+ message: str
283
+ detail: Mapping[str, str]
284
+
285
+
286
+ class HarnessError(Exception):
287
+ """The base of every failure the harness raises, carrying its own exit code.
288
+
289
+ ``code`` is declared and deliberately not assigned. A subclass sets it, so the exit-code table
290
+ is a property of the class hierarchy rather than a branch inside ``main`` — adding a failure
291
+ class is a new exception class and a new enum member, never an edit to the console script.
292
+
293
+ Nothing enforces that a subclass remembered. A subclass that forgets raises ``AttributeError``
294
+ from ``problem()`` rather than reporting some default code, which is the better of the two
295
+ failure modes: a missing code is loud, and a wrong code is a report that lies.
296
+
297
+ No subclass ships in this file. Each one arrives with the module that raises it —
298
+ ``SettingsUnreadable`` with ``settings.py``. A subclass
299
+ with no raiser and no test exercising it is work pulled forward, and shipping them here would
300
+ let the claim above be asserted once instead of exercised five times. The test for
301
+ ``problem()`` defines its own subclass, which tests the mechanism rather than one instance of
302
+ it.
303
+
304
+ ``packs.py`` ships no subclass at all. It returns ``Problem`` records directly, because one
305
+ call has to report every unmatched pin and an exception carries one.
306
+ """
307
+
308
+ code: ClassVar[ExitCode]
309
+
310
+ def __init__(self, message: str, detail: Mapping[str, str] | None = None) -> None:
311
+ """Take the one-line message and the named facts that go with it.
312
+
313
+ ``detail`` is accepted here, rather than left for a subclass to add later, because without
314
+ it ``problem()`` could only ever return an empty mapping and ``Problem.detail`` would be a
315
+ dead field until some component reopened this file to fix that. Reopening this file is the
316
+ thing the class is arranged to avoid.
317
+
318
+ The mapping is copied and wrapped, so the record ``problem()`` returns cannot be edited
319
+ through the exception that produced it. A frozen dataclass stops the field being rebound;
320
+ it does not stop the mapping inside it being mutated, and this is where that is closed.
321
+ ``types`` is already resident before user code runs, so the wrap costs nothing measurable.
322
+ """
323
+ super().__init__(message)
324
+ self.detail: Mapping[str, str] = MappingProxyType(dict(detail or {}))
325
+
326
+ def problem(self) -> Problem:
327
+ """This failure as a ``Problem``, carrying the raising subclass's own code.
328
+
329
+ ``type(self).code`` rather than a literal, which is the whole arrangement: the code
330
+ travels with the class, so this method never learns about a new failure class.
331
+ """
332
+ return Problem(code=type(self).code, message=str(self), detail=self.detail)