@wildo-ai/platform-config-lib 1.1.10 → 1.1.11

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 (231) hide show
  1. package/dist/esm/_unimplemented/unimplemented-field-warning.d.ts +1 -1
  2. package/dist/esm/_unimplemented/unimplemented-field-warning.js +1 -1
  3. package/dist/esm/_unimplemented/unimplemented-field-warning.js.map +1 -1
  4. package/dist/esm/blueprint/anchored-region.d.ts +83 -0
  5. package/dist/esm/blueprint/anchored-region.d.ts.map +1 -0
  6. package/dist/esm/blueprint/anchored-region.js +263 -0
  7. package/dist/esm/blueprint/anchored-region.js.map +1 -0
  8. package/dist/esm/blueprint/blueprint.schemas.d.ts +689 -0
  9. package/dist/esm/blueprint/blueprint.schemas.d.ts.map +1 -0
  10. package/dist/esm/blueprint/blueprint.schemas.js +638 -0
  11. package/dist/esm/blueprint/blueprint.schemas.js.map +1 -0
  12. package/dist/esm/bootstrap/application-backend-env.contracts.d.ts.map +1 -1
  13. package/dist/esm/bootstrap/bootstrap-planner.d.ts.map +1 -1
  14. package/dist/esm/bootstrap/bootstrap.contracts.d.ts +13 -1
  15. package/dist/esm/bootstrap/bootstrap.contracts.d.ts.map +1 -1
  16. package/dist/esm/bootstrap/bootstrap.contracts.js +6 -0
  17. package/dist/esm/bootstrap/bootstrap.contracts.js.map +1 -1
  18. package/dist/esm/bootstrap/bootstrap.schemas.d.ts +21 -3
  19. package/dist/esm/bootstrap/bootstrap.schemas.d.ts.map +1 -1
  20. package/dist/esm/bootstrap/bootstrap.schemas.js +14 -3
  21. package/dist/esm/bootstrap/bootstrap.schemas.js.map +1 -1
  22. package/dist/esm/bootstrap/platform-runtime-env.contracts.d.ts +121 -0
  23. package/dist/esm/bootstrap/platform-runtime-env.contracts.d.ts.map +1 -1
  24. package/dist/esm/bootstrap/platform-runtime-env.contracts.js +129 -0
  25. package/dist/esm/bootstrap/platform-runtime-env.contracts.js.map +1 -1
  26. package/dist/esm/bootstrap/platform-store-preconnect.d.ts.map +1 -1
  27. package/dist/esm/bootstrap/runtime-backing-service-access.d.ts.map +1 -1
  28. package/dist/esm/bootstrap/runtime-network-policy.d.ts.map +1 -1
  29. package/dist/esm/bootstrap/runtime-network-topology.d.ts.map +1 -1
  30. package/dist/esm/bootstrap/runtime-platform-access.d.ts.map +1 -1
  31. package/dist/esm/bootstrap/runtime-principal.contracts.d.ts.map +1 -1
  32. package/dist/esm/bootstrap/runtime-response-integrity.d.ts +249 -0
  33. package/dist/esm/bootstrap/runtime-response-integrity.d.ts.map +1 -0
  34. package/dist/esm/bootstrap/runtime-response-integrity.js +353 -0
  35. package/dist/esm/bootstrap/runtime-response-integrity.js.map +1 -0
  36. package/dist/esm/bootstrap/runtime-secret-env.contracts.d.ts +32 -0
  37. package/dist/esm/bootstrap/runtime-secret-env.contracts.d.ts.map +1 -0
  38. package/dist/esm/bootstrap/runtime-secret-env.contracts.js +43 -0
  39. package/dist/esm/bootstrap/runtime-secret-env.contracts.js.map +1 -0
  40. package/dist/esm/bootstrap/runtime-topology.contracts.d.ts.map +1 -1
  41. package/dist/esm/bootstrap/wildo-owner-organization.contracts.d.ts.map +1 -1
  42. package/dist/esm/canonical-json/rfc8785-canonical-json.d.ts +51 -0
  43. package/dist/esm/canonical-json/rfc8785-canonical-json.d.ts.map +1 -0
  44. package/dist/esm/canonical-json/rfc8785-canonical-json.js +231 -0
  45. package/dist/esm/canonical-json/rfc8785-canonical-json.js.map +1 -0
  46. package/dist/esm/config-authoring.entry.d.ts.map +1 -1
  47. package/dist/esm/index.d.ts +15 -0
  48. package/dist/esm/index.d.ts.map +1 -1
  49. package/dist/esm/index.js +15 -0
  50. package/dist/esm/index.js.map +1 -1
  51. package/dist/esm/key-management/approval-seal-verifier.d.ts +216 -0
  52. package/dist/esm/key-management/approval-seal-verifier.d.ts.map +1 -0
  53. package/dist/esm/key-management/approval-seal-verifier.js +233 -0
  54. package/dist/esm/key-management/approval-seal-verifier.js.map +1 -0
  55. package/dist/esm/key-management/approval-seal.contracts.d.ts +131 -0
  56. package/dist/esm/key-management/approval-seal.contracts.d.ts.map +1 -0
  57. package/dist/esm/key-management/approval-seal.contracts.js +115 -0
  58. package/dist/esm/key-management/approval-seal.contracts.js.map +1 -0
  59. package/dist/esm/key-management/data-key.contracts.d.ts +108 -0
  60. package/dist/esm/key-management/data-key.contracts.d.ts.map +1 -0
  61. package/dist/esm/key-management/data-key.contracts.js +54 -0
  62. package/dist/esm/key-management/data-key.contracts.js.map +1 -0
  63. package/dist/esm/key-management/es256-jws.d.ts +60 -0
  64. package/dist/esm/key-management/es256-jws.d.ts.map +1 -0
  65. package/dist/esm/key-management/es256-jws.js +135 -0
  66. package/dist/esm/key-management/es256-jws.js.map +1 -0
  67. package/dist/esm/key-management/key-provider.spi.d.ts +151 -0
  68. package/dist/esm/key-management/key-provider.spi.d.ts.map +1 -0
  69. package/dist/esm/key-management/key-provider.spi.js +38 -0
  70. package/dist/esm/key-management/key-provider.spi.js.map +1 -0
  71. package/dist/esm/key-management/keyring-rotation.contracts.d.ts +93 -0
  72. package/dist/esm/key-management/keyring-rotation.contracts.d.ts.map +1 -0
  73. package/dist/esm/key-management/keyring-rotation.contracts.js +101 -0
  74. package/dist/esm/key-management/keyring-rotation.contracts.js.map +1 -0
  75. package/dist/esm/key-management/keyring-status.contracts.d.ts +66 -0
  76. package/dist/esm/key-management/keyring-status.contracts.d.ts.map +1 -0
  77. package/dist/esm/key-management/keyring-status.contracts.js +45 -0
  78. package/dist/esm/key-management/keyring-status.contracts.js.map +1 -0
  79. package/dist/esm/key-management/signature-request.contracts.d.ts +95 -0
  80. package/dist/esm/key-management/signature-request.contracts.d.ts.map +1 -0
  81. package/dist/esm/key-management/signature-request.contracts.js +96 -0
  82. package/dist/esm/key-management/signature-request.contracts.js.map +1 -0
  83. package/dist/esm/key-management/signing-log-export.contracts.d.ts +216 -0
  84. package/dist/esm/key-management/signing-log-export.contracts.d.ts.map +1 -0
  85. package/dist/esm/key-management/signing-log-export.contracts.js +268 -0
  86. package/dist/esm/key-management/signing-log-export.contracts.js.map +1 -0
  87. package/dist/esm/key-management/vault-custody.contracts.d.ts +55 -0
  88. package/dist/esm/key-management/vault-custody.contracts.d.ts.map +1 -0
  89. package/dist/esm/key-management/vault-custody.contracts.js +88 -0
  90. package/dist/esm/key-management/vault-custody.contracts.js.map +1 -0
  91. package/dist/esm/lockfile/file-lock-hold.d.ts.map +1 -1
  92. package/dist/esm/lockfile/lockfile-io.d.ts +7 -9
  93. package/dist/esm/lockfile/lockfile-io.d.ts.map +1 -1
  94. package/dist/esm/lockfile/lockfile-io.js +23 -22
  95. package/dist/esm/lockfile/lockfile-io.js.map +1 -1
  96. package/dist/esm/lockfile/materialize-infra-section.d.ts +17 -14
  97. package/dist/esm/lockfile/materialize-infra-section.d.ts.map +1 -1
  98. package/dist/esm/lockfile/materialize-infra-section.js +9 -9
  99. package/dist/esm/lockfile/materialize-infra-section.js.map +1 -1
  100. package/dist/esm/lockfile/wildo-saas-lock.shared.schemas.d.ts +26 -2
  101. package/dist/esm/lockfile/wildo-saas-lock.shared.schemas.d.ts.map +1 -1
  102. package/dist/esm/lockfile/wildo-saas-lock.shared.schemas.js +27 -2
  103. package/dist/esm/lockfile/wildo-saas-lock.shared.schemas.js.map +1 -1
  104. package/dist/esm/project-config/application-public-pricing-catalog.loader.d.ts.map +1 -1
  105. package/dist/esm/project-config/application-public-pricing-catalog.loader.js +9 -2
  106. package/dist/esm/project-config/application-public-pricing-catalog.loader.js.map +1 -1
  107. package/dist/esm/project-config/application-served-public-documents.loader.d.ts +26 -0
  108. package/dist/esm/project-config/application-served-public-documents.loader.d.ts.map +1 -0
  109. package/dist/esm/project-config/application-served-public-documents.loader.js +78 -0
  110. package/dist/esm/project-config/application-served-public-documents.loader.js.map +1 -0
  111. package/dist/esm/project-config/define-framework-config.d.ts.map +1 -1
  112. package/dist/esm/project-config/define-infra-env-config.d.ts +236 -15
  113. package/dist/esm/project-config/define-infra-env-config.d.ts.map +1 -1
  114. package/dist/esm/project-config/define-infra-env-config.js +104 -91
  115. package/dist/esm/project-config/define-infra-env-config.js.map +1 -1
  116. package/dist/esm/project-config/define-minion-config.d.ts.map +1 -1
  117. package/dist/esm/project-config/define-saas-config.d.ts +133 -3
  118. package/dist/esm/project-config/define-saas-config.d.ts.map +1 -1
  119. package/dist/esm/project-config/define-saas-config.js +170 -19
  120. package/dist/esm/project-config/define-saas-config.js.map +1 -1
  121. package/dist/esm/project-config/define-worker-config.d.ts.map +1 -1
  122. package/dist/esm/project-config/hosted-infra-env-config.d.ts.map +1 -1
  123. package/dist/esm/project-config/hosted-infra-env-config.js +3 -0
  124. package/dist/esm/project-config/hosted-infra-env-config.js.map +1 -1
  125. package/dist/esm/project-config/index.d.ts +3 -0
  126. package/dist/esm/project-config/index.d.ts.map +1 -1
  127. package/dist/esm/project-config/index.js +3 -0
  128. package/dist/esm/project-config/index.js.map +1 -1
  129. package/dist/esm/project-config/loader.d.ts.map +1 -1
  130. package/dist/esm/project-config/npm-version-range.d.ts.map +1 -1
  131. package/dist/esm/project-config/npm-version-range.js +39 -16
  132. package/dist/esm/project-config/npm-version-range.js.map +1 -1
  133. package/dist/esm/project-config/owning-package-tsconfig.d.ts +15 -0
  134. package/dist/esm/project-config/owning-package-tsconfig.d.ts.map +1 -0
  135. package/dist/esm/project-config/owning-package-tsconfig.js +29 -0
  136. package/dist/esm/project-config/owning-package-tsconfig.js.map +1 -0
  137. package/dist/esm/project-config/provider-catalog-types.d.ts.map +1 -1
  138. package/dist/esm/project-config/provider-companion-discovery.d.ts +4 -4
  139. package/dist/esm/project-config/provider-companion-discovery.d.ts.map +1 -1
  140. package/dist/esm/project-config/provider-companion-discovery.js +13 -9
  141. package/dist/esm/project-config/provider-companion-discovery.js.map +1 -1
  142. package/dist/esm/project-config/provider-runtime-artifacts.d.ts +32 -3
  143. package/dist/esm/project-config/provider-runtime-artifacts.d.ts.map +1 -1
  144. package/dist/esm/project-config/provider-runtime-artifacts.js +67 -13
  145. package/dist/esm/project-config/provider-runtime-artifacts.js.map +1 -1
  146. package/dist/esm/project-config/shared/application-creation-verification.schemas.d.ts.map +1 -1
  147. package/dist/esm/project-config/shared/application-modules.schemas.d.ts.map +1 -1
  148. package/dist/esm/project-config/shared/application-modules.utils.d.ts.map +1 -1
  149. package/dist/esm/project-config/shared/auth.schemas.d.ts.map +1 -1
  150. package/dist/esm/project-config/shared/backing-service-servability.d.ts.map +1 -1
  151. package/dist/esm/project-config/shared/backing-services.schemas.d.ts.map +1 -1
  152. package/dist/esm/project-config/shared/cdn.example.d.ts.map +1 -1
  153. package/dist/esm/project-config/shared/cdn.schemas.d.ts.map +1 -1
  154. package/dist/esm/project-config/shared/csp-defaults.d.ts +4 -5
  155. package/dist/esm/project-config/shared/csp-defaults.d.ts.map +1 -1
  156. package/dist/esm/project-config/shared/csp-defaults.js +4 -5
  157. package/dist/esm/project-config/shared/csp-defaults.js.map +1 -1
  158. package/dist/esm/project-config/shared/csp-emit.d.ts.map +1 -1
  159. package/dist/esm/project-config/shared/csp.schemas.d.ts +1 -2
  160. package/dist/esm/project-config/shared/csp.schemas.d.ts.map +1 -1
  161. package/dist/esm/project-config/shared/csp.schemas.js +1 -2
  162. package/dist/esm/project-config/shared/csp.schemas.js.map +1 -1
  163. package/dist/esm/project-config/shared/data-services.schemas.d.ts.map +1 -1
  164. package/dist/esm/project-config/shared/environment.schemas.d.ts +6 -0
  165. package/dist/esm/project-config/shared/environment.schemas.d.ts.map +1 -1
  166. package/dist/esm/project-config/shared/environment.schemas.js +8 -1
  167. package/dist/esm/project-config/shared/environment.schemas.js.map +1 -1
  168. package/dist/esm/project-config/shared/infra-providers.schemas.d.ts.map +1 -1
  169. package/dist/esm/project-config/shared/infra-service.schemas.d.ts.map +1 -1
  170. package/dist/esm/project-config/shared/infrastructure-defaults.schemas.d.ts +1 -0
  171. package/dist/esm/project-config/shared/infrastructure-defaults.schemas.d.ts.map +1 -1
  172. package/dist/esm/project-config/shared/infrastructure-defaults.schemas.js +3 -0
  173. package/dist/esm/project-config/shared/infrastructure-defaults.schemas.js.map +1 -1
  174. package/dist/esm/project-config/shared/minion-resource-access.validation.d.ts +4 -0
  175. package/dist/esm/project-config/shared/minion-resource-access.validation.d.ts.map +1 -1
  176. package/dist/esm/project-config/shared/minion-resource-access.validation.js +6 -2
  177. package/dist/esm/project-config/shared/minion-resource-access.validation.js.map +1 -1
  178. package/dist/esm/project-config/shared/platform-key-management.schemas.d.ts +250 -0
  179. package/dist/esm/project-config/shared/platform-key-management.schemas.d.ts.map +1 -0
  180. package/dist/esm/project-config/shared/platform-key-management.schemas.js +194 -0
  181. package/dist/esm/project-config/shared/platform-key-management.schemas.js.map +1 -0
  182. package/dist/esm/project-config/shared/platform-services.schemas.d.ts.map +1 -1
  183. package/dist/esm/project-config/shared/platform-storage.schemas.d.ts.map +1 -1
  184. package/dist/esm/project-config/shared/schema-version.schemas.d.ts.map +1 -1
  185. package/dist/esm/project-config/shared/service-definitions.schemas.d.ts.map +1 -1
  186. package/dist/esm/project-config/shared/systems-of-record-env.schemas.d.ts.map +1 -1
  187. package/dist/esm/registry/artifact-domain.schemas.d.ts.map +1 -1
  188. package/dist/esm/registry/digest.schemas.d.ts.map +1 -1
  189. package/dist/esm/registry/index.d.ts +1 -0
  190. package/dist/esm/registry/index.d.ts.map +1 -1
  191. package/dist/esm/registry/index.js +1 -0
  192. package/dist/esm/registry/index.js.map +1 -1
  193. package/dist/esm/registry/local-checkout-source.d.ts +22 -2
  194. package/dist/esm/registry/local-checkout-source.d.ts.map +1 -1
  195. package/dist/esm/registry/local-checkout-source.js +66 -3
  196. package/dist/esm/registry/local-checkout-source.js.map +1 -1
  197. package/dist/esm/registry/lockfile-modules-section.schemas.d.ts +10 -0
  198. package/dist/esm/registry/lockfile-modules-section.schemas.d.ts.map +1 -1
  199. package/dist/esm/registry/module-artifact.schemas.d.ts +23 -0
  200. package/dist/esm/registry/module-artifact.schemas.d.ts.map +1 -1
  201. package/dist/esm/registry/module-manifest.schemas.d.ts +336 -18
  202. package/dist/esm/registry/module-manifest.schemas.d.ts.map +1 -1
  203. package/dist/esm/registry/module-manifest.schemas.js +245 -19
  204. package/dist/esm/registry/module-manifest.schemas.js.map +1 -1
  205. package/dist/esm/registry/module-search.schemas.d.ts +2 -0
  206. package/dist/esm/registry/module-search.schemas.d.ts.map +1 -1
  207. package/dist/esm/registry/module-search.schemas.js +14 -1
  208. package/dist/esm/registry/module-search.schemas.js.map +1 -1
  209. package/dist/esm/registry/registry-config.schemas.d.ts.map +1 -1
  210. package/dist/esm/registry/registry-errors.d.ts +22 -2
  211. package/dist/esm/registry/registry-errors.d.ts.map +1 -1
  212. package/dist/esm/registry/registry-errors.js +28 -2
  213. package/dist/esm/registry/registry-errors.js.map +1 -1
  214. package/dist/esm/registry/registry-keys.schemas.d.ts.map +1 -1
  215. package/dist/esm/registry/registry-section-schemas.constants.d.ts +5 -0
  216. package/dist/esm/registry/registry-section-schemas.constants.d.ts.map +1 -1
  217. package/dist/esm/registry/registry-url-resolution.d.ts +72 -0
  218. package/dist/esm/registry/registry-url-resolution.d.ts.map +1 -0
  219. package/dist/esm/registry/registry-url-resolution.js +157 -0
  220. package/dist/esm/registry/registry-url-resolution.js.map +1 -0
  221. package/dist/esm/schemas/framework-info.schemas.d.ts.map +1 -1
  222. package/dist/esm/schemas/framework-secrets.schemas.d.ts +55 -0
  223. package/dist/esm/schemas/framework-secrets.schemas.d.ts.map +1 -1
  224. package/dist/esm/schemas/framework-secrets.schemas.js +53 -0
  225. package/dist/esm/schemas/framework-secrets.schemas.js.map +1 -1
  226. package/dist/esm/schemas/platform-application-config.schemas.d.ts.map +1 -1
  227. package/dist/esm/schemas/platform-application-secrets.schemas.d.ts.map +1 -1
  228. package/dist/esm/schemas/platform-config.schemas.d.ts.map +1 -1
  229. package/dist/esm/workspace-scope/application-subject-manifest.d.ts.map +1 -1
  230. package/dist/esm/workspace-scope/index.d.ts.map +1 -1
  231. package/package.json +7 -7
