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/settings.py ADDED
@@ -0,0 +1,617 @@
1
+ """Settings resolution: finding the two files, reading one, and merging them key by key.
2
+
3
+ Three separable questions, and they are three functions because they fail independently.
4
+ ``locate_settings`` decides *which files apply* and opens nothing, so a file that exists and will
5
+ not parse can be reported as skipped rather than silently becoming absent.
6
+ ``load_settings_document`` decides *what is in one file* and knows nothing about layers.
7
+ ``resolve_settings`` decides *what wins* and reads no filesystem — it takes documents and
8
+ sources as arguments, which is what lets the whole cascade be tested against constructed values.
9
+
10
+ This is the first module in the package to import a runtime distribution. ``ruamel.yaml`` and
11
+ ``platformdirs`` are both imported at module level here, deliberately and visibly: nothing on
12
+ ``cli``'s module-level import path may reach this file, which is the property
13
+ ``tests/test_console_script.py`` asserts by importing ``periplus.cli`` with both distributions
14
+ blocked. Before this module existed that test could only fail if somebody imported a distribution
15
+ for no reason. From here on it protects something real, because ``cli`` importing ``settings`` at
16
+ module level would break the startup check that names a missing dependency.
17
+
18
+ What this module does not do, because a later component does it:
19
+
20
+ * It does not substitute a brace in a folder value, join a folder to a root, or check that any path
21
+ exists. A ``folders`` value leaves here as written: one template string, or a tuple of them
22
+ for a list. That is the input of a later folder resolver, which is not built yet.
23
+ * It does not parse a ``packs:`` pin into a name and a version, list a directory, or decide whether
24
+ a pack root exists. Pins leave here as the strings the file wrote. That is ``packs.py``.
25
+ * It does not decide whether a failure ends the run, and it does not catch its own exception.
26
+ ``resolution.py`` catches ``SettingsUnreadable`` and turns it into a ``Problem`` and a skipped
27
+ source; the "neither file exists" condition is invisible here, because this module is handed
28
+ documents rather than finding them.
29
+ * It validates nothing, by design. What it does do is refuse to *lie*
30
+ about a type: a value whose shape does not match the key's declared type is dropped rather than
31
+ coerced into a tuple of characters. See ``MERGE_RULES``.
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+ import os
37
+ from collections.abc import Callable, Mapping, Sequence
38
+ from dataclasses import dataclass
39
+ from pathlib import Path
40
+ from typing import Any, Generic, Literal, TypeVar
41
+
42
+ import platformdirs
43
+ from ruamel.yaml import YAML
44
+ from ruamel.yaml.error import YAMLError
45
+
46
+ from periplus.errors import ExitCode, HarnessError
47
+
48
+ # Re-exported, so every caller that imported these from here still can. The redundant alias is
49
+ # the explicit re-export form, and it is what tells the linter the names are deliberate.
50
+ from periplus.layout import PACKS_DIRECTORY as PACKS_DIRECTORY
51
+ from periplus.layout import PROJECT_MARKER as PROJECT_MARKER
52
+ from periplus.layout import SETTINGS_FILENAME as SETTINGS_FILENAME
53
+
54
+ __all__ = [
55
+ "MERGE_RULES",
56
+ "FirstParty",
57
+ "ResolvedSetting",
58
+ "ResolvedSettings",
59
+ "SettingsSource",
60
+ "SettingsUnreadable",
61
+ "SourceRef",
62
+ "find_project_root",
63
+ "load_settings_document",
64
+ "locate_settings",
65
+ "resolve_settings",
66
+ "user_config_dir",
67
+ ]
68
+
69
+ T = TypeVar("T")
70
+
71
+ # Three vocabularies are written out at every annotation rather than named once as a module-level
72
+ # alias, which is not the arrangement anyone would choose. A `Literal` alias cannot be verified in
73
+ # an inline-typed package: mypy normalises `Literal["user", "project"]` into a union of two
74
+ # literals, the runtime object is one `_LiteralGenericAlias` and not a union, so a tool that
75
+ # compares the declared types against the imported module reports `SourceKind is not a Union` on a
76
+ # module that is correct. Measured with `mypy.stubtest` on 2026-08-30 — that run was the evidence
77
+ # for this shape, not a check holding it in place; nothing in this project runs stubtest. A leading
78
+ # underscore does not exempt the alias.
79
+ #
80
+ # the two layers that are settings files Literal["user", "project"]
81
+ # A third — a `folders` block inside a pack manifest — would arrive as one more member.
82
+ # what happened to one layer's file Literal["used", "absent", "skipped"]
83
+ # `skipped` is set by the caller that catches a parse failure, never here: the difference
84
+ # between "there is no file" and "there is a file I could not read" is the whole reason
85
+ # locating and loading are two functions.
86
+ # how one settings key merges Literal["replace", "union", "accumulate", "per_key",
87
+ # "paired"]
88
+
89
+
90
+ #: The environment variable that replaces the user configuration directory outright.
91
+ CONFIG_DIR_VARIABLE = "PERIPLUS_CONFIG_DIR"
92
+
93
+
94
+ @dataclass(frozen=True, slots=True)
95
+ class SourceRef:
96
+ """Which settings file an effective value came from, as it is printed beside that value."""
97
+
98
+ kind: Literal["user", "project"]
99
+ name: str
100
+
101
+
102
+ @dataclass(frozen=True, slots=True)
103
+ class SettingsSource:
104
+ """One layer's file: where it is, what a relative path in it means, and what happened to it.
105
+
106
+ ``root`` carries the anchor rather than leaving it to be derived, which is what makes "a
107
+ relative path resolves against the root of the file that declared it" structural instead of a
108
+ rule the merge has to remember. The two layers do not derive it the same way — the project
109
+ file's root is its grandparent, because the file is ``<root>/.periplus/settings.yml``, and the
110
+ user file's root is its parent — and an explicit ``--settings PATH`` breaks both derivations.
111
+ Computing it once where the file is located removes the question from every later reader.
112
+ """
113
+
114
+ kind: Literal["user", "project"]
115
+ path: Path
116
+ root: Path
117
+ status: Literal["used", "absent", "skipped"]
118
+ reason: str | None
119
+
120
+ def ref(self) -> SourceRef:
121
+ """This source as the reference an effective value carries.
122
+
123
+ The one place a ``SourceRef.name`` is built from a path, so the two cannot drift.
124
+ """
125
+ return SourceRef(kind=self.kind, name=str(self.path))
126
+
127
+
128
+ @dataclass(frozen=True, slots=True)
129
+ class ResolvedSetting(Generic[T]):
130
+ """An effective value and every file that had a say in it.
131
+
132
+ There is no way to hold a value without holding where it came from, which is what makes
133
+ research's visibility requirement structural rather than a convention.
134
+
135
+ ``sources`` is in cascade order — user first, then project. A key merged by replacement carries
136
+ exactly one entry, the file that won. A key merged by accumulation carries one entry per file
137
+ that declared it, including a file that declared it empty: presence is what makes a file a
138
+ source, not whether its contribution changed the answer.
139
+
140
+ ``sources`` attributes the *key* and not the *entries in it*, and for a key that accumulates
141
+ those are different facts. Given a ``pack_paths`` of ``(pathA, pathB)`` and a ``sources`` of
142
+ ``(user, project)``, nothing says which file added which path — so ``packs.py``'s
143
+ ``PackRoot.source``, "which settings file added a configured root", would have to guess, and
144
+ would guess plausibly and silently. ``entry_sources`` is that missing fact: one ``SourceRef``
145
+ per element of ``value``, in the same order, for the keys that accumulate. It is ``None`` for
146
+ every other key, which says "there is nothing per-entry to say here" rather than repeating one
147
+ file N times — a replace key's entries all came from the one file ``sources`` already names.
148
+
149
+ One reference per entry, in the same order, holds by construction rather than by a check.
150
+ ``_merge_sequence`` is the only code that builds a non-``None`` ``entry_sources``, and it
151
+ appends to ``values`` and to ``entry_sources`` in one loop body, so the two cannot come out of
152
+ step. A later builder that does not append in lockstep carries that check itself: the defect is
153
+ an ``entry_sources`` short by one, which type-checks, reads correctly, and reaches a report as
154
+ a misattribution rather than as a crash.
155
+
156
+ One gap this does not close, stated so it is not mistaken for closed: ``first_party``
157
+ accumulates two lists inside one ``FirstParty`` value, so a flat tuple of the same length as
158
+ ``value`` cannot describe it. Its ``entry_sources`` is ``None``, and per-entry attribution for
159
+ its two lists is unavailable. ``pack_paths`` is the key that needs it.
160
+ """
161
+
162
+ value: T
163
+ sources: tuple[SourceRef, ...]
164
+ entry_sources: tuple[SourceRef, ...] | None = None
165
+
166
+
167
+ @dataclass(frozen=True, slots=True)
168
+ class FirstParty:
169
+ """The two path-pattern lists that decide where the codebase ends and its dependencies begin.
170
+
171
+ Both accumulate across layers, so this is one setting holding two lists rather than two
172
+ settings — ``ResolvedSetting[FirstParty]`` — and it means the sources are the files that
173
+ contributed to either list.
174
+ """
175
+
176
+ include: tuple[str, ...]
177
+ exclude: tuple[str, ...]
178
+
179
+
180
+ @dataclass(frozen=True, slots=True)
181
+ class ResolvedSettings:
182
+ """Every settings key, merged, with its sources. A key no file declared is ``None``.
183
+
184
+ ``None`` rather than an empty tuple or a machine default, because a key that fell through to
185
+ nothing is exactly the case the output has to make visible: the cascade deliberately does not
186
+ forbid it, and a fabricated default would print as though somebody had chosen it.
187
+
188
+ ``folders`` and ``extensions`` are mappings rather than optionals for the same reason in the
189
+ opposite direction — an empty mapping already says "no folder was declared anywhere", and
190
+ wrapping it in an optional would give two ways to write the same fact.
191
+ """
192
+
193
+ periplus_version: ResolvedSetting[int] | None
194
+ packs: ResolvedSetting[tuple[str, ...]] | None
195
+ pack_paths: ResolvedSetting[tuple[Path, ...]] | None
196
+ folders: Mapping[str, ResolvedSetting[str | tuple[str, ...]]]
197
+ extensions: Mapping[str, ResolvedSetting[str]]
198
+ first_party: ResolvedSetting[FirstParty] | None
199
+ exclude: ResolvedSetting[tuple[str, ...]] | None
200
+ re_include: ResolvedSetting[tuple[str, ...]] | None
201
+ accepted_unknowns: ResolvedSetting[tuple[Mapping[str, object], ...]] | None
202
+ #: The named text values every template of every pack may name, merged as ``extensions`` is.
203
+ values: Mapping[str, ResolvedSetting[str]]
204
+
205
+
206
+ class SettingsUnreadable(HarnessError):
207
+ """A settings file exists and could not be turned into a mapping.
208
+
209
+ One class for four causes — the bytes could not be read, they could not be decoded, the parser
210
+ refused them, or the document parsed into something that is not a mapping — because they are one
211
+ thing to do about it: open the file and fix it. ``detail`` names which one it was.
212
+
213
+ This is the only ``HarnessError`` subclass this module ships. There is deliberately no
214
+ ``SettingsNotFound``: this module never sees the "neither file exists" condition, because it
215
+ takes documents and sources as arguments. That detection belongs to ``resolution.py``.
216
+ """
217
+
218
+ code = ExitCode.UNREADABLE_SETTINGS
219
+
220
+
221
+ def find_project_root(start: Path) -> Path | None:
222
+ """The nearest directory at or above ``start`` that holds a ``.periplus/`` directory.
223
+
224
+ Lexical, and never ``resolve()``d. Following a symlink here would report a project root the
225
+ person never wrote and never navigated through, and the walk would leave the tree it was asked
226
+ about. ``Path.parents`` is a lexical sequence, so a symlinked parent cannot send the walk
227
+ somewhere unrelated; it stops at the filesystem root and returns ``None``.
228
+
229
+ The marker is a directory, not a file, for the reason ``git`` looks for ``.git`` — the same
230
+ directory holds the settings file and the project's own packs, so one marker answers both.
231
+ """
232
+ for directory in (start, *start.parents):
233
+ if (directory / PROJECT_MARKER).is_dir():
234
+ return directory
235
+ return None
236
+
237
+
238
+ def user_config_dir(env: Mapping[str, str]) -> Path:
239
+ """Periplus' own configuration directory — ``~/.config/periplus`` on Linux, not ``~/.config``.
240
+
241
+ One function returns one level whichever branch produced it, which is what
242
+ ``PERIPLUS_CONFIG_DIR`` forces: a variable named for this tool cannot sensibly point at the
243
+ directory holding every tool's configuration. So the user settings file is
244
+ ``<user config dir>/settings.yml`` and the user pack root is ``<user config dir>/packs/``, with
245
+ no ``periplus`` segment appended by us.
246
+
247
+ The environment is an argument rather than something this function reads, so a test moves the
248
+ user layer without monkeypatching a module — and what it reads out of that argument is
249
+ ``PERIPLUS_CONFIG_DIR`` alone. Everything else is ``platformdirs``, which reads the process
250
+ environment itself: ``XDG_CONFIG_HOME`` on POSIX, ``%APPDATA%`` on Windows,
251
+ ``~/Library/Application Support`` on macOS. Verified 2026-08-30 against platformdirs 4.11.5 that
252
+ ``user_config_dir()`` accepts no environment argument and reads ``os.environ`` at
253
+ ``unix.py:326``, so an ``XDG_CONFIG_HOME`` passed through this mapping would be read by nothing
254
+ and offering it would be a decoration on the one variable that matters.
255
+
256
+ ``appauthor=False`` is load-bearing on Windows and inert everywhere else: left at ``None``,
257
+ platformdirs uses the app name as the author directory and returns
258
+ ``%APPDATA%\\periplus\\periplus``.
259
+ """
260
+ override = env.get(CONFIG_DIR_VARIABLE)
261
+ if override:
262
+ return Path(override)
263
+ return Path(platformdirs.user_config_dir("periplus", appauthor=False))
264
+
265
+
266
+ def locate_settings(
267
+ project_root: Path | None,
268
+ user_config_dir: Path | None,
269
+ settings_path: Path | None = None,
270
+ ) -> tuple[SettingsSource, ...]:
271
+ """One record per layer whose file location is knowable, in cascade order: user, then project.
272
+
273
+ Opens nothing. A layer whose file is not there comes back ``absent`` rather than being left out,
274
+ because the report has to name the file it did not find.
275
+
276
+ A layer appears at all only when its location can be named. ``user_config_dir=None`` means the
277
+ user layer was not consulted, and a project layer with neither a root nor an explicit file has
278
+ no path to report as absent.
279
+
280
+ The project source's root is ``project_root`` when one is given, and otherwise derived from
281
+ ``settings_path`` by one rule: a file at ``X/.periplus/settings.yml`` anchors to ``X``,
282
+ and any other file anchors to its own directory. So the contract for the caller is one line —
283
+ pass the root when something decided it, and pass ``settings_path`` with ``project_root=None``
284
+ to get the ``--settings`` rule. Deciding between ``--project-root``, ``--settings`` and the walk
285
+ is the caller's, because only it knows which flag the person typed.
286
+ """
287
+ sources: list[SettingsSource] = []
288
+
289
+ if user_config_dir is not None:
290
+ sources.append(_source("user", user_config_dir / SETTINGS_FILENAME, user_config_dir))
291
+
292
+ if settings_path is not None:
293
+ sources.append(_source("project", settings_path, project_root or _anchor_of(settings_path)))
294
+ elif project_root is not None:
295
+ path = project_root / PROJECT_MARKER / SETTINGS_FILENAME
296
+ sources.append(_source("project", path, project_root))
297
+
298
+ return tuple(sources)
299
+
300
+
301
+ def _anchor_of(settings_path: Path) -> Path:
302
+ """The project root an explicitly named settings file implies.
303
+
304
+ A file at ``X/.periplus/settings.yml`` fixes the root at ``X``, so a person pointing
305
+ at a real project's file gets that project's root and the two can never disagree. Any other file
306
+ anchors to its own directory, which is the only answer available and the one that keeps a
307
+ relative ``pack_paths`` entry beside the file that wrote it.
308
+ """
309
+ parent = settings_path.parent
310
+ return parent.parent if parent.name == PROJECT_MARKER else parent
311
+
312
+
313
+ def _source(kind: Literal["user", "project"], path: Path, root: Path) -> SettingsSource:
314
+ """One located layer. ``is_file()`` is the only filesystem call; the file is not opened."""
315
+ return SettingsSource(
316
+ kind=kind,
317
+ path=path,
318
+ root=root,
319
+ status="used" if path.is_file() else "absent",
320
+ reason=None,
321
+ )
322
+
323
+
324
+ def load_settings_document(path: Path) -> Mapping[str, object]:
325
+ """Read one settings file into a mapping, or raise ``SettingsUnreadable``.
326
+
327
+ ``YAML(typ='safe', pure=True)``. ``safe`` refuses arbitrary object construction and is YAML 1.2,
328
+ which is the whole reason ruamel is here rather than PyYAML: verified 2026-08-30 on 0.19.1, a
329
+ duplicate key raises where PyYAML keeps the last value silently, and ``12:30``, ``on``, ``yes``
330
+ and ``no`` stay the strings they were written as, where PyYAML makes the first of those the
331
+ integer 750. ``pure`` pins the pure-Python parser, which ruamel would otherwise swap for the C
332
+ one whenever the optional ``ruamel.yaml.clib`` extension happens to be importable — an
333
+ environment-dependent branch in a tool that promises output that is byte-identical
334
+ across machines.
335
+
336
+ One ``except`` covers every parser refusal, because ``DuplicateKeyError``, ``ParserError`` and
337
+ ``ScannerError`` all subclass ``YAMLError``; the parser's own message, marks and all, goes into
338
+ ``detail`` rather than into the one line a person reads.
339
+
340
+ ``OSError`` and ``UnicodeDecodeError`` are caught for the same exit code, because exit 4
341
+ means "a settings file could not be read **or** parsed", and a person gets a named
342
+ failure rather than a traceback. A settings file that is a directory, or unreadable, or holds
343
+ bytes that are not UTF-8, reaches a person as a line naming the file.
344
+
345
+ An empty file loads as ``None`` and a scalar or a list document loads as a ``str`` or a
346
+ ``list``. All three are valid YAML that is not a settings file, and all three are exit 4 — the
347
+ check is here rather than in the parser because no parser has an opinion about it.
348
+
349
+ Keys are not checked. A key the settings schema does not name is ignored by the merge without
350
+ comment, whatever its type, because this module validates nothing.
351
+ """
352
+ yaml = YAML(typ="safe", pure=True)
353
+ try:
354
+ with path.open("r", encoding="utf-8") as stream:
355
+ document = yaml.load(stream)
356
+ except YAMLError as error:
357
+ raise SettingsUnreadable(
358
+ f"the settings file could not be parsed: {path}",
359
+ {"path": str(path), "cause": "parser", "detail": str(error)},
360
+ ) from error
361
+ except UnicodeDecodeError as error:
362
+ raise SettingsUnreadable(
363
+ f"the settings file is not valid UTF-8: {path}",
364
+ {"path": str(path), "cause": "encoding", "detail": str(error)},
365
+ ) from error
366
+ except OSError as error:
367
+ raise SettingsUnreadable(
368
+ f"the settings file could not be read: {path}",
369
+ {"path": str(path), "cause": "read", "detail": str(error)},
370
+ ) from error
371
+
372
+ if not isinstance(document, Mapping):
373
+ raise SettingsUnreadable(
374
+ f"the settings file is not a mapping: {path}",
375
+ {"path": str(path), "cause": "shape", "detail": type(document).__name__},
376
+ )
377
+ return document
378
+
379
+
380
+ def _as_int(value: object) -> int | None:
381
+ """An integer, and not a ``bool`` wearing one. ``periplus_version: true`` is not version 1."""
382
+ if isinstance(value, bool):
383
+ return None
384
+ return value if isinstance(value, int) else None
385
+
386
+
387
+ def _as_strings(value: object) -> tuple[str, ...] | None:
388
+ """A list of strings, all of them, or nothing at all."""
389
+ if isinstance(value, list | tuple) and all(isinstance(item, str) for item in value):
390
+ return tuple(value)
391
+ return None
392
+
393
+
394
+ def _as_string_mapping(value: object) -> Mapping[str, str] | None:
395
+ """A mapping of string to string, all of them, or nothing at all."""
396
+ if isinstance(value, Mapping) and all(
397
+ isinstance(key, str) and isinstance(item, str) for key, item in value.items()
398
+ ):
399
+ return dict(value)
400
+ return None
401
+
402
+
403
+ def _as_folder_mapping(value: object) -> Mapping[str, str | tuple[str, ...]] | None:
404
+ """A mapping of string to a string or a non-empty list of strings, all of them, or nothing."""
405
+ if isinstance(value, Mapping) and all(
406
+ isinstance(key, str)
407
+ and (
408
+ isinstance(item, str)
409
+ or (isinstance(item, list) and item and _as_strings(item) is not None)
410
+ )
411
+ for key, item in value.items()
412
+ ):
413
+ return {key: item if isinstance(item, str) else tuple(item) for key, item in value.items()}
414
+ return None
415
+
416
+
417
+ def _as_mappings(value: object) -> tuple[Mapping[str, object], ...] | None:
418
+ """A list of string-keyed mappings, whatever their values are.
419
+
420
+ The values are deliberately not required to be strings. An ``accepted_unknowns`` entry's
421
+ ``accepted_on`` is a date, and an unquoted ``2026-08-28`` loads as a ``datetime.date`` under
422
+ ``typ='safe'`` — measured, not assumed. Requiring ``str`` here would silently delete a
423
+ legitimate entry from a person's file to satisfy a type annotation.
424
+ """
425
+ if isinstance(value, list | tuple) and all(
426
+ isinstance(item, Mapping) and all(isinstance(key, str) for key in item) for item in value
427
+ ):
428
+ return tuple(dict(item) for item in value)
429
+ return None
430
+
431
+
432
+ def _as_first_party(value: object) -> FirstParty | None:
433
+ """A ``first_party`` block. A missing or malformed half is an empty list, not a refusal."""
434
+ if not isinstance(value, Mapping):
435
+ return None
436
+ return FirstParty(
437
+ include=_as_strings(value.get("include", [])) or (),
438
+ exclude=_as_strings(value.get("exclude", [])) or (),
439
+ )
440
+
441
+
442
+ @dataclass(frozen=True, slots=True)
443
+ class _Rule:
444
+ """How one settings key merges across layers, and what shape its value has to be.
445
+
446
+ ``coerce`` is part of the rule rather than a step beside it, because the two are one decision:
447
+ the behaviour says which contributions combine and the coercion says which ones count. A
448
+ contribution the coercion rejects is dropped exactly like a key the schema does not name.
449
+ """
450
+
451
+ behaviour: Literal["replace", "union", "accumulate", "per_key", "paired"]
452
+ coerce: Callable[[object], Any]
453
+ anchor: bool = False
454
+
455
+
456
+ #: The merge rule for every key the settings schema names, keyed by the name. Data, not branches:
457
+ #: a new key in the settings schema is a row here and a field on ``ResolvedSettings``, never a
458
+ #: condition inside the merge.
459
+ #:
460
+ #: "Scalars — last wins" and "``packs`` — replace" are
461
+ #: one operation: take the last file that declared the key. One row kind, two names in prose.
462
+ #:
463
+ #: Only ``pack_paths`` sets ``anchor``, which turns each relative string into a path under the root
464
+ #: of the file that declared it. ``folders`` values are templates that a later folder resolver will
465
+ #: join to the project root, so they are stored exactly as written, braces intact.
466
+ MERGE_RULES: Mapping[str, _Rule] = {
467
+ "periplus_version": _Rule("replace", _as_int),
468
+ "packs": _Rule("replace", _as_strings),
469
+ "pack_paths": _Rule("union", _as_strings, anchor=True),
470
+ "folders": _Rule("per_key", _as_folder_mapping),
471
+ "extensions": _Rule("per_key", _as_string_mapping),
472
+ "first_party": _Rule("paired", _as_first_party),
473
+ "exclude": _Rule("accumulate", _as_strings),
474
+ "re_include": _Rule("accumulate", _as_strings),
475
+ "accepted_unknowns": _Rule("accumulate", _as_mappings),
476
+ "values": _Rule("per_key", _as_string_mapping),
477
+ }
478
+
479
+
480
+ def _anchor_path(root: Path, value: str) -> Path:
481
+ """``value`` as an absolute path under ``root``, normalised lexically and never resolved.
482
+
483
+ An absolute entry is kept exactly as written. A relative one is joined and normalised with
484
+ ``os.path.normpath``, which collapses ``..`` textually; ``Path.resolve()`` would follow a
485
+ symlink and print a directory the person never named.
486
+ """
487
+ candidate = Path(value)
488
+ if candidate.is_absolute():
489
+ return candidate
490
+ return Path(os.path.normpath(root / candidate))
491
+
492
+
493
+ def _merge_key(
494
+ name: str, rule: _Rule, layers: Sequence[tuple[SettingsSource, Mapping[str, object]]]
495
+ ) -> Any: # noqa: ANN401 - the return type is the field's, and the field declares it
496
+ """Merge one key across every layer that declared it, in cascade order.
497
+
498
+ Returns ``None`` for a key no layer declared, except under ``per_key``, where the empty mapping
499
+ already says it.
500
+ """
501
+ contributions = [
502
+ (source, coerced)
503
+ for source, document in layers
504
+ if name in document and (coerced := rule.coerce(document[name])) is not None
505
+ ]
506
+
507
+ if rule.behaviour == "per_key":
508
+ return _merge_per_key(contributions)
509
+ if not contributions:
510
+ return None
511
+ if rule.behaviour == "replace":
512
+ source, value = contributions[-1]
513
+ return ResolvedSetting(value=value, sources=(source.ref(),))
514
+ if rule.behaviour == "paired":
515
+ return ResolvedSetting(
516
+ value=FirstParty(
517
+ include=tuple(item for _, value in contributions for item in value.include),
518
+ exclude=tuple(item for _, value in contributions for item in value.exclude),
519
+ ),
520
+ sources=tuple(source.ref() for source, _ in contributions),
521
+ )
522
+ return _merge_sequence(contributions, rule)
523
+
524
+
525
+ def _merge_per_key(
526
+ contributions: Sequence[tuple[SettingsSource, Mapping[str, str]]],
527
+ ) -> Mapping[str, ResolvedSetting[str]]:
528
+ """A mapping merged entry by entry: for each name, the last layer that declared *that name*.
529
+
530
+ Each entry carries the one file that won it, which is what makes the fell-through case visible —
531
+ a name only the user file declares survives into the result carrying the user file as its
532
+ source, beside a name the project file overrode carrying the project file.
533
+
534
+ Sorted by name. ``report.py`` sorts everything it prints, but this mapping is a value a second
535
+ consumer can hold, and a mapping that reaches anyone in the order a YAML file happened to be
536
+ written in is a determinism defect waiting for a consumer that does not sort.
537
+ """
538
+ merged: dict[str, ResolvedSetting[str]] = {}
539
+ for source, mapping in contributions:
540
+ for name, value in mapping.items():
541
+ merged[name] = ResolvedSetting(value=value, sources=(source.ref(),))
542
+ return dict(sorted(merged.items()))
543
+
544
+
545
+ def _merge_sequence(
546
+ contributions: Sequence[tuple[SettingsSource, tuple[Any, ...]]], rule: _Rule
547
+ ) -> ResolvedSetting[tuple[Any, ...]]:
548
+ """Concatenate every layer's list in cascade order.
549
+
550
+ ``union`` drops a repeat and ``accumulate`` keeps it, and the difference is not cosmetic.
551
+ ``pack_paths`` names directories to search: the same directory reached from two files is one
552
+ place to look, and listing it twice would make one pack directory match a pin under two roots
553
+ and fail the run at exit 6 for a duplicate that does not exist. ``exclude`` and ``re_include``
554
+ are ordered patterns where a repeat costs nothing and removing one would quietly reorder the
555
+ rest.
556
+
557
+ De-duplication keeps the first occurrence, so the earliest layer that named a path fixes its
558
+ position, and every layer that named it stays in ``sources``. It is also the layer the surviving
559
+ entry is attributed to: a directory both files name was added by the earlier one, and the later
560
+ one changed nothing about where it sits in the search order.
561
+
562
+ ``entry_sources`` is built here, in the loop, and not derived afterwards. The declaring source
563
+ is in hand at the moment each item is appended and nowhere else; once the values are
564
+ concatenated the fact is gone. That is why per-entry attribution cannot be added to a merge
565
+ that did not collect it.
566
+ """
567
+ values: list[Any] = []
568
+ entry_sources: list[SourceRef] = []
569
+ for source, value in contributions:
570
+ for item in value:
571
+ item = _anchor_path(source.root, item) if rule.anchor else item
572
+ if rule.behaviour == "union" and item in values:
573
+ continue
574
+ values.append(item)
575
+ entry_sources.append(source.ref())
576
+ return ResolvedSetting(
577
+ value=tuple(values),
578
+ sources=tuple(source.ref() for source, _ in contributions),
579
+ entry_sources=tuple(entry_sources),
580
+ )
581
+
582
+
583
+ def resolve_settings(
584
+ user: Mapping[str, object] | None,
585
+ project: Mapping[str, object] | None,
586
+ sources: Sequence[SettingsSource],
587
+ ) -> ResolvedSettings:
588
+ """Merge the layers into one record where every effective value names the files behind it.
589
+
590
+ The cascade is ``sources``' own order rather than a hardcoded user-then-project, so the order
591
+ ``locate_settings`` returns is the order that applies and can be tested by reordering it.
592
+
593
+ A document is paired with the source of its own ``kind``, which is where a relative path in it
594
+ gets its anchor from. A layer contributes only when both halves are present: a ``used`` source
595
+ with no document, and a document for a layer that has no ``used`` source, are each skipped.
596
+ Neither can come from a person's input — only from wiring — and ``resolution.py``, the one
597
+ caller, builds this mapping from the same ``sources`` tuple it passes in.
598
+ """
599
+ documents: dict[str, Mapping[str, object] | None] = {"user": user, "project": project}
600
+ layers = [
601
+ (source, document)
602
+ for source in sources
603
+ if source.status == "used" and (document := documents[source.kind]) is not None
604
+ ]
605
+ merged = {name: _merge_key(name, rule, layers) for name, rule in MERGE_RULES.items()}
606
+ return ResolvedSettings(
607
+ periplus_version=merged["periplus_version"],
608
+ packs=merged["packs"],
609
+ pack_paths=merged["pack_paths"],
610
+ folders=merged["folders"],
611
+ extensions=merged["extensions"],
612
+ first_party=merged["first_party"],
613
+ exclude=merged["exclude"],
614
+ re_include=merged["re_include"],
615
+ accepted_unknowns=merged["accepted_unknowns"],
616
+ values=merged["values"],
617
+ )