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/map.py ADDED
@@ -0,0 +1,364 @@
1
+ """``periplus map``: extract the map of a project and write it.
2
+
3
+ The shape follows ``validate`` and ``spec``: frozen records, an ``exit_code`` property, and a
4
+ ``RENDERERS`` table keyed by ``--format``'s two choices. All extraction lives in the
5
+ ``periplus.engine`` package. This module links settings, packs, the engine and the write.
6
+
7
+ It names no stack. Every folder, type and rule comes from a loaded pack.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ import os
14
+ import posixpath
15
+ from collections import Counter
16
+ from collections.abc import Callable, Mapping, Sequence
17
+ from dataclasses import dataclass
18
+ from pathlib import Path
19
+ from typing import Any
20
+
21
+ from jsonschema import Draft202012Validator
22
+
23
+ import periplus
24
+ from periplus.engine.check import checked
25
+ from periplus.engine.emit import build_document, render
26
+ from periplus.engine.rules import MapPass, run_file_rules, run_map_rules
27
+ from periplus.engine.select import Selection, files_in, holds_double_star, resolve_folders
28
+ from periplus.errors import ExitCode, HarnessError, Problem
29
+ from periplus.layout import PROJECT_MARKER, SETTINGS_FILENAME
30
+ from periplus.manifest import resolve_pack_order
31
+ from periplus.preflight import DependencyStatus
32
+ from periplus.report import _escape
33
+ from periplus.resolution import resolve
34
+ from periplus.validate import _schema
35
+
36
+ __all__ = ["RENDERERS", "MapReport", "render_json", "render_text", "run"]
37
+
38
+ #: The shipped schema the built document is checked against before anything is written.
39
+ MAP_SCHEMA = "schema/map.schema.json"
40
+
41
+ #: The map's default home, under the project root.
42
+ _DEFAULT_MAP = "map.json"
43
+
44
+
45
+ @dataclass(frozen=True, slots=True)
46
+ class MapReport:
47
+ """One ``map`` run. ``map_path`` is ``None`` when nothing was written."""
48
+
49
+ map_path: str | None
50
+ nodes: int
51
+ edges: int
52
+ packs: tuple[tuple[str, str], ...]
53
+ executed: tuple[tuple[str, str, int], ...]
54
+ not_executed: tuple[tuple[str, str, str], ...]
55
+ problems: tuple[Problem, ...]
56
+ opened: tuple[str, ...] = ()
57
+ differing: tuple[tuple[str, str], ...] = ()
58
+ selected: int = 0
59
+ excluded: int = 0
60
+ parse_errors: tuple[str, ...] = ()
61
+ skipped: tuple[tuple[str, int, str, str], ...] = ()
62
+ #: The files below the rules' folders, after excludes, that no executed rule selected.
63
+ unread: tuple[str, ...] = ()
64
+ #: The folders below the rules' folders that the unread walk could not list.
65
+ unlisted: tuple[str, ...] = ()
66
+ #: Each pass of the map rules, the last one adding nothing; empty when no map rule runs.
67
+ map_passes: tuple[MapPass, ...] = ()
68
+
69
+ @property
70
+ def exit_code(self) -> ExitCode:
71
+ """The lowest code among the problems, or ``OK`` when there were none."""
72
+ return min((problem.code for problem in self.problems), default=ExitCode.OK)
73
+
74
+ @property
75
+ def idle(self) -> tuple[tuple[str, str], ...]:
76
+ """The executed rules that fired zero times."""
77
+ return tuple((pack, rule) for pack, rule, fires in self.executed if fires == 0)
78
+
79
+
80
+ def run(
81
+ start: Path,
82
+ env: Mapping[str, str],
83
+ dependencies: tuple[DependencyStatus, ...],
84
+ settings_path: Path | None = None,
85
+ output: Path | None = None,
86
+ ) -> MapReport:
87
+ """Resolve the project, run its rules, validate the document and write it.
88
+
89
+ A problem the resolution already carries ends the run with its code before any file is
90
+ selected. A project with no settings file is ``NO_SETTINGS``. A pack that fails its schema
91
+ does not hide the problems of the packs that do not depend on it. Nothing is written on any
92
+ failure.
93
+ """
94
+ resolution = resolve(
95
+ start=start, env=env, dependencies=dependencies, settings_path=settings_path
96
+ )
97
+ problems = list(resolution.problems)
98
+ project = next(
99
+ (s for s in resolution.settings_sources if s.kind == "project" and s.status == "used"),
100
+ None,
101
+ )
102
+ if not problems and (project is None or resolution.settings is None):
103
+ problems.append(
104
+ Problem(
105
+ ExitCode.NO_SETTINGS,
106
+ f"no {PROJECT_MARKER}/{SETTINGS_FILENAME} found for this project",
107
+ {},
108
+ )
109
+ )
110
+ if problems or project is None or resolution.settings is None:
111
+ return _failed(problems)
112
+ if not resolution.packs:
113
+ message = (
114
+ f"no rutter is pinned: list one under packs in {PROJECT_MARKER}/{SETTINGS_FILENAME}; "
115
+ "periplus status shows the bundled rutters"
116
+ )
117
+ return _failed([Problem(ExitCode.MAP_INVALID, message, {"setting": "packs"})])
118
+
119
+ packs, pack_problems = resolve_pack_order(resolution.packs, resolution.candidates)
120
+ if pack_problems:
121
+ return _failed(pack_problems)
122
+ root = project.root
123
+ given = resolution.settings.values
124
+ values = {name: setting.value for name, setting in given.items()}
125
+ origins = {name: setting.sources[-1].name for name, setting in given.items()}
126
+ rule_set, refused = checked(packs, values, origins)
127
+ try:
128
+ if rule_set is None or refused:
129
+ return _failed(refused)
130
+ wanted = sorted(
131
+ {name for rule in rule_set.rules if rule.supported for name in rule.folders}
132
+ )
133
+ # A path value relative to a folder needs its directories; the unread walk stays on rules.
134
+ relative = {v.relative_to for i in rule_set.files.values() for v in i.path_values}
135
+ overrides = {n: setting.value for n, setting in resolution.settings.folders.items()}
136
+ settings = resolution.settings
137
+ first_party = settings.first_party.value if settings.first_party else None
138
+ selection = Selection.build(
139
+ packs,
140
+ {name: setting.value for name, setting in settings.extensions.items()},
141
+ first_party.include if first_party else (),
142
+ first_party.exclude if first_party else (),
143
+ settings.exclude.value if settings.exclude else (),
144
+ settings.re_include.value if settings.re_include else (),
145
+ )
146
+ deep = sorted(name for name in relative - {""} if holds_double_star(name, packs, overrides))
147
+ if deep:
148
+ message = (
149
+ f"the folder {deep[0]}, which a path value is relative_to, holds ** in its value"
150
+ )
151
+ return _failed([Problem(ExitCode.FOLDER_UNRESOLVED, message, {"folder": deep[0]})])
152
+ folders = resolve_folders(
153
+ sorted({*wanted, *relative} - {""}), packs, overrides, root, selection
154
+ )
155
+ found_nodes, found_edges, fires, opened, read, removed, broken, skipped = run_file_rules(
156
+ root, rule_set, packs, folders, selection
157
+ )
158
+ map_nodes, map_edges, map_fires, map_passes = run_map_rules(
159
+ rule_set, found_nodes, found_edges
160
+ )
161
+ fires.update(map_fires)
162
+ directories = sorted({path for name in wanted for path in folders[name]})
163
+ listed, unlisted = files_in(root, directories, selection)
164
+ unread = sorted(set(listed) - read)
165
+ document = build_document(
166
+ [*found_nodes, *map_nodes],
167
+ [*found_edges, *map_edges],
168
+ rule_set.types,
169
+ rule_set.edge_kinds,
170
+ packs,
171
+ periplus.__version__,
172
+ Path(os.path.relpath(project.path, root)).as_posix(),
173
+ boundary=rule_set.boundary,
174
+ skipped=skipped,
175
+ )
176
+ except HarnessError as error:
177
+ return _failed([error.problem()])
178
+ declared = {info.id_namespace for info in rule_set.types.values() if info.id_namespace}
179
+ undeclared = sorted(
180
+ node["id"] for node in document["nodes"] if node["id"].partition("::")[0] not in declared
181
+ )
182
+ if undeclared:
183
+ more = f", and {len(undeclared) - 1} more" if len(undeclared) > 1 else ""
184
+ message = (
185
+ "the built map holds an id whose namespace no loaded pack declares "
186
+ f"(UNDECLARED_ID_NAMESPACE): {undeclared[0]}{more}"
187
+ )
188
+ detail = {"problem": "UNDECLARED_ID_NAMESPACE", "id": undeclared[0]}
189
+ return _failed([Problem(ExitCode.MAP_INVALID, message, detail)])
190
+ invalid = sorted(
191
+ Draft202012Validator(_schema(MAP_SCHEMA)).iter_errors(document),
192
+ key=lambda found: (list(map(str, found.absolute_path)), found.message),
193
+ )
194
+ if invalid:
195
+ message = f"the built map does not match its schema: {invalid[0].message}"
196
+ return _failed([Problem(ExitCode.MAP_INVALID, message, {})])
197
+
198
+ target = start / output if output is not None else root / PROJECT_MARKER / _DEFAULT_MAP
199
+ try:
200
+ target.write_bytes(render(document).encode("utf-8"))
201
+ except OSError as error:
202
+ message = f"the map cannot be written to {target}: {error.strerror or error}"
203
+ return _failed([Problem(ExitCode.OUTPUT_UNWRITABLE, message, {"path": str(target)})])
204
+ return MapReport(
205
+ map_path=str(target),
206
+ nodes=len(document["nodes"]),
207
+ edges=len(document["edges"]),
208
+ packs=tuple(sorted((p.name.pack, p.name.version) for p in packs)),
209
+ executed=tuple(sorted((pack, rule, count) for (pack, rule), count in fires.items())),
210
+ not_executed=tuple(
211
+ sorted(
212
+ (rule.pack, rule.name, rule.reason) for rule in rule_set.rules if not rule.supported
213
+ )
214
+ ),
215
+ problems=(),
216
+ opened=tuple(opened),
217
+ differing=_differing(document),
218
+ selected=len(read),
219
+ excluded=len(removed),
220
+ parse_errors=tuple(broken),
221
+ skipped=tuple(sorted(skipped)),
222
+ unread=tuple(unread),
223
+ unlisted=tuple(unlisted),
224
+ map_passes=tuple(map_passes),
225
+ )
226
+
227
+
228
+ def _differing(document: Mapping[str, Any]) -> tuple[tuple[str, str], ...]:
229
+ """Each node id and attribute name whose value is written with ``differs``."""
230
+ return tuple(
231
+ sorted(
232
+ (node["id"], name)
233
+ for node in document["nodes"]
234
+ for name, value in node.get("attributes", {}).items()
235
+ if isinstance(value, dict) and set(value) == {"differs"}
236
+ )
237
+ )
238
+
239
+
240
+ def _failed(problems: Sequence[Problem]) -> MapReport:
241
+ return MapReport(
242
+ None, 0, 0, (), (), (), tuple(sorted(problems, key=lambda p: (p.code, p.message)))
243
+ )
244
+
245
+
246
+ def _section(heading: str, rows: Sequence[str]) -> list[str]:
247
+ """A blank line, a heading, and the rows indented under it; ``none`` when there are none."""
248
+ return ["", f"{heading}:", *[f" {row}".rstrip() for row in rows or ["none"]]]
249
+
250
+
251
+ def render_text(report: MapReport) -> str:
252
+ """The report as lines a person reads. Every outside string goes through ``_escape``."""
253
+ lines = ["periplus map"]
254
+ lines += _section(
255
+ "Map",
256
+ [
257
+ f"{'path':<8}{_escape(report.map_path or 'not written')}",
258
+ f"{'nodes':<8}{report.nodes}",
259
+ f"{'edges':<8}{report.edges}",
260
+ ],
261
+ )
262
+ lines += _section(
263
+ "Files",
264
+ [
265
+ f"{'selected':<10}{report.selected}",
266
+ f"{'excluded':<10}{report.excluded}",
267
+ f"{'unread':<10}{len(report.unread)}",
268
+ f"{'unlisted':<10}{len(report.unlisted)}",
269
+ ],
270
+ )
271
+ endings = Counter(
272
+ posixpath.splitext(posixpath.basename(path))[1].lstrip(".") for path in report.unread
273
+ )
274
+ lines += _section(
275
+ "Files no rule read, by ending",
276
+ [
277
+ f"{_escape(ending or 'none')} {count}"
278
+ for ending, count in sorted(endings.items(), key=lambda item: (-item[1], item[0]))
279
+ ],
280
+ )
281
+ shown = [_escape(path) for path in report.unread[:20]]
282
+ if len(report.unread) > 20:
283
+ shown.append(f"and {len(report.unread) - 20} more; the JSON report lists them all")
284
+ lines += _section("Files no rule read", shown)
285
+ listed = [_escape(path) for path in report.unlisted[:20]]
286
+ if len(report.unlisted) > 20:
287
+ listed.append(f"and {len(report.unlisted) - 20} more; the JSON report lists them all")
288
+ lines += _section("Folders that could not be listed", listed)
289
+ lines += _section("Files that did not parse cleanly", [_escape(f) for f in report.parse_errors])
290
+ lines += _section("Packs", [f"{_escape(p)} {_escape(v)}" for p, v in report.packs])
291
+ lines += _section(
292
+ "Rules executed",
293
+ [f"{_escape(p)} {_escape(r)} fired {n}" for p, r, n in report.executed],
294
+ )
295
+ lines += _section(
296
+ "Rules that fired zero times", [f"{_escape(p)} {_escape(r)}" for p, r in report.idle]
297
+ )
298
+ lines += _section(
299
+ "Map rule passes",
300
+ [
301
+ f"pass {n}: "
302
+ + (", ".join(f"{_escape(p)} {_escape(r)} fired {k}" for p, r, k in rows) or "none")
303
+ for n, rows in report.map_passes
304
+ ],
305
+ )
306
+ lines += _section(
307
+ "Rules not executed",
308
+ [f"{_escape(p)} {_escape(r)} {_escape(why)}" for p, r, why in report.not_executed],
309
+ )
310
+ lines += _section(
311
+ "Matches skipped",
312
+ [f"{_escape(f)}:{n} {_escape(r)} {_escape(why)}" for f, n, r, why in report.skipped],
313
+ )
314
+ lines += _section(
315
+ "Attributes that differ between files",
316
+ [f"{_escape(node)} {_escape(name)}" for node, name in report.differing],
317
+ )
318
+ lines += _section(
319
+ "Problems",
320
+ [f"{int(p.code)} {_escape(p.message)}" for p in report.problems],
321
+ )
322
+ return "\n".join(lines) + "\n"
323
+
324
+
325
+ def render_json(report: MapReport) -> str:
326
+ """The report as one JSON document, keys sorted, ``ensure_ascii=True``."""
327
+ payload = {
328
+ "map": report.map_path,
329
+ "nodes": report.nodes,
330
+ "edges": report.edges,
331
+ "packs": [{"pack": p, "version": v} for p, v in report.packs],
332
+ "executed": [{"pack": p, "rule": r, "fires": n} for p, r, n in report.executed],
333
+ "zero_fires": [{"pack": p, "rule": r} for p, r in report.idle],
334
+ "not_executed": [
335
+ {"pack": p, "rule": r, "reason": why} for p, r, why in report.not_executed
336
+ ],
337
+ "opened": list(report.opened),
338
+ "parse_errors": list(report.parse_errors),
339
+ "skipped": [
340
+ {"file": f, "line": n, "rule": r, "reason": why} for f, n, r, why in report.skipped
341
+ ],
342
+ "differing": [{"node": n, "attribute": a} for n, a in report.differing],
343
+ "selected": report.selected,
344
+ "excluded": report.excluded,
345
+ "unread": list(report.unread),
346
+ "unlisted": list(report.unlisted),
347
+ "map_passes": [
348
+ {"pass": n, "fired": [{"pack": p, "rule": r, "fires": k} for p, r, k in rows]}
349
+ for n, rows in report.map_passes
350
+ ],
351
+ "problems": [
352
+ {"code": int(p.code), "message": p.message, "detail": dict(p.detail)}
353
+ for p in report.problems
354
+ ],
355
+ }
356
+ return json.dumps(payload, sort_keys=True, indent=2, ensure_ascii=True) + "\n"
357
+
358
+
359
+ #: The formats ``map --format`` offers. ``cli.build_parser`` writes the same two names as a
360
+ #: literal because ``cli`` may not import this module; a test asserts the two agree.
361
+ RENDERERS: Mapping[str, Callable[[MapReport], str]] = {
362
+ "text": render_text,
363
+ "json": render_json,
364
+ }
@@ -0,0 +1 @@
1
+ """Commands that read a written map back: load it, index it, answer a question about it."""
@@ -0,0 +1,143 @@
1
+ """``periplus find``: the nodes whose id holds a text, closest match first."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from collections.abc import Mapping
7
+ from dataclasses import dataclass
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from periplus.errors import ExitCode, HarnessError, Problem
12
+ from periplus.navigate.listing import Listing, cut, footer, payload
13
+ from periplus.navigate.mapfile import MapIndex, as_text, load_map, reading_fields
14
+ from periplus.report import _escape
15
+
16
+ __all__ = ["RENDERERS", "FindReport", "render_json", "render_text", "run"]
17
+
18
+
19
+ @dataclass(frozen=True, slots=True)
20
+ class FindReport:
21
+ """The matching nodes as rows (id, type, state, first location), and what went wrong."""
22
+
23
+ matches: Listing = Listing((), 0, 0, False)
24
+ warnings: tuple[str, ...] = ()
25
+ problems: tuple[Problem, ...] = ()
26
+
27
+ @property
28
+ def exit_code(self) -> ExitCode:
29
+ """The lowest code among the problems, or ``OK`` when there were none."""
30
+ return min((problem.code for problem in self.problems), default=ExitCode.OK)
31
+
32
+
33
+ def _rank(node_id: str, text: str) -> int | None:
34
+ """0 the id is the text, 1 the name is, 2 it starts with it, 3 holds it, 4 the id holds it."""
35
+ whole = node_id.casefold()
36
+ name = whole.rsplit("::", 1)[-1]
37
+ if whole == text:
38
+ return 0
39
+ if name == text:
40
+ return 1
41
+ if name.startswith(text):
42
+ return 2
43
+ if text in name:
44
+ return 3
45
+ return 4 if text in whole else None
46
+
47
+
48
+ def _with_subtypes(index: MapIndex, type_name: str) -> set[str]:
49
+ """``type_name`` and every type below it in the map's hierarchy."""
50
+ found = {type_name}
51
+ pending = [type_name]
52
+ while pending:
53
+ for child in index.subtypes(pending.pop()):
54
+ if child not in found:
55
+ found.add(child)
56
+ pending.append(child)
57
+ return found
58
+
59
+
60
+ def _location(node: Mapping[str, Any]) -> str | None:
61
+ """The node's first location as ``file:line``, or ``None`` when it has none."""
62
+ locations = node["locations"]
63
+ return f"{locations[0]['file']}:{locations[0]['line']}" if locations else None
64
+
65
+
66
+ def run(
67
+ start: Path,
68
+ env: Mapping[str, str],
69
+ text: str,
70
+ type_name: str | None,
71
+ limit: int,
72
+ map_path: Path | None,
73
+ ) -> FindReport:
74
+ """Find the nodes whose id holds ``text``; a load failure is a problem, not a raise."""
75
+ try:
76
+ index = load_map(start, env, map_path)
77
+ with reading_fields(start, map_path):
78
+ return _find(index, text, type_name, limit)
79
+ except HarnessError as error:
80
+ return FindReport(problems=(error.problem(),))
81
+
82
+
83
+ def _find(index: MapIndex, text: str, type_name: str | None, limit: int) -> FindReport:
84
+ """``run``'s report, read from the map's node fields."""
85
+ warnings: tuple[str, ...] = ()
86
+ wanted: set[str] | None = None
87
+ if type_name is not None:
88
+ wanted = _with_subtypes(index, type_name)
89
+ if not any(node["type"] in wanted for node in index.nodes.values()) and not (
90
+ index.parent(type_name) or index.subtypes(type_name)
91
+ ):
92
+ warnings = (f"no type named {type_name!r} is in the map; periplus types lists them",)
93
+ needle = text.casefold()
94
+ ranked = []
95
+ for node_id, node in index.nodes.items():
96
+ rank = _rank(as_text(node_id), needle)
97
+ if rank is not None and (wanted is None or node["type"] in wanted):
98
+ ranked.append((rank, node_id, node))
99
+ ranked.sort(key=lambda row: (row[0], row[1]))
100
+ rows = [
101
+ {
102
+ "id": i,
103
+ "type": as_text(n["type"]),
104
+ "state": as_text(n["state"]),
105
+ "location": _location(n),
106
+ }
107
+ for _, i, n in ranked
108
+ ]
109
+ return FindReport(cut(rows, limit), warnings)
110
+
111
+
112
+ def render_text(report: FindReport) -> str:
113
+ """The report as lines a person reads. Every outside string goes through ``_escape``."""
114
+ lines = ["periplus find", ""]
115
+ for row in report.matches.items:
116
+ where = row["location"] or "no location"
117
+ lines.append(
118
+ f"{_escape(row['id'])} {_escape(row['type'])}"
119
+ f" {_escape(row['state'])} {_escape(where)}"
120
+ )
121
+ if not report.matches.items:
122
+ lines.append("no matches")
123
+ note = footer(report.matches)
124
+ lines += [note] if note else []
125
+ lines += [f"warning: {_escape(w)}" for w in report.warnings]
126
+ lines += [f"{int(p.code)} {_escape(p.message)}" for p in report.problems]
127
+ return "\n".join(lines) + "\n"
128
+
129
+
130
+ def render_json(report: FindReport) -> str:
131
+ """The report as one JSON document, keys sorted, ``ensure_ascii=True``."""
132
+ document = {
133
+ **payload(report.matches),
134
+ "warnings": list(report.warnings),
135
+ "problems": [
136
+ {"code": int(p.code), "message": p.message, "detail": dict(p.detail)}
137
+ for p in report.problems
138
+ ],
139
+ }
140
+ return json.dumps(document, sort_keys=True, indent=2, ensure_ascii=True) + "\n"
141
+
142
+
143
+ RENDERERS = {"text": render_text, "json": render_json}
@@ -0,0 +1,30 @@
1
+ """Resolve a node id a person pasted from ``periplus find`` output."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+
7
+ from periplus.navigate.mapfile import MapIndex
8
+
9
+ _ESCAPE = re.compile(r"\\(?:(\\)|n|r|t|x([0-9a-f]{2})|u([0-9a-f]{4}))")
10
+ _SIMPLE = {"n": "\n", "r": "\r", "t": "\t"}
11
+
12
+
13
+ def _unescape(text: str) -> str:
14
+ """The inverse of ``report._escape``, in one pass so a produced escape is not read twice."""
15
+
16
+ def one(match: re.Match[str]) -> str:
17
+ if match.group(1):
18
+ return "\\"
19
+ hexa = match.group(2) or match.group(3)
20
+ return chr(int(hexa, 16)) if hexa else _SIMPLE[match.group(0)[1]]
21
+
22
+ return _ESCAPE.sub(one, text)
23
+
24
+
25
+ def resolve(index: MapIndex, text: str) -> str:
26
+ """The id as given when the map holds it, else the id the escaped form stands for."""
27
+ if text in index.nodes:
28
+ return text
29
+ unescaped = _unescape(text)
30
+ return unescaped if unescaped in index.nodes else text
@@ -0,0 +1,42 @@
1
+ """The cut-list envelope every list-returning navigation command shares."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Sequence
6
+ from dataclasses import dataclass
7
+ from typing import Any
8
+
9
+ __all__ = ["Listing", "cut", "footer", "payload"]
10
+
11
+
12
+ @dataclass(frozen=True, slots=True)
13
+ class Listing:
14
+ """Some items of a longer list: what is shown, how many there were, and whether it was cut."""
15
+
16
+ items: tuple[Any, ...]
17
+ total: int
18
+ shown: int
19
+ truncated: bool
20
+
21
+
22
+ def cut(items: Sequence[Any], limit: int) -> Listing:
23
+ """The first ``limit`` items, in the order given. A limit of 0 keeps every item."""
24
+ if limit < 0:
25
+ raise ValueError(f"limit must be 0 or more, not {limit}")
26
+ kept = tuple(items) if limit == 0 else tuple(items[:limit])
27
+ return Listing(items=kept, total=len(items), shown=len(kept), truncated=len(kept) < len(items))
28
+
29
+
30
+ def payload(listing: Listing) -> dict[str, Any]:
31
+ """The JSON fragment for a listing: ``items``, ``total``, ``shown`` and ``truncated``."""
32
+ return {
33
+ "items": list(listing.items),
34
+ "total": listing.total,
35
+ "shown": listing.shown,
36
+ "truncated": listing.truncated,
37
+ }
38
+
39
+
40
+ def footer(listing: Listing) -> str | None:
41
+ """``showing N of M`` when the list was cut, and ``None`` when nothing was left out."""
42
+ return f"showing {listing.shown} of {listing.total}" if listing.truncated else None