@@ -121,7 +121,7 @@ export declare function emitUnimplementedFieldWarning(source: UnimplementedField
121
121
  * const warn = createUnimplementedFieldWarner(UnimplementedFieldSource.SAAS_CONFIG);
122
122
  * warn('features.organizations', 'D-3');
123
123
  * warn('features.organizations', 'D-3'); // second call is a no-op
124
- * warn('csp.docs', 'B-2C', '.cursor/plans/auth-hardening.md');
124
+ * warn('example.field', 'X-1', 'docs/example-plan.md');
125
125
  * ```
126
126
  *
127
127
  * The returned closure is local to the parse call (not stored on a
@@ -129,7 +129,7 @@ export function emitUnimplementedFieldWarning(source, fieldPath, followUpSliceId
129
129
  * const warn = createUnimplementedFieldWarner(UnimplementedFieldSource.SAAS_CONFIG);
130
130
  * warn('features.organizations', 'D-3');
131
131
  * warn('features.organizations', 'D-3'); // second call is a no-op
132
- * warn('csp.docs', 'B-2C', '.cursor/plans/auth-hardening.md');
132
+ * warn('example.field', 'X-1', 'docs/example-plan.md');
133
133
  * ```
134
134
  *
135
135
  * The returned closure is local to the parse call (not stored on a
@@ -1 +1 @@
1
- {"version":3,"file":"unimplemented-field-warning.js","sourceRoot":"","sources":["../../../../src/_unimplemented/unimplemented-field-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AAEH;;;;GAIG;AACH,MAAM,CAAN,IAAY,wBAGX;AAHD,WAAY,wBAAwB;IAClC,6DAAiC,CAAA;IACjC,uEAA2C,CAAA;AAC7C,CAAC,EAHW,wBAAwB,KAAxB,wBAAwB,QAGnC;AAED,MAAM,+BAA+B,GAAG,mDAAmD,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAgC,EAChC,SAAiB,EACjB,eAAuB,EACvB,mBAA2B,+BAA+B;IAE1D,MAAM,OAAO,GACX,IAAI,MAAM,2BAA2B,SAAS,eAAe;QAC7D,iCAAiC,eAAe,GAAG;QACnD,IAAI,gBAAgB,KAAK;QACzB,8DAA8D,CAAC;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAAgC;IAEhC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,OAAO,CAAC,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,EAAE;QACtD,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,OAAO;QACnC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvB,6BAA6B,CAAC,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,CAAC,CAAC;IACtF,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * @fileoverview `@unimplemented` runtime-contract warning utility\n * (Slice 3.4 + Slice 3.5 infra extension).\n *\n * Some authored fields on `WildoSaasConfigSchema` and\n * `WildoInfraEnvConfigInputSchema` are intentionally exposed in the\n * authoring surface today but have **no runtime consumer yet**: they\n * are \"scaffolded for the next slice\". Examples (full list in\n * `.cursor/plans/post-flattening-completion-fixes.md` Slices 3.4-3.5 +\n * the deferred-backlog table):\n *\n * - `WildoSaasConfig.version`, `WildoInfraEnvConfig.version` → backlog `D-5`\n *\n * (`WildoSaasConfig.{minions, workers}` → backlog `D-1` was retired\n * 2026-05-05 with the close of D-1; the runtime path now ships\n * end-to-end — see `.claude/plans/minions-and-workers-implementation.md`\n * Phase 4. The per-entry `resourceAccess` soft-warn channel under\n * `minions.<key>` survives because it is an authoring-contract\n * advisory, not a \"runtime missing\" marker.)\n *\n * The framework-mindset rule of thumb (per `.cursor/rules/design-philosophy.mdc`)\n * is that **every authored field must carry its semantic weight**. Silently\n * stripping or silently ignoring authored values is the kind of \"trick\" that\n * compounds into long-term debt — an app developer who writes a still-deferred\n * field should NOT discover six months later that the flag never wired\n * anything up.\n *\n * The honest middle-ground until the deferred slices land is:\n *\n * 1. Keep the field in the schema so authored configs stay forward-compatible\n * when the runtime support DOES arrive (no breaking re-author).\n * 2. **Loudly warn at parse time** that the field is parsed but currently\n * has no runtime consumer, with a pointer to the tracking backlog ID.\n * 3. Document the same set in `cli-dx.md` so a reader can audit the gap\n * without grepping the codebase.\n *\n * Design choices made for this utility:\n *\n * - **Channel = `process.stderr`** (decided 2026-04-13). Writing directly to\n * the FD keeps the utility usable from every context the schema runs in\n * today — CLI commands, the dev watcher, backend bootstrap, and tests —\n * without coupling to the CLI logger or to `console.warn` (the latter\n * would be hijacked by the dev watcher's pretty-printer and the warning\n * would lose its raw form). Tests stub via `vi.spyOn(process.stderr, 'write')`.\n * - **Dedupe = \"once per parse call\"** (decided 2026-04-13). The utility is\n * stateless — no module-level `Set` caching emitted warnings — and the\n * *caller* (`defineSaasConfig`) owns a fresh `Set<string>` per parse so\n * that authoring the same field twice in one config still warns once,\n * but the dev watcher re-parsing on every save still re-emits the full\n * set so authors see them on every save instead of \"warning fatigue =\n * silent after the first save\". Process-wide dedupe was rejected because\n * a long-lived dev watcher would emit each warning exactly once at boot\n * and never again, defeating the purpose for someone who joins later.\n * - **Format = single-line with slice ID + plan reference** (decided\n * 2026-04-13). One line per warning is grep-friendly, fits inside dev\n * watcher log streams without breaking layout, and embedding `D-{n}`\n * plus the plan filename gives the reader a one-jump path to the\n * tracking entry. The longer \"two-line block\" alternative was rejected\n * because the dev watcher's per-line log prefixes break the visual\n * indentation, and the \"minimal one-liner\" alternative was rejected\n * because it required the reader to look up `D-{n}` separately.\n *\n * NOT a replacement for schema validation:\n * - This utility does NOT prevent the field from being authored.\n * - It does NOT cast / coerce / mutate the parsed value.\n * - It is a **runtime advisory**, surfaced AFTER `WildoSaasConfigSchema.parse()`\n * succeeds, by the `defineSaasConfig` wrapper.\n *\n * When the deferred backlog item lands and the runtime consumer ships, the\n * corresponding `if (...) emitUnimplementedFieldWarning(...)` block in\n * `defineSaasConfig.ts` MUST be removed in the same commit as the runtime\n * wiring — leaving a stale warning is worse than silence because authors\n * will start ignoring the channel.\n */\n\n/**\n * Source label embedded in the warning prefix so a reader can tell at a\n * glance which authored config emitted the warning. Keep the literals\n * stable — tests and operator runbooks may grep on these prefixes.\n */\nexport enum UnimplementedFieldSource {\n SAAS_CONFIG = 'wildo-saas-config',\n INFRA_ENV_CONFIG = 'wildo-infra-env-config',\n}\n\nconst DEFAULT_UNIMPLEMENTED_PLAN_PATH = '.cursor/plans/post-flattening-completion-fixes.md';\n\n/**\n * Emit a single-line `@unimplemented` warning to `process.stderr`.\n *\n * @param source - Which authored config the field belongs to. Surfaces in\n * the warning prefix (`[wildo-saas-config]` /\n * `[wildo-infra-env-config]`) so the reader can match the\n * warning back to the file they were editing without\n * scrolling the call stack.\n * @param fieldPath - Dotted path to the authored field, e.g.\n * `'features.organizations'` or\n * `'capabilities.AI_LLM.runtime'`. Used as the dedupe\n * key by callers and surfaced verbatim in the warning\n * text so authors can ctrl-F it in their config.\n * @param followUpSliceId - Tracking ID in the deferred backlog\n * (`D-1` / `D-2` / `D-3` / `D-5` today, plus\n * auth-hardening's `B-2C`). Surfaced in the\n * warning so readers can jump to the matching\n * plan entry without grepping.\n * @param followUpPlanPath - Plan file that owns the backlog ID. Defaults\n * to `post-flattening-completion-fixes.md` so\n * the existing D-series warnings keep their\n * current breadcrumb, but callers can override\n * it for backlog IDs owned by another plan.\n *\n * The warning is written synchronously; this is intentional so the line\n * appears next to the offending parse in the dev watcher's interleaved\n * log stream. Throwing here is intentionally not done — a bad warning\n * must never block a parse, only inform.\n */\nexport function emitUnimplementedFieldWarning(\n source: UnimplementedFieldSource,\n fieldPath: string,\n followUpSliceId: string,\n followUpPlanPath: string = DEFAULT_UNIMPLEMENTED_PLAN_PATH,\n): void {\n const message =\n `[${source}] @unimplemented field '${fieldPath}' authored — ` +\n `runtime support tracked under ${followUpSliceId} ` +\n `(${followUpPlanPath}). ` +\n `The field is parsed but currently has no runtime consumer.\\n`;\n process.stderr.write(message);\n}\n\n/**\n * Convenience wrapper that owns a per-call dedupe `Set<string>` keyed by\n * `fieldPath` alone (the `source` is bound by the closure, so embedding\n * it in the dedupe key would be redundant — one warner instance is\n * scoped to one source). Intended call shape:\n *\n * ```ts\n * const warn = createUnimplementedFieldWarner(UnimplementedFieldSource.SAAS_CONFIG);\n * warn('features.organizations', 'D-3');\n * warn('features.organizations', 'D-3'); // second call is a no-op\n * warn('csp.docs', 'B-2C', '.cursor/plans/auth-hardening.md');\n * ```\n *\n * The returned closure is local to the parse call (not stored on a\n * module / singleton) so dev-watcher re-parses still re-emit the full set\n * — see the \"once per parse call\" decision in the file-level JSDoc above.\n *\n * The source is captured by the closure so callers (one per\n * `defineSaasConfig` / `defineInfraEnvConfig` invocation) only have to\n * pass field paths, matching the existing call shape used in\n * `defineSaasConfig.emitUnimplementedRuntimeWarnings`.\n */\nexport function createUnimplementedFieldWarner(\n source: UnimplementedFieldSource,\n): (fieldPath: string, followUpSliceId: string, followUpPlanPath?: string) => void {\n const emitted = new Set<string>();\n return (fieldPath, followUpSliceId, followUpPlanPath) => {\n if (emitted.has(fieldPath)) return;\n emitted.add(fieldPath);\n emitUnimplementedFieldWarning(source, fieldPath, followUpSliceId, followUpPlanPath);\n };\n}\n"]}
1
+ {"version":3,"file":"unimplemented-field-warning.js","sourceRoot":"","sources":["../../../../src/_unimplemented/unimplemented-field-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AAEH;;;;GAIG;AACH,MAAM,CAAN,IAAY,wBAGX;AAHD,WAAY,wBAAwB;IAClC,6DAAiC,CAAA;IACjC,uEAA2C,CAAA;AAC7C,CAAC,EAHW,wBAAwB,KAAxB,wBAAwB,QAGnC;AAED,MAAM,+BAA+B,GAAG,mDAAmD,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAgC,EAChC,SAAiB,EACjB,eAAuB,EACvB,mBAA2B,+BAA+B;IAE1D,MAAM,OAAO,GACX,IAAI,MAAM,2BAA2B,SAAS,eAAe;QAC7D,iCAAiC,eAAe,GAAG;QACnD,IAAI,gBAAgB,KAAK;QACzB,8DAA8D,CAAC;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAAgC;IAEhC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,OAAO,CAAC,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,EAAE;QACtD,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,OAAO;QACnC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvB,6BAA6B,CAAC,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,CAAC,CAAC;IACtF,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * @fileoverview `@unimplemented` runtime-contract warning utility\n * (Slice 3.4 + Slice 3.5 infra extension).\n *\n * Some authored fields on `WildoSaasConfigSchema` and\n * `WildoInfraEnvConfigInputSchema` are intentionally exposed in the\n * authoring surface today but have **no runtime consumer yet**: they\n * are \"scaffolded for the next slice\". Examples (full list in\n * `.cursor/plans/post-flattening-completion-fixes.md` Slices 3.4-3.5 +\n * the deferred-backlog table):\n *\n * - `WildoSaasConfig.version`, `WildoInfraEnvConfig.version` → backlog `D-5`\n *\n * (`WildoSaasConfig.{minions, workers}` → backlog `D-1` was retired\n * 2026-05-05 with the close of D-1; the runtime path now ships\n * end-to-end — see `.claude/plans/minions-and-workers-implementation.md`\n * Phase 4. The per-entry `resourceAccess` soft-warn channel under\n * `minions.<key>` survives because it is an authoring-contract\n * advisory, not a \"runtime missing\" marker.)\n *\n * The framework-mindset rule of thumb (per `.cursor/rules/design-philosophy.mdc`)\n * is that **every authored field must carry its semantic weight**. Silently\n * stripping or silently ignoring authored values is the kind of \"trick\" that\n * compounds into long-term debt — an app developer who writes a still-deferred\n * field should NOT discover six months later that the flag never wired\n * anything up.\n *\n * The honest middle-ground until the deferred slices land is:\n *\n * 1. Keep the field in the schema so authored configs stay forward-compatible\n * when the runtime support DOES arrive (no breaking re-author).\n * 2. **Loudly warn at parse time** that the field is parsed but currently\n * has no runtime consumer, with a pointer to the tracking backlog ID.\n * 3. Document the same set in `cli-dx.md` so a reader can audit the gap\n * without grepping the codebase.\n *\n * Design choices made for this utility:\n *\n * - **Channel = `process.stderr`** (decided 2026-04-13). Writing directly to\n * the FD keeps the utility usable from every context the schema runs in\n * today — CLI commands, the dev watcher, backend bootstrap, and tests —\n * without coupling to the CLI logger or to `console.warn` (the latter\n * would be hijacked by the dev watcher's pretty-printer and the warning\n * would lose its raw form). Tests stub via `vi.spyOn(process.stderr, 'write')`.\n * - **Dedupe = \"once per parse call\"** (decided 2026-04-13). The utility is\n * stateless — no module-level `Set` caching emitted warnings — and the\n * *caller* (`defineSaasConfig`) owns a fresh `Set<string>` per parse so\n * that authoring the same field twice in one config still warns once,\n * but the dev watcher re-parsing on every save still re-emits the full\n * set so authors see them on every save instead of \"warning fatigue =\n * silent after the first save\". Process-wide dedupe was rejected because\n * a long-lived dev watcher would emit each warning exactly once at boot\n * and never again, defeating the purpose for someone who joins later.\n * - **Format = single-line with slice ID + plan reference** (decided\n * 2026-04-13). One line per warning is grep-friendly, fits inside dev\n * watcher log streams without breaking layout, and embedding `D-{n}`\n * plus the plan filename gives the reader a one-jump path to the\n * tracking entry. The longer \"two-line block\" alternative was rejected\n * because the dev watcher's per-line log prefixes break the visual\n * indentation, and the \"minimal one-liner\" alternative was rejected\n * because it required the reader to look up `D-{n}` separately.\n *\n * NOT a replacement for schema validation:\n * - This utility does NOT prevent the field from being authored.\n * - It does NOT cast / coerce / mutate the parsed value.\n * - It is a **runtime advisory**, surfaced AFTER `WildoSaasConfigSchema.parse()`\n * succeeds, by the `defineSaasConfig` wrapper.\n *\n * When the deferred backlog item lands and the runtime consumer ships, the\n * corresponding `if (...) emitUnimplementedFieldWarning(...)` block in\n * `defineSaasConfig.ts` MUST be removed in the same commit as the runtime\n * wiring — leaving a stale warning is worse than silence because authors\n * will start ignoring the channel.\n */\n\n/**\n * Source label embedded in the warning prefix so a reader can tell at a\n * glance which authored config emitted the warning. Keep the literals\n * stable — tests and operator runbooks may grep on these prefixes.\n */\nexport enum UnimplementedFieldSource {\n SAAS_CONFIG = 'wildo-saas-config',\n INFRA_ENV_CONFIG = 'wildo-infra-env-config',\n}\n\nconst DEFAULT_UNIMPLEMENTED_PLAN_PATH = '.cursor/plans/post-flattening-completion-fixes.md';\n\n/**\n * Emit a single-line `@unimplemented` warning to `process.stderr`.\n *\n * @param source - Which authored config the field belongs to. Surfaces in\n * the warning prefix (`[wildo-saas-config]` /\n * `[wildo-infra-env-config]`) so the reader can match the\n * warning back to the file they were editing without\n * scrolling the call stack.\n * @param fieldPath - Dotted path to the authored field, e.g.\n * `'features.organizations'` or\n * `'capabilities.AI_LLM.runtime'`. Used as the dedupe\n * key by callers and surfaced verbatim in the warning\n * text so authors can ctrl-F it in their config.\n * @param followUpSliceId - Tracking ID in the deferred backlog\n * (`D-1` / `D-2` / `D-3` / `D-5` today, plus\n * auth-hardening's `B-2C`). Surfaced in the\n * warning so readers can jump to the matching\n * plan entry without grepping.\n * @param followUpPlanPath - Plan file that owns the backlog ID. Defaults\n * to `post-flattening-completion-fixes.md` so\n * the existing D-series warnings keep their\n * current breadcrumb, but callers can override\n * it for backlog IDs owned by another plan.\n *\n * The warning is written synchronously; this is intentional so the line\n * appears next to the offending parse in the dev watcher's interleaved\n * log stream. Throwing here is intentionally not done — a bad warning\n * must never block a parse, only inform.\n */\nexport function emitUnimplementedFieldWarning(\n source: UnimplementedFieldSource,\n fieldPath: string,\n followUpSliceId: string,\n followUpPlanPath: string = DEFAULT_UNIMPLEMENTED_PLAN_PATH,\n): void {\n const message =\n `[${source}] @unimplemented field '${fieldPath}' authored — ` +\n `runtime support tracked under ${followUpSliceId} ` +\n `(${followUpPlanPath}). ` +\n `The field is parsed but currently has no runtime consumer.\\n`;\n process.stderr.write(message);\n}\n\n/**\n * Convenience wrapper that owns a per-call dedupe `Set<string>` keyed by\n * `fieldPath` alone (the `source` is bound by the closure, so embedding\n * it in the dedupe key would be redundant — one warner instance is\n * scoped to one source). Intended call shape:\n *\n * ```ts\n * const warn = createUnimplementedFieldWarner(UnimplementedFieldSource.SAAS_CONFIG);\n * warn('features.organizations', 'D-3');\n * warn('features.organizations', 'D-3'); // second call is a no-op\n * warn('example.field', 'X-1', 'docs/example-plan.md');\n * ```\n *\n * The returned closure is local to the parse call (not stored on a\n * module / singleton) so dev-watcher re-parses still re-emit the full set\n * — see the \"once per parse call\" decision in the file-level JSDoc above.\n *\n * The source is captured by the closure so callers (one per\n * `defineSaasConfig` / `defineInfraEnvConfig` invocation) only have to\n * pass field paths, matching the existing call shape used in\n * `defineSaasConfig.emitUnimplementedRuntimeWarnings`.\n */\nexport function createUnimplementedFieldWarner(\n source: UnimplementedFieldSource,\n): (fieldPath: string, followUpSliceId: string, followUpPlanPath?: string) => void {\n const emitted = new Set<string>();\n return (fieldPath, followUpSliceId, followUpPlanPath) => {\n if (emitted.has(fieldPath)) return;\n emitted.add(fieldPath);\n emitUnimplementedFieldWarning(source, fieldPath, followUpSliceId, followUpPlanPath);\n };\n}\n"]}
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Anchor SLOTS and blueprint CONTRIBUTIONS in free text (epic #2856, #2862) — the grammar, read and write.
3
+ *
4
+ * A slot is an extension point a base file declares; a blueprint writes its text inside it as a contribution span
5
+ * of its own, so layers stack in order and each one's text stays identifiable:
6
+ *
7
+ * ```markdown
8
+ * <!-- @wildo_anchor:slot:start application.guide -->
9
+ * <!-- @wildo_anchor:contribution:start acme/internal-tool application.guide -->
10
+ * The layer's text.
11
+ * <!-- @wildo_anchor:contribution:end acme/internal-tool application.guide -->
12
+ * <!-- @wildo_anchor:slot:end application.guide -->
13
+ * ```
14
+ *
15
+ * Only free text needs this. A TypeScript base file exposes NAMED DECLARATIONS a blueprint sets instead
16
+ * (`BlueprintDeclarationFile`), which is the preferred and far more common shape: measured on Wonder Procurement
17
+ * (#2860), the agent guide was the one change to a base file that was not the value of a declaration.
18
+ *
19
+ * ## Strict, like the writer it is modelled on
20
+ *
21
+ * The rules are those of `rewriteNginxCspMarkerPairsString` (`project-config/shared/csp-emit.ts`): a marker is a
22
+ * whole line; a nested slot, an end with no start, an unclosed span, a slot declared twice, a contribution outside its
23
+ * slot or naming another slot all REFUSE, because a guess at a damaged boundary writes text into the wrong place. So
24
+ * does any other comment line opening with `@wildo_anchor:` (a third argument, text after the marker): a damaged
25
+ * marker never reads as plain text, while prose that only mentions the family does. In Markdown, lines inside a code fence are text, so a guide can SHOW the markers. A contribution body
26
+ * may not contain a marker line, and every write re-reads its own result.
27
+ *
28
+ * Indentation is kept, every line keeps its own terminator (a file mixing `\n` and `\r\n` stays mixed; added lines
29
+ * take the more common one), and a write that changes nothing returns the input unchanged.
30
+ *
31
+ * The marker family is deliberately not `@wildo_source`: that one is an extraction contract for framework knowledge,
32
+ * and a refactor of what knowledge extracts must never move a place applications are written into.
33
+ */
34
+ /** How a file writes a whole-line comment. */
35
+ export declare enum AnchorCommentStyle {
36
+ /** Markdown and HTML: `<!-- … -->`. Survives a Handlebars render, which `{{!-- --}}` would not. */
37
+ HTML = "html",
38
+ /** TypeScript and JavaScript: `// …`. */
39
+ LINE_SLASH = "line-slash",
40
+ /** YAML, shell, Dockerfile, `.gitignore`: `# …`. */
41
+ HASH = "hash"
42
+ }
43
+ /** The comment style of a file, by its name. */
44
+ export declare function anchorCommentStyleForPath(path: string): AnchorCommentStyle;
45
+ /** One contribution span inside a slot. Line numbers are zero-based indexes into the file's lines. */
46
+ export interface AnchorContribution {
47
+ readonly blueprintId: string;
48
+ readonly startLine: number;
49
+ readonly endLine: number;
50
+ /** The span's text, markers excluded. */
51
+ readonly body: string;
52
+ }
53
+ /** One slot as the file holds it. */
54
+ export interface AnchorSlot {
55
+ readonly id: string;
56
+ readonly startLine: number;
57
+ readonly endLine: number;
58
+ readonly indent: string;
59
+ readonly contributions: readonly AnchorContribution[];
60
+ /** The slot's text OUTSIDE every contribution span — what the application wrote there itself. */
61
+ readonly ownText: string;
62
+ }
63
+ /** Every slot of a file, by id. Refuses a damaged structure rather than reading around it. */
64
+ export declare function readAnchorSlots(content: string, style: AnchorCommentStyle): ReadonlyMap<string, AnchorSlot>;
65
+ /**
66
+ * Write `body` as `blueprintId`'s contribution to `slotId`: replace its existing span, or add one just before the
67
+ * slot's end marker (after every earlier layer's). Refuses a slot the file does not declare. Returns the content
68
+ * unchanged when the span already holds exactly this body.
69
+ */
70
+ export declare function writeAnchorContribution(content: string, style: AnchorCommentStyle, input: {
71
+ readonly slotId: string;
72
+ readonly blueprintId: string;
73
+ readonly body: string;
74
+ }): string;
75
+ /**
76
+ * A slot's whole text with every contribution marker removed and blank lines trimmed at both ends: what a reader
77
+ * sees there, whoever wrote it. Two files whose slots read the same this way say the same thing, which is how an
78
+ * export compares the slot it reproduces with the one the defining application holds.
79
+ */
80
+ export declare function readableAnchorSlotText(content: string, style: AnchorCommentStyle, slotId: string): string | undefined;
81
+ /** The file's content with every contribution marker line removed — for comparing files that differ only by them. */
82
+ export declare function withoutAnchorContributionMarkers(content: string, style: AnchorCommentStyle): string;
83
+ //# sourceMappingURL=anchored-region.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"anchored-region.d.ts","sourceRoot":"","sources":["../../../../src/blueprint/anchored-region.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,8CAA8C;AAC9C,oBAAY,kBAAkB;IAC5B,mGAAmG;IACnG,IAAI,SAAS;IACb,yCAAyC;IACzC,UAAU,eAAe;IACzB,oDAAoD;IACpD,IAAI,SAAS;CACd;AAED,gDAAgD;AAChD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAM1E;AAkED,sGAAsG;AACtG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACtD,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAqCD,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAsD3G;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACtF,MAAM,CAwBR;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQrH;AAED,qHAAqH;AACrH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAOnG"}
@@ -0,0 +1,263 @@
1
+ /**
2
+ * Anchor SLOTS and blueprint CONTRIBUTIONS in free text (epic #2856, #2862) — the grammar, read and write.
3
+ *
4
+ * A slot is an extension point a base file declares; a blueprint writes its text inside it as a contribution span
5
+ * of its own, so layers stack in order and each one's text stays identifiable:
6
+ *
7
+ * ```markdown
8
+ * <!-- @wildo_anchor:slot:start application.guide -->
9
+ * <!-- @wildo_anchor:contribution:start acme/internal-tool application.guide -->
10
+ * The layer's text.
11
+ * <!-- @wildo_anchor:contribution:end acme/internal-tool application.guide -->
12
+ * <!-- @wildo_anchor:slot:end application.guide -->
13
+ * ```
14
+ *
15
+ * Only free text needs this. A TypeScript base file exposes NAMED DECLARATIONS a blueprint sets instead
16
+ * (`BlueprintDeclarationFile`), which is the preferred and far more common shape: measured on Wonder Procurement
17
+ * (#2860), the agent guide was the one change to a base file that was not the value of a declaration.
18
+ *
19
+ * ## Strict, like the writer it is modelled on
20
+ *
21
+ * The rules are those of `rewriteNginxCspMarkerPairsString` (`project-config/shared/csp-emit.ts`): a marker is a
22
+ * whole line; a nested slot, an end with no start, an unclosed span, a slot declared twice, a contribution outside its
23
+ * slot or naming another slot all REFUSE, because a guess at a damaged boundary writes text into the wrong place. So
24
+ * does any other comment line opening with `@wildo_anchor:` (a third argument, text after the marker): a damaged
25
+ * marker never reads as plain text, while prose that only mentions the family does. In Markdown, lines inside a code fence are text, so a guide can SHOW the markers. A contribution body
26
+ * may not contain a marker line, and every write re-reads its own result.
27
+ *
28
+ * Indentation is kept, every line keeps its own terminator (a file mixing `\n` and `\r\n` stays mixed; added lines
29
+ * take the more common one), and a write that changes nothing returns the input unchanged.
30
+ *
31
+ * The marker family is deliberately not `@wildo_source`: that one is an extraction contract for framework knowledge,
32
+ * and a refactor of what knowledge extracts must never move a place applications are written into.
33
+ */
34
+ /** How a file writes a whole-line comment. */
35
+ export var AnchorCommentStyle;
36
+ (function (AnchorCommentStyle) {
37
+ /** Markdown and HTML: `<!-- … -->`. Survives a Handlebars render, which `{{!-- --}}` would not. */
38
+ AnchorCommentStyle["HTML"] = "html";
39
+ /** TypeScript and JavaScript: `// …`. */
40
+ AnchorCommentStyle["LINE_SLASH"] = "line-slash";
41
+ /** YAML, shell, Dockerfile, `.gitignore`: `# …`. */
42
+ AnchorCommentStyle["HASH"] = "hash";
43
+ })(AnchorCommentStyle || (AnchorCommentStyle = {}));
44
+ /** The comment style of a file, by its name. */
45
+ export function anchorCommentStyleForPath(path) {
46
+ const name = path.split('/').pop() ?? path;
47
+ if (/\.(md|mdx|html?)$/i.test(name))
48
+ return AnchorCommentStyle.HTML;
49
+ if (/\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i.test(name))
50
+ return AnchorCommentStyle.LINE_SLASH;
51
+ if (/\.(ya?ml|sh|toml)$/i.test(name) || name === 'Dockerfile' || name.startsWith('.'))
52
+ return AnchorCommentStyle.HASH;
53
+ throw new Error(`No anchor comment style is defined for ${path}.`);
54
+ }
55
+ /** What a marker line opens or closes. */
56
+ var AnchorMarkerKind;
57
+ (function (AnchorMarkerKind) {
58
+ AnchorMarkerKind["SLOT"] = "slot";
59
+ AnchorMarkerKind["CONTRIBUTION"] = "contribution";
60
+ })(AnchorMarkerKind || (AnchorMarkerKind = {}));
61
+ /** Which end of a span a marker line is. */
62
+ var AnchorMarkerEdge;
63
+ (function (AnchorMarkerEdge) {
64
+ AnchorMarkerEdge["START"] = "start";
65
+ AnchorMarkerEdge["END"] = "end";
66
+ })(AnchorMarkerEdge || (AnchorMarkerEdge = {}));
67
+ const MARKER_BODY = '@wildo_anchor:(slot|contribution):(start|end)\\s+(\\S+(?:\\s+\\S+)?)';
68
+ /** The marker family, as text. A contribution body may not contain it at all. */
69
+ const MARKER_FAMILY = '@wildo_anchor:';
70
+ /**
71
+ * A line that OPENS a comment with the marker family — what a marker looks like. One that is not a well-formed marker
72
+ * refuses rather than reading as text. Prose that merely MENTIONS the family ("the `@wildo_anchor:slot` markers") is
73
+ * text, so a guide can talk about its own slots.
74
+ */
75
+ const MARKER_SHAPED_LINES = {
76
+ [AnchorCommentStyle.HTML]: /^\s*<!--\s*@wildo_anchor:/,
77
+ [AnchorCommentStyle.LINE_SLASH]: /^\s*\/\/\s*@wildo_anchor:/,
78
+ [AnchorCommentStyle.HASH]: /^\s*#\s*@wildo_anchor:/,
79
+ };
80
+ /** A Markdown code fence: markers shown inside one are an example, not a slot. */
81
+ const CODE_FENCE_PATTERN = /^\s*(```|~~~)/;
82
+ const MARKER_PATTERNS = {
83
+ [AnchorCommentStyle.HTML]: new RegExp(`^(\\s*)<!--\\s*${MARKER_BODY}\\s*-->\\s*$`),
84
+ [AnchorCommentStyle.LINE_SLASH]: new RegExp(`^(\\s*)//\\s*${MARKER_BODY}\\s*$`),
85
+ [AnchorCommentStyle.HASH]: new RegExp(`^(\\s*)#\\s*${MARKER_BODY}\\s*$`),
86
+ };
87
+ function parseMarker(line, style) {
88
+ const match = MARKER_PATTERNS[style].exec(line);
89
+ if (match === null)
90
+ return null;
91
+ return {
92
+ kind: match[2],
93
+ edge: match[3],
94
+ args: (match[4] ?? '').split(/\s+/),
95
+ indent: match[1] ?? '',
96
+ };
97
+ }
98
+ function renderMarker(style, indent, kind, edge, args) {
99
+ const body = `@wildo_anchor:${kind}:${edge} ${args.join(' ')}`;
100
+ switch (style) {
101
+ case AnchorCommentStyle.HTML:
102
+ return `${indent}<!-- ${body} -->`;
103
+ case AnchorCommentStyle.LINE_SLASH:
104
+ return `${indent}// ${body}`;
105
+ case AnchorCommentStyle.HASH:
106
+ return `${indent}# ${body}`;
107
+ }
108
+ }
109
+ /**
110
+ * The file's lines, each line's own terminator (the last one's is `''`), and the terminator new lines get: the one
111
+ * the file uses most. Keeping each terminator is what lets a write leave every line it did not add byte-identical,
112
+ * even in a file that mixes `\n` and `\r\n`.
113
+ */
114
+ function splitLines(content) {
115
+ const lines = [];
116
+ const terminators = [];
117
+ const pattern = /\r?\n/g;
118
+ let start = 0;
119
+ for (const match of content.matchAll(pattern)) {
120
+ lines.push(content.slice(start, match.index));
121
+ terminators.push(match[0]);
122
+ start = (match.index ?? 0) + match[0].length;
123
+ }
124
+ lines.push(content.slice(start));
125
+ terminators.push('');
126
+ const crlf = terminators.filter((terminator) => terminator === '\r\n').length;
127
+ const lf = terminators.filter((terminator) => terminator === '\n').length;
128
+ return { lines, terminators, eol: crlf > lf ? '\r\n' : '\n' };
129
+ }
130
+ function joinLines(lines, terminators) {
131
+ return lines.map((line, index) => `${line}${terminators[index] ?? ''}`).join('');
132
+ }
133
+ /** Drop blank lines at both ends of a text block. */
134
+ function trimBlankLines(lines) {
135
+ let start = 0;
136
+ let end = lines.length;
137
+ while (start < end && lines[start]?.trim() === '')
138
+ start += 1;
139
+ while (end > start && lines[end - 1]?.trim() === '')
140
+ end -= 1;
141
+ return lines.slice(start, end).join('\n');
142
+ }
143
+ /** Every slot of a file, by id. Refuses a damaged structure rather than reading around it. */
144
+ export function readAnchorSlots(content, style) {
145
+ const { lines } = splitLines(content);
146
+ const slots = new Map();
147
+ let open = null;
148
+ let openContribution = null;
149
+ let insideFence = false;
150
+ lines.forEach((line, index) => {
151
+ const where = `line ${index + 1}`;
152
+ if (style === AnchorCommentStyle.HTML && CODE_FENCE_PATTERN.test(line))
153
+ insideFence = !insideFence;
154
+ const marker = insideFence ? null : parseMarker(line, style);
155
+ if (marker === null && !insideFence && MARKER_SHAPED_LINES[style].test(line)) {
156
+ throw new Error(`The ${MARKER_FAMILY} line at ${where} is not a well-formed marker (a slot names one id, a contribution a blueprint and a slot, and the marker is the whole line).`);
157
+ }
158
+ if (marker === null) {
159
+ if (openContribution !== null)
160
+ openContribution.body.push(line);
161
+ else if (open !== null)
162
+ open.own.push(line);
163
+ return;
164
+ }
165
+ if (marker.kind === AnchorMarkerKind.SLOT) {
166
+ const [id] = marker.args;
167
+ if (marker.args.length !== 1 || id === undefined)
168
+ throw new Error(`Anchor slot marker at ${where} must name exactly one slot.`);
169
+ if (marker.edge === AnchorMarkerEdge.START) {
170
+ if (open !== null)
171
+ throw new Error(`Anchor slot '${id}' at ${where} opens inside slot '${open.id}': slots do not nest.`);
172
+ if (slots.has(id))
173
+ throw new Error(`Anchor slot '${id}' is declared twice (again at ${where}).`);
174
+ open = { id, startLine: index, indent: marker.indent, contributions: [], own: [] };
175
+ return;
176
+ }
177
+ if (open === null || open.id !== id)
178
+ throw new Error(`Anchor slot end '${id}' at ${where} closes no open slot of that name.`);
179
+ if (openContribution !== null)
180
+ throw new Error(`Anchor slot '${id}' closes at ${where} inside an unclosed contribution of '${openContribution.blueprintId}'.`);
181
+ slots.set(id, { id, startLine: open.startLine, endLine: index, indent: open.indent, contributions: open.contributions, ownText: trimBlankLines(open.own) });
182
+ open = null;
183
+ return;
184
+ }
185
+ const [blueprintId, slotId] = marker.args;
186
+ if (marker.args.length !== 2 || blueprintId === undefined || slotId === undefined) {
187
+ throw new Error(`Anchor contribution marker at ${where} must name a blueprint and a slot.`);
188
+ }
189
+ if (open === null || open.id !== slotId)
190
+ throw new Error(`Contribution of '${blueprintId}' at ${where} names slot '${slotId}' but sits outside it.`);
191
+ if (marker.edge === AnchorMarkerEdge.START) {
192
+ if (openContribution !== null)
193
+ throw new Error(`Contribution of '${blueprintId}' at ${where} opens inside the contribution of '${openContribution.blueprintId}'.`);
194
+ if (open.contributions.some((contribution) => contribution.blueprintId === blueprintId)) {
195
+ throw new Error(`Blueprint '${blueprintId}' contributes to slot '${slotId}' twice (again at ${where}).`);
196
+ }
197
+ openContribution = { blueprintId, startLine: index, body: [] };
198
+ return;
199
+ }
200
+ if (openContribution === null || openContribution.blueprintId !== blueprintId) {
201
+ throw new Error(`Contribution end of '${blueprintId}' at ${where} closes no open contribution of that blueprint.`);
202
+ }
203
+ open.contributions.push({ blueprintId, startLine: openContribution.startLine, endLine: index, body: openContribution.body.join('\n') });
204
+ openContribution = null;
205
+ });
206
+ if (open !== null)
207
+ throw new Error(`Anchor slot '${open.id}' is never closed.`);
208
+ return slots;
209
+ }
210
+ /**
211
+ * Write `body` as `blueprintId`'s contribution to `slotId`: replace its existing span, or add one just before the
212
+ * slot's end marker (after every earlier layer's). Refuses a slot the file does not declare. Returns the content
213
+ * unchanged when the span already holds exactly this body.
214
+ */
215
+ export function writeAnchorContribution(content, style, input) {
216
+ const slot = readAnchorSlots(content, style).get(input.slotId);
217
+ if (slot === undefined)
218
+ throw new Error(`No anchor slot '${input.slotId}' is declared in this file.`);
219
+ const { lines, terminators, eol } = splitLines(content);
220
+ const bodyLines = input.body === '' ? [] : input.body.replace(/\r?\n$/, '').split(/\r?\n/);
221
+ if (bodyLines.some((line) => line.includes(MARKER_FAMILY))) {
222
+ throw new Error(`The contribution of '${input.blueprintId}' to slot '${input.slotId}' contains a ${MARKER_FAMILY} line, which would break the slot it is written into.`);
223
+ }
224
+ const span = [
225
+ renderMarker(style, slot.indent, AnchorMarkerKind.CONTRIBUTION, AnchorMarkerEdge.START, [input.blueprintId, input.slotId]),
226
+ ...bodyLines,
227
+ renderMarker(style, slot.indent, AnchorMarkerKind.CONTRIBUTION, AnchorMarkerEdge.END, [input.blueprintId, input.slotId]),
228
+ ];
229
+ const spanTerminators = span.map(() => eol);
230
+ const existing = slot.contributions.find((contribution) => contribution.blueprintId === input.blueprintId);
231
+ const [from, to] = existing === undefined ? [slot.endLine, slot.endLine] : [existing.startLine, existing.endLine + 1];
232
+ const written = joinLines([...lines.slice(0, from), ...span, ...lines.slice(to)], [...terminators.slice(0, from), ...spanTerminators, ...terminators.slice(to)]);
233
+ if (written === content)
234
+ return content;
235
+ // Re-read what is about to be written: a write must never leave a file the next read refuses.
236
+ readAnchorSlots(written, style);
237
+ return written;
238
+ }
239
+ /**
240
+ * A slot's whole text with every contribution marker removed and blank lines trimmed at both ends: what a reader
241
+ * sees there, whoever wrote it. Two files whose slots read the same this way say the same thing, which is how an
242
+ * export compares the slot it reproduces with the one the defining application holds.
243
+ */
244
+ export function readableAnchorSlotText(content, style, slotId) {
245
+ const slot = readAnchorSlots(content, style).get(slotId);
246
+ if (slot === undefined)
247
+ return undefined;
248
+ const { lines } = splitLines(content);
249
+ return trimBlankLines(lines.slice(slot.startLine + 1, slot.endLine).filter((line) => {
250
+ const marker = parseMarker(line, style);
251
+ return marker === null || marker.kind !== AnchorMarkerKind.CONTRIBUTION;
252
+ }));
253
+ }
254
+ /** The file's content with every contribution marker line removed — for comparing files that differ only by them. */
255
+ export function withoutAnchorContributionMarkers(content, style) {
256
+ const { lines, terminators } = splitLines(content);
257
+ const kept = lines.map((line, index) => ({ line, terminator: terminators[index] ?? '' })).filter(({ line }) => {
258
+ const marker = parseMarker(line, style);
259
+ return marker === null || marker.kind !== AnchorMarkerKind.CONTRIBUTION;
260
+ });
261
+ return joinLines(kept.map(({ line }) => line), kept.map(({ terminator }) => terminator));
262
+ }
263
+ //# sourceMappingURL=anchored-region.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"anchored-region.js","sourceRoot":"","sources":["../../../../src/blueprint/anchored-region.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Anchor SLOTS and blueprint CONTRIBUTIONS in free text (epic #2856, #2862) — the grammar, read and write.\n *\n * A slot is an extension point a base file declares; a blueprint writes its text inside it as a contribution span\n * of its own, so layers stack in order and each one's text stays identifiable:\n *\n * ```markdown\n * <!-- @wildo_anchor:slot:start application.guide -->\n * <!-- @wildo_anchor:contribution:start acme/internal-tool application.guide -->\n * The layer's text.\n * <!-- @wildo_anchor:contribution:end acme/internal-tool application.guide -->\n * <!-- @wildo_anchor:slot:end application.guide -->\n * ```\n *\n * Only free text needs this. A TypeScript base file exposes NAMED DECLARATIONS a blueprint sets instead\n * (`BlueprintDeclarationFile`), which is the preferred and far more common shape: measured on Wonder Procurement\n * (#2860), the agent guide was the one change to a base file that was not the value of a declaration.\n *\n * ## Strict, like the writer it is modelled on\n *\n * The rules are those of `rewriteNginxCspMarkerPairsString` (`project-config/shared/csp-emit.ts`): a marker is a\n * whole line; a nested slot, an end with no start, an unclosed span, a slot declared twice, a contribution outside its\n * slot or naming another slot all REFUSE, because a guess at a damaged boundary writes text into the wrong place. So\n * does any other comment line opening with `@wildo_anchor:` (a third argument, text after the marker): a damaged\n * marker never reads as plain text, while prose that only mentions the family does. In Markdown, lines inside a code fence are text, so a guide can SHOW the markers. A contribution body\n * may not contain a marker line, and every write re-reads its own result.\n *\n * Indentation is kept, every line keeps its own terminator (a file mixing `\\n` and `\\r\\n` stays mixed; added lines\n * take the more common one), and a write that changes nothing returns the input unchanged.\n *\n * The marker family is deliberately not `@wildo_source`: that one is an extraction contract for framework knowledge,\n * and a refactor of what knowledge extracts must never move a place applications are written into.\n */\n\n/** How a file writes a whole-line comment. */\nexport enum AnchorCommentStyle {\n /** Markdown and HTML: `<!-- … -->`. Survives a Handlebars render, which `{{!-- --}}` would not. */\n HTML = 'html',\n /** TypeScript and JavaScript: `// …`. */\n LINE_SLASH = 'line-slash',\n /** YAML, shell, Dockerfile, `.gitignore`: `# …`. */\n HASH = 'hash',\n}\n\n/** The comment style of a file, by its name. */\nexport function anchorCommentStyleForPath(path: string): AnchorCommentStyle {\n const name = path.split('/').pop() ?? path;\n if (/\\.(md|mdx|html?)$/i.test(name)) return AnchorCommentStyle.HTML;\n if (/\\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i.test(name)) return AnchorCommentStyle.LINE_SLASH;\n if (/\\.(ya?ml|sh|toml)$/i.test(name) || name === 'Dockerfile' || name.startsWith('.')) return AnchorCommentStyle.HASH;\n throw new Error(`No anchor comment style is defined for ${path}.`);\n}\n\n/** What a marker line opens or closes. */\nenum AnchorMarkerKind {\n SLOT = 'slot',\n CONTRIBUTION = 'contribution',\n}\n\n/** Which end of a span a marker line is. */\nenum AnchorMarkerEdge {\n START = 'start',\n END = 'end',\n}\n\ninterface MarkerLine {\n readonly kind: AnchorMarkerKind;\n readonly edge: AnchorMarkerEdge;\n /** Slot: `[slotId]`. Contribution: `[blueprintId, slotId]`. */\n readonly args: readonly string[];\n readonly indent: string;\n}\n\nconst MARKER_BODY = '@wildo_anchor:(slot|contribution):(start|end)\\\\s+(\\\\S+(?:\\\\s+\\\\S+)?)';\n/** The marker family, as text. A contribution body may not contain it at all. */\nconst MARKER_FAMILY = '@wildo_anchor:';\n/**\n * A line that OPENS a comment with the marker family — what a marker looks like. One that is not a well-formed marker\n * refuses rather than reading as text. Prose that merely MENTIONS the family (\"the `@wildo_anchor:slot` markers\") is\n * text, so a guide can talk about its own slots.\n */\nconst MARKER_SHAPED_LINES: Readonly<Record<AnchorCommentStyle, RegExp>> = {\n [AnchorCommentStyle.HTML]: /^\\s*<!--\\s*@wildo_anchor:/,\n [AnchorCommentStyle.LINE_SLASH]: /^\\s*\\/\\/\\s*@wildo_anchor:/,\n [AnchorCommentStyle.HASH]: /^\\s*#\\s*@wildo_anchor:/,\n};\n/** A Markdown code fence: markers shown inside one are an example, not a slot. */\nconst CODE_FENCE_PATTERN = /^\\s*(```|~~~)/;\nconst MARKER_PATTERNS: Readonly<Record<AnchorCommentStyle, RegExp>> = {\n [AnchorCommentStyle.HTML]: new RegExp(`^(\\\\s*)<!--\\\\s*${MARKER_BODY}\\\\s*-->\\\\s*$`),\n [AnchorCommentStyle.LINE_SLASH]: new RegExp(`^(\\\\s*)//\\\\s*${MARKER_BODY}\\\\s*$`),\n [AnchorCommentStyle.HASH]: new RegExp(`^(\\\\s*)#\\\\s*${MARKER_BODY}\\\\s*$`),\n};\n\nfunction parseMarker(line: string, style: AnchorCommentStyle): MarkerLine | null {\n const match = MARKER_PATTERNS[style].exec(line);\n if (match === null) return null;\n return {\n kind: match[2] as AnchorMarkerKind,\n edge: match[3] as AnchorMarkerEdge,\n args: (match[4] ?? '').split(/\\s+/),\n indent: match[1] ?? '',\n };\n}\n\nfunction renderMarker(style: AnchorCommentStyle, indent: string, kind: AnchorMarkerKind, edge: AnchorMarkerEdge, args: readonly string[]): string {\n const body = `@wildo_anchor:${kind}:${edge} ${args.join(' ')}`;\n switch (style) {\n case AnchorCommentStyle.HTML:\n return `${indent}<!-- ${body} -->`;\n case AnchorCommentStyle.LINE_SLASH:\n return `${indent}// ${body}`;\n case AnchorCommentStyle.HASH:\n return `${indent}# ${body}`;\n }\n}\n\n/** One contribution span inside a slot. Line numbers are zero-based indexes into the file's lines. */\nexport interface AnchorContribution {\n readonly blueprintId: string;\n readonly startLine: number;\n readonly endLine: number;\n /** The span's text, markers excluded. */\n readonly body: string;\n}\n\n/** One slot as the file holds it. */\nexport interface AnchorSlot {\n readonly id: string;\n readonly startLine: number;\n readonly endLine: number;\n readonly indent: string;\n readonly contributions: readonly AnchorContribution[];\n /** The slot's text OUTSIDE every contribution span — what the application wrote there itself. */\n readonly ownText: string;\n}\n\n/**\n * The file's lines, each line's own terminator (the last one's is `''`), and the terminator new lines get: the one\n * the file uses most. Keeping each terminator is what lets a write leave every line it did not add byte-identical,\n * even in a file that mixes `\\n` and `\\r\\n`.\n */\nfunction splitLines(content: string): { lines: string[]; terminators: string[]; eol: string } {\n const lines: string[] = [];\n const terminators: string[] = [];\n const pattern = /\\r?\\n/g;\n let start = 0;\n for (const match of content.matchAll(pattern)) {\n lines.push(content.slice(start, match.index));\n terminators.push(match[0]);\n start = (match.index ?? 0) + match[0].length;\n }\n lines.push(content.slice(start));\n terminators.push('');\n const crlf = terminators.filter((terminator) => terminator === '\\r\\n').length;\n const lf = terminators.filter((terminator) => terminator === '\\n').length;\n return { lines, terminators, eol: crlf > lf ? '\\r\\n' : '\\n' };\n}\n\nfunction joinLines(lines: readonly string[], terminators: readonly string[]): string {\n return lines.map((line, index) => `${line}${terminators[index] ?? ''}`).join('');\n}\n\n/** Drop blank lines at both ends of a text block. */\nfunction trimBlankLines(lines: readonly string[]): string {\n let start = 0;\n let end = lines.length;\n while (start < end && lines[start]?.trim() === '') start += 1;\n while (end > start && lines[end - 1]?.trim() === '') end -= 1;\n return lines.slice(start, end).join('\\n');\n}\n\n/** Every slot of a file, by id. Refuses a damaged structure rather than reading around it. */\nexport function readAnchorSlots(content: string, style: AnchorCommentStyle): ReadonlyMap<string, AnchorSlot> {\n const { lines } = splitLines(content);\n const slots = new Map<string, AnchorSlot>();\n let open: { id: string; startLine: number; indent: string; contributions: AnchorContribution[]; own: string[] } | null = null;\n let openContribution: { blueprintId: string; startLine: number; body: string[] } | null = null;\n let insideFence = false;\n lines.forEach((line, index) => {\n const where = `line ${index + 1}`;\n if (style === AnchorCommentStyle.HTML && CODE_FENCE_PATTERN.test(line)) insideFence = !insideFence;\n const marker = insideFence ? null : parseMarker(line, style);\n if (marker === null && !insideFence && MARKER_SHAPED_LINES[style].test(line)) {\n throw new Error(`The ${MARKER_FAMILY} line at ${where} is not a well-formed marker (a slot names one id, a contribution a blueprint and a slot, and the marker is the whole line).`);\n }\n if (marker === null) {\n if (openContribution !== null) openContribution.body.push(line);\n else if (open !== null) open.own.push(line);\n return;\n }\n if (marker.kind === AnchorMarkerKind.SLOT) {\n const [id] = marker.args;\n if (marker.args.length !== 1 || id === undefined) throw new Error(`Anchor slot marker at ${where} must name exactly one slot.`);\n if (marker.edge === AnchorMarkerEdge.START) {\n if (open !== null) throw new Error(`Anchor slot '${id}' at ${where} opens inside slot '${open.id}': slots do not nest.`);\n if (slots.has(id)) throw new Error(`Anchor slot '${id}' is declared twice (again at ${where}).`);\n open = { id, startLine: index, indent: marker.indent, contributions: [], own: [] };\n return;\n }\n if (open === null || open.id !== id) throw new Error(`Anchor slot end '${id}' at ${where} closes no open slot of that name.`);\n if (openContribution !== null) throw new Error(`Anchor slot '${id}' closes at ${where} inside an unclosed contribution of '${openContribution.blueprintId}'.`);\n slots.set(id, { id, startLine: open.startLine, endLine: index, indent: open.indent, contributions: open.contributions, ownText: trimBlankLines(open.own) });\n open = null;\n return;\n }\n const [blueprintId, slotId] = marker.args;\n if (marker.args.length !== 2 || blueprintId === undefined || slotId === undefined) {\n throw new Error(`Anchor contribution marker at ${where} must name a blueprint and a slot.`);\n }\n if (open === null || open.id !== slotId) throw new Error(`Contribution of '${blueprintId}' at ${where} names slot '${slotId}' but sits outside it.`);\n if (marker.edge === AnchorMarkerEdge.START) {\n if (openContribution !== null) throw new Error(`Contribution of '${blueprintId}' at ${where} opens inside the contribution of '${openContribution.blueprintId}'.`);\n if (open.contributions.some((contribution) => contribution.blueprintId === blueprintId)) {\n throw new Error(`Blueprint '${blueprintId}' contributes to slot '${slotId}' twice (again at ${where}).`);\n }\n openContribution = { blueprintId, startLine: index, body: [] };\n return;\n }\n if (openContribution === null || openContribution.blueprintId !== blueprintId) {\n throw new Error(`Contribution end of '${blueprintId}' at ${where} closes no open contribution of that blueprint.`);\n }\n open.contributions.push({ blueprintId, startLine: openContribution.startLine, endLine: index, body: openContribution.body.join('\\n') });\n openContribution = null;\n });\n if (open !== null) throw new Error(`Anchor slot '${(open as { id: string }).id}' is never closed.`);\n return slots;\n}\n\n/**\n * Write `body` as `blueprintId`'s contribution to `slotId`: replace its existing span, or add one just before the\n * slot's end marker (after every earlier layer's). Refuses a slot the file does not declare. Returns the content\n * unchanged when the span already holds exactly this body.\n */\nexport function writeAnchorContribution(\n content: string,\n style: AnchorCommentStyle,\n input: { readonly slotId: string; readonly blueprintId: string; readonly body: string },\n): string {\n const slot = readAnchorSlots(content, style).get(input.slotId);\n if (slot === undefined) throw new Error(`No anchor slot '${input.slotId}' is declared in this file.`);\n const { lines, terminators, eol } = splitLines(content);\n const bodyLines = input.body === '' ? [] : input.body.replace(/\\r?\\n$/, '').split(/\\r?\\n/);\n if (bodyLines.some((line) => line.includes(MARKER_FAMILY))) {\n throw new Error(`The contribution of '${input.blueprintId}' to slot '${input.slotId}' contains a ${MARKER_FAMILY} line, which would break the slot it is written into.`);\n }\n const span = [\n renderMarker(style, slot.indent, AnchorMarkerKind.CONTRIBUTION, AnchorMarkerEdge.START, [input.blueprintId, input.slotId]),\n ...bodyLines,\n renderMarker(style, slot.indent, AnchorMarkerKind.CONTRIBUTION, AnchorMarkerEdge.END, [input.blueprintId, input.slotId]),\n ];\n const spanTerminators = span.map(() => eol);\n const existing = slot.contributions.find((contribution) => contribution.blueprintId === input.blueprintId);\n const [from, to] = existing === undefined ? [slot.endLine, slot.endLine] : [existing.startLine, existing.endLine + 1];\n const written = joinLines(\n [...lines.slice(0, from), ...span, ...lines.slice(to)],\n [...terminators.slice(0, from), ...spanTerminators, ...terminators.slice(to)],\n );\n if (written === content) return content;\n // Re-read what is about to be written: a write must never leave a file the next read refuses.\n readAnchorSlots(written, style);\n return written;\n}\n\n/**\n * A slot's whole text with every contribution marker removed and blank lines trimmed at both ends: what a reader\n * sees there, whoever wrote it. Two files whose slots read the same this way say the same thing, which is how an\n * export compares the slot it reproduces with the one the defining application holds.\n */\nexport function readableAnchorSlotText(content: string, style: AnchorCommentStyle, slotId: string): string | undefined {\n const slot = readAnchorSlots(content, style).get(slotId);\n if (slot === undefined) return undefined;\n const { lines } = splitLines(content);\n return trimBlankLines(lines.slice(slot.startLine + 1, slot.endLine).filter((line) => {\n const marker = parseMarker(line, style);\n return marker === null || marker.kind !== AnchorMarkerKind.CONTRIBUTION;\n }));\n}\n\n/** The file's content with every contribution marker line removed — for comparing files that differ only by them. */\nexport function withoutAnchorContributionMarkers(content: string, style: AnchorCommentStyle): string {\n const { lines, terminators } = splitLines(content);\n const kept = lines.map((line, index) => ({ line, terminator: terminators[index] ?? '' })).filter(({ line }) => {\n const marker = parseMarker(line, style);\n return marker === null || marker.kind !== AnchorMarkerKind.CONTRIBUTION;\n });\n return joinLines(kept.map(({ line }) => line), kept.map(({ terminator }) => terminator));\n}\n"]}