zod-args-parser 2.0.0-beta.1 → 2.0.0-beta.3

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 (474) hide show
  1. package/LICENSE +1 -0
  2. package/README.md +244 -282
  3. package/lib/esm/autocomplete-scripts/bash-autocomplete-script.js +74 -2
  4. package/lib/esm/autocomplete-scripts/bash-autocomplete-script.js.map +7 -1
  5. package/lib/esm/autocomplete-scripts/powershell-autocomplete-script.js +90 -2
  6. package/lib/esm/autocomplete-scripts/powershell-autocomplete-script.js.map +7 -1
  7. package/lib/esm/autocomplete-scripts/zsh-autocomplete-script.js +39 -13
  8. package/lib/esm/autocomplete-scripts/zsh-autocomplete-script.js.map +7 -1
  9. package/lib/esm/cli-error/cli-error.js +38 -0
  10. package/lib/esm/cli-error/cli-error.js.map +7 -0
  11. package/lib/esm/cli-error/error-cause.js +12 -0
  12. package/lib/esm/cli-error/error-cause.js.map +7 -0
  13. package/lib/esm/cli-error/error-code/definition-error-code.js +23 -0
  14. package/lib/esm/cli-error/error-code/definition-error-code.js.map +7 -0
  15. package/lib/esm/cli-error/error-code/internal-error-code.js +10 -0
  16. package/lib/esm/cli-error/error-code/internal-error-code.js.map +7 -0
  17. package/lib/esm/cli-error/error-code/parse-error-code.js +18 -0
  18. package/lib/esm/cli-error/error-code/parse-error-code.js.map +7 -0
  19. package/lib/esm/cli-error/error-code/validation-error-code.js +17 -0
  20. package/lib/esm/cli-error/error-code/validation-error-code.js.map +7 -0
  21. package/lib/esm/cli-error/error-message/definition-error-message.js +70 -0
  22. package/lib/esm/cli-error/error-message/definition-error-message.js.map +7 -0
  23. package/lib/esm/cli-error/error-message/internal-error-message.js +16 -0
  24. package/lib/esm/cli-error/error-message/internal-error-message.js.map +7 -0
  25. package/lib/esm/cli-error/error-message/parse-error-message.js +40 -0
  26. package/lib/esm/cli-error/error-message/parse-error-message.js.map +7 -0
  27. package/lib/esm/cli-error/error-message/validation-error-message.js +60 -0
  28. package/lib/esm/cli-error/error-message/validation-error-message.js.map +7 -0
  29. package/lib/esm/coerce/coerce-methods.js +197 -2
  30. package/lib/esm/coerce/coerce-methods.js.map +7 -1
  31. package/lib/esm/coerce/string-to-array.js +17 -2
  32. package/lib/esm/coerce/string-to-array.js.map +7 -1
  33. package/lib/esm/coerce/string-to-primitive.js +73 -2
  34. package/lib/esm/coerce/string-to-primitive.js.map +7 -1
  35. package/lib/esm/coerce/string-to-set.js +17 -2
  36. package/lib/esm/coerce/string-to-set.js.map +7 -1
  37. package/lib/esm/definitions/define-arguments.js +10 -2
  38. package/lib/esm/definitions/define-arguments.js.map +7 -1
  39. package/lib/esm/definitions/define-cli.js +89 -2
  40. package/lib/esm/definitions/define-cli.js.map +7 -1
  41. package/lib/esm/definitions/define-options.js +10 -2
  42. package/lib/esm/definitions/define-options.js.map +7 -1
  43. package/lib/esm/definitions/define-subcommand.js +56 -2
  44. package/lib/esm/definitions/define-subcommand.js.map +7 -1
  45. package/lib/esm/definitions/validate-cli-definition.js +360 -2
  46. package/lib/esm/definitions/validate-cli-definition.js.map +7 -1
  47. package/lib/esm/help-message/format-arguments.js +48 -2
  48. package/lib/esm/help-message/format-arguments.js.map +7 -1
  49. package/lib/esm/help-message/format-options.js +50 -2
  50. package/lib/esm/help-message/format-options.js.map +7 -1
  51. package/lib/esm/help-message/format-subcommands.js +37 -2
  52. package/lib/esm/help-message/format-subcommands.js.map +7 -1
  53. package/lib/esm/help-message/generate-for-cli.js +71 -2
  54. package/lib/esm/help-message/generate-for-cli.js.map +7 -1
  55. package/lib/esm/help-message/generate-for-subcommand.js +23 -2
  56. package/lib/esm/help-message/generate-for-subcommand.js.map +7 -1
  57. package/lib/esm/help-message/print-help.js +14 -2
  58. package/lib/esm/help-message/print-help.js.map +7 -1
  59. package/lib/esm/help-message/set-defaults.js +29 -2
  60. package/lib/esm/help-message/set-defaults.js.map +7 -1
  61. package/lib/esm/help-message/styles.js +154 -2
  62. package/lib/esm/help-message/styles.js.map +7 -1
  63. package/lib/esm/help-message/terminal-markdown.js +121 -2
  64. package/lib/esm/help-message/terminal-markdown.js.map +7 -1
  65. package/lib/esm/index.js +52 -2
  66. package/lib/esm/index.js.map +7 -1
  67. package/lib/esm/markdown/generate-markdown.js +153 -2
  68. package/lib/esm/markdown/generate-markdown.js.map +7 -1
  69. package/lib/esm/metadata/arguments-metadata.js +26 -2
  70. package/lib/esm/metadata/arguments-metadata.js.map +7 -1
  71. package/lib/esm/metadata/cli-metadata.js +24 -2
  72. package/lib/esm/metadata/cli-metadata.js.map +7 -1
  73. package/lib/esm/metadata/options-metadata.js +35 -2
  74. package/lib/esm/metadata/options-metadata.js.map +7 -1
  75. package/lib/esm/metadata/subcommands-metadata.js +32 -2
  76. package/lib/esm/metadata/subcommands-metadata.js.map +7 -1
  77. package/lib/esm/parse/context/cli-context-builder.js +283 -2
  78. package/lib/esm/parse/context/cli-context-builder.js.map +7 -1
  79. package/lib/esm/parse/context/object-context-builder.js +62 -2
  80. package/lib/esm/parse/context/object-context-builder.js.map +7 -1
  81. package/lib/esm/parse/parser-utilities.js +108 -2
  82. package/lib/esm/parse/parser-utilities.js.map +7 -1
  83. package/lib/esm/parse/safe-parse.js +57 -2
  84. package/lib/esm/parse/safe-parse.js.map +7 -1
  85. package/lib/esm/parse/validation/validate-context.js +17 -2
  86. package/lib/esm/parse/validation/validate-context.js.map +7 -1
  87. package/lib/esm/parse/validation/validators/arguments.js +67 -2
  88. package/lib/esm/parse/validation/validators/arguments.js.map +7 -1
  89. package/lib/esm/parse/validation/validators/conflict.js +38 -2
  90. package/lib/esm/parse/validation/validators/conflict.js.map +7 -1
  91. package/lib/esm/parse/validation/validators/exclusive.js +39 -2
  92. package/lib/esm/parse/validation/validators/exclusive.js.map +7 -1
  93. package/lib/esm/parse/validation/validators/explicitly-passed.js +18 -2
  94. package/lib/esm/parse/validation/validators/explicitly-passed.js.map +7 -1
  95. package/lib/esm/parse/validation/validators/options.js +67 -2
  96. package/lib/esm/parse/validation/validators/options.js.map +7 -1
  97. package/lib/esm/parse/validation/validators/requires.js +43 -2
  98. package/lib/esm/parse/validation/validators/requires.js.map +7 -1
  99. package/lib/esm/utilities/parse-argv.js +61 -0
  100. package/lib/esm/utilities/parse-argv.js.map +7 -0
  101. package/lib/esm/utilities/schema-utilities.js +57 -0
  102. package/lib/esm/utilities/schema-utilities.js.map +7 -0
  103. package/lib/esm/utilities/utilities.js +122 -0
  104. package/lib/esm/utilities/utilities.js.map +7 -0
  105. package/lib/iife/index.js +41 -1
  106. package/lib/iife/index.js.map +1 -1
  107. package/lib/mjs/autocomplete-scripts/bash-autocomplete-script.mjs +74 -2
  108. package/lib/mjs/autocomplete-scripts/bash-autocomplete-script.mjs.map +7 -1
  109. package/lib/mjs/autocomplete-scripts/powershell-autocomplete-script.mjs +90 -2
  110. package/lib/mjs/autocomplete-scripts/powershell-autocomplete-script.mjs.map +7 -1
  111. package/lib/mjs/autocomplete-scripts/zsh-autocomplete-script.mjs +39 -13
  112. package/lib/mjs/autocomplete-scripts/zsh-autocomplete-script.mjs.map +7 -1
  113. package/lib/mjs/cli-error/cli-error.mjs +38 -0
  114. package/lib/mjs/cli-error/cli-error.mjs.map +7 -0
  115. package/lib/mjs/cli-error/error-cause.mjs +12 -0
  116. package/lib/mjs/cli-error/error-cause.mjs.map +7 -0
  117. package/lib/mjs/cli-error/error-code/definition-error-code.mjs +23 -0
  118. package/lib/mjs/cli-error/error-code/definition-error-code.mjs.map +7 -0
  119. package/lib/mjs/cli-error/error-code/internal-error-code.mjs +10 -0
  120. package/lib/mjs/cli-error/error-code/internal-error-code.mjs.map +7 -0
  121. package/lib/mjs/cli-error/error-code/parse-error-code.mjs +18 -0
  122. package/lib/mjs/cli-error/error-code/parse-error-code.mjs.map +7 -0
  123. package/lib/mjs/cli-error/error-code/validation-error-code.mjs +17 -0
  124. package/lib/mjs/cli-error/error-code/validation-error-code.mjs.map +7 -0
  125. package/lib/mjs/cli-error/error-message/definition-error-message.mjs +70 -0
  126. package/lib/mjs/cli-error/error-message/definition-error-message.mjs.map +7 -0
  127. package/lib/mjs/cli-error/error-message/internal-error-message.mjs +16 -0
  128. package/lib/mjs/cli-error/error-message/internal-error-message.mjs.map +7 -0
  129. package/lib/mjs/cli-error/error-message/parse-error-message.mjs +40 -0
  130. package/lib/mjs/cli-error/error-message/parse-error-message.mjs.map +7 -0
  131. package/lib/mjs/cli-error/error-message/validation-error-message.mjs +60 -0
  132. package/lib/mjs/cli-error/error-message/validation-error-message.mjs.map +7 -0
  133. package/lib/mjs/coerce/coerce-methods.mjs +197 -2
  134. package/lib/mjs/coerce/coerce-methods.mjs.map +7 -1
  135. package/lib/mjs/coerce/string-to-array.mjs +17 -2
  136. package/lib/mjs/coerce/string-to-array.mjs.map +7 -1
  137. package/lib/mjs/coerce/string-to-primitive.mjs +73 -2
  138. package/lib/mjs/coerce/string-to-primitive.mjs.map +7 -1
  139. package/lib/mjs/coerce/string-to-set.mjs +17 -2
  140. package/lib/mjs/coerce/string-to-set.mjs.map +7 -1
  141. package/lib/mjs/definitions/define-arguments.mjs +10 -2
  142. package/lib/mjs/definitions/define-arguments.mjs.map +7 -1
  143. package/lib/mjs/definitions/define-cli.mjs +89 -2
  144. package/lib/mjs/definitions/define-cli.mjs.map +7 -1
  145. package/lib/mjs/definitions/define-options.mjs +10 -2
  146. package/lib/mjs/definitions/define-options.mjs.map +7 -1
  147. package/lib/mjs/definitions/define-subcommand.mjs +56 -2
  148. package/lib/mjs/definitions/define-subcommand.mjs.map +7 -1
  149. package/lib/mjs/definitions/validate-cli-definition.mjs +360 -2
  150. package/lib/mjs/definitions/validate-cli-definition.mjs.map +7 -1
  151. package/lib/mjs/help-message/format-arguments.mjs +48 -2
  152. package/lib/mjs/help-message/format-arguments.mjs.map +7 -1
  153. package/lib/mjs/help-message/format-options.mjs +50 -2
  154. package/lib/mjs/help-message/format-options.mjs.map +7 -1
  155. package/lib/mjs/help-message/format-subcommands.mjs +37 -2
  156. package/lib/mjs/help-message/format-subcommands.mjs.map +7 -1
  157. package/lib/mjs/help-message/generate-for-cli.mjs +71 -2
  158. package/lib/mjs/help-message/generate-for-cli.mjs.map +7 -1
  159. package/lib/mjs/help-message/generate-for-subcommand.mjs +23 -2
  160. package/lib/mjs/help-message/generate-for-subcommand.mjs.map +7 -1
  161. package/lib/mjs/help-message/print-help.mjs +14 -2
  162. package/lib/mjs/help-message/print-help.mjs.map +7 -1
  163. package/lib/mjs/help-message/set-defaults.mjs +29 -2
  164. package/lib/mjs/help-message/set-defaults.mjs.map +7 -1
  165. package/lib/mjs/help-message/styles.mjs +154 -2
  166. package/lib/mjs/help-message/styles.mjs.map +7 -1
  167. package/lib/mjs/help-message/terminal-markdown.mjs +121 -2
  168. package/lib/mjs/help-message/terminal-markdown.mjs.map +7 -1
  169. package/lib/mjs/index.mjs +52 -2
  170. package/lib/mjs/index.mjs.map +7 -1
  171. package/lib/mjs/markdown/generate-markdown.mjs +153 -2
  172. package/lib/mjs/markdown/generate-markdown.mjs.map +7 -1
  173. package/lib/mjs/metadata/arguments-metadata.mjs +26 -2
  174. package/lib/mjs/metadata/arguments-metadata.mjs.map +7 -1
  175. package/lib/mjs/metadata/cli-metadata.mjs +24 -2
  176. package/lib/mjs/metadata/cli-metadata.mjs.map +7 -1
  177. package/lib/mjs/metadata/options-metadata.mjs +35 -2
  178. package/lib/mjs/metadata/options-metadata.mjs.map +7 -1
  179. package/lib/mjs/metadata/subcommands-metadata.mjs +32 -2
  180. package/lib/mjs/metadata/subcommands-metadata.mjs.map +7 -1
  181. package/lib/mjs/parse/context/cli-context-builder.mjs +283 -2
  182. package/lib/mjs/parse/context/cli-context-builder.mjs.map +7 -1
  183. package/lib/mjs/parse/context/object-context-builder.mjs +62 -2
  184. package/lib/mjs/parse/context/object-context-builder.mjs.map +7 -1
  185. package/lib/mjs/parse/parser-utilities.mjs +108 -2
  186. package/lib/mjs/parse/parser-utilities.mjs.map +7 -1
  187. package/lib/mjs/parse/safe-parse.mjs +57 -2
  188. package/lib/mjs/parse/safe-parse.mjs.map +7 -1
  189. package/lib/mjs/parse/validation/validate-context.mjs +17 -2
  190. package/lib/mjs/parse/validation/validate-context.mjs.map +7 -1
  191. package/lib/mjs/parse/validation/validators/arguments.mjs +67 -2
  192. package/lib/mjs/parse/validation/validators/arguments.mjs.map +7 -1
  193. package/lib/mjs/parse/validation/validators/conflict.mjs +38 -2
  194. package/lib/mjs/parse/validation/validators/conflict.mjs.map +7 -1
  195. package/lib/mjs/parse/validation/validators/exclusive.mjs +39 -2
  196. package/lib/mjs/parse/validation/validators/exclusive.mjs.map +7 -1
  197. package/lib/mjs/parse/validation/validators/explicitly-passed.mjs +18 -2
  198. package/lib/mjs/parse/validation/validators/explicitly-passed.mjs.map +7 -1
  199. package/lib/mjs/parse/validation/validators/options.mjs +67 -2
  200. package/lib/mjs/parse/validation/validators/options.mjs.map +7 -1
  201. package/lib/mjs/parse/validation/validators/requires.mjs +43 -2
  202. package/lib/mjs/parse/validation/validators/requires.mjs.map +7 -1
  203. package/lib/mjs/utilities/parse-argv.mjs +61 -0
  204. package/lib/mjs/utilities/parse-argv.mjs.map +7 -0
  205. package/lib/mjs/utilities/schema-utilities.mjs +57 -0
  206. package/lib/mjs/utilities/schema-utilities.mjs.map +7 -0
  207. package/lib/mjs/utilities/utilities.mjs +122 -0
  208. package/lib/mjs/utilities/utilities.mjs.map +7 -0
  209. package/lib/{typescript → types}/autocomplete-scripts/bash-autocomplete-script.d.ts.map +1 -1
  210. package/lib/types/autocomplete-scripts/powershell-autocomplete-script.d.ts +15 -0
  211. package/lib/{typescript → types}/autocomplete-scripts/powershell-autocomplete-script.d.ts.map +1 -1
  212. package/lib/types/autocomplete-scripts/zsh-autocomplete-script.d.ts +4 -0
  213. package/lib/{typescript → types}/autocomplete-scripts/zsh-autocomplete-script.d.ts.map +1 -1
  214. package/lib/types/cli-error/cli-error.d.ts +152 -0
  215. package/lib/types/cli-error/cli-error.d.ts.map +1 -0
  216. package/lib/types/cli-error/error-cause.d.ts +5 -0
  217. package/lib/types/cli-error/error-cause.d.ts.map +1 -0
  218. package/lib/types/cli-error/error-code/definition-error-code.d.ts +5 -0
  219. package/lib/types/cli-error/error-code/definition-error-code.d.ts.map +1 -0
  220. package/lib/types/cli-error/error-code/internal-error-code.d.ts +5 -0
  221. package/lib/types/cli-error/error-code/internal-error-code.d.ts.map +1 -0
  222. package/lib/types/cli-error/error-code/parse-error-code.d.ts +5 -0
  223. package/lib/types/cli-error/error-code/parse-error-code.d.ts.map +1 -0
  224. package/lib/types/cli-error/error-code/validation-error-code.d.ts +5 -0
  225. package/lib/types/cli-error/error-code/validation-error-code.d.ts.map +1 -0
  226. package/lib/types/cli-error/error-message/definition-error-message.d.ts +3 -0
  227. package/lib/types/cli-error/error-message/definition-error-message.d.ts.map +1 -0
  228. package/lib/types/cli-error/error-message/internal-error-message.d.ts +3 -0
  229. package/lib/types/cli-error/error-message/internal-error-message.d.ts.map +1 -0
  230. package/lib/types/cli-error/error-message/parse-error-message.d.ts +3 -0
  231. package/lib/types/cli-error/error-message/parse-error-message.d.ts.map +1 -0
  232. package/lib/types/cli-error/error-message/validation-error-message.d.ts +3 -0
  233. package/lib/types/cli-error/error-message/validation-error-message.d.ts.map +1 -0
  234. package/lib/types/coerce/coerce-methods.d.ts +122 -0
  235. package/lib/types/coerce/coerce-methods.d.ts.map +1 -0
  236. package/lib/{typescript → types}/coerce/string-to-array.d.ts +2 -2
  237. package/lib/types/coerce/string-to-array.d.ts.map +1 -0
  238. package/lib/types/coerce/string-to-primitive.d.ts +21 -0
  239. package/lib/types/coerce/string-to-primitive.d.ts.map +1 -0
  240. package/lib/{typescript → types}/coerce/string-to-set.d.ts +2 -2
  241. package/lib/{typescript → types}/coerce/string-to-set.d.ts.map +1 -1
  242. package/lib/{typescript → types}/definitions/define-cli.d.ts +2 -6
  243. package/lib/types/definitions/define-cli.d.ts.map +1 -0
  244. package/lib/{typescript → types}/definitions/define-subcommand.d.ts +2 -4
  245. package/lib/types/definitions/define-subcommand.d.ts.map +1 -0
  246. package/lib/{typescript → types}/definitions/validate-cli-definition.d.ts +1 -1
  247. package/lib/types/definitions/validate-cli-definition.d.ts.map +1 -0
  248. package/lib/{typescript → types}/help-message/terminal-markdown.d.ts.map +1 -1
  249. package/lib/{typescript → types}/index.d.ts +7 -0
  250. package/lib/{typescript → types}/index.d.ts.map +1 -1
  251. package/lib/{typescript → types}/metadata/arguments-metadata.d.ts.map +1 -1
  252. package/lib/{typescript → types}/metadata/options-metadata.d.ts.map +1 -1
  253. package/lib/{typescript → types}/parse/context/cli-context-builder.d.ts +1 -1
  254. package/lib/{typescript → types}/parse/context/cli-context-builder.d.ts.map +1 -1
  255. package/lib/{typescript → types}/parse/context/object-context-builder.d.ts +1 -1
  256. package/lib/types/parse/context/object-context-builder.d.ts.map +1 -0
  257. package/lib/{typescript → types}/parse/parser-utilities.d.ts +9 -0
  258. package/lib/{typescript → types}/parse/parser-utilities.d.ts.map +1 -1
  259. package/lib/{typescript → types}/parse/safe-parse.d.ts.map +1 -1
  260. package/lib/{typescript → types}/parse/validation/validate-context.d.ts +1 -1
  261. package/lib/{typescript → types}/parse/validation/validate-context.d.ts.map +1 -1
  262. package/lib/{typescript → types}/parse/validation/validators/arguments.d.ts +1 -1
  263. package/lib/{typescript → types}/parse/validation/validators/arguments.d.ts.map +1 -1
  264. package/lib/{typescript → types}/parse/validation/validators/conflict.d.ts +3 -3
  265. package/lib/{typescript → types}/parse/validation/validators/conflict.d.ts.map +1 -1
  266. package/lib/{typescript → types}/parse/validation/validators/exclusive.d.ts +3 -3
  267. package/lib/{typescript → types}/parse/validation/validators/exclusive.d.ts.map +1 -1
  268. package/lib/{typescript → types}/parse/validation/validators/options.d.ts +1 -1
  269. package/lib/{typescript → types}/parse/validation/validators/options.d.ts.map +1 -1
  270. package/lib/{typescript → types}/parse/validation/validators/requires.d.ts +3 -3
  271. package/lib/{typescript → types}/parse/validation/validators/requires.d.ts.map +1 -1
  272. package/lib/{typescript → types}/types/definitions-types.d.ts +35 -4
  273. package/lib/types/types/definitions-types.d.ts.map +1 -0
  274. package/lib/types/types/error-types.d.ts +275 -0
  275. package/lib/types/types/error-types.d.ts.map +1 -0
  276. package/lib/types/types/types.d.ts +146 -0
  277. package/lib/types/types/types.d.ts.map +1 -0
  278. package/lib/{typescript → types}/types/utilities-types.d.ts +0 -2
  279. package/lib/{typescript → types}/types/utilities-types.d.ts.map +1 -1
  280. package/lib/types/utilities/parse-argv.d.ts +3 -0
  281. package/lib/types/utilities/parse-argv.d.ts.map +1 -0
  282. package/lib/types/utilities/schema-utilities.d.ts +15 -0
  283. package/lib/types/utilities/schema-utilities.d.ts.map +1 -0
  284. package/lib/{typescript → types/utilities}/utilities.d.ts +12 -15
  285. package/lib/types/utilities/utilities.d.ts.map +1 -0
  286. package/package.json +10 -9
  287. package/src/autocomplete-scripts/bash-autocomplete-script.ts +14 -12
  288. package/src/autocomplete-scripts/powershell-autocomplete-script.ts +67 -33
  289. package/src/autocomplete-scripts/zsh-autocomplete-script.ts +39 -31
  290. package/src/cli-error/cli-error.ts +44 -0
  291. package/src/cli-error/error-cause.ts +10 -0
  292. package/src/cli-error/error-code/definition-error-code.ts +21 -0
  293. package/src/cli-error/error-code/internal-error-code.ts +8 -0
  294. package/src/cli-error/error-code/parse-error-code.ts +16 -0
  295. package/src/cli-error/error-code/validation-error-code.ts +15 -0
  296. package/src/cli-error/error-message/definition-error-message.ts +144 -0
  297. package/src/cli-error/error-message/internal-error-message.ts +19 -0
  298. package/src/cli-error/error-message/parse-error-message.ts +76 -0
  299. package/src/cli-error/error-message/validation-error-message.ts +104 -0
  300. package/src/coerce/coerce-methods.ts +194 -39
  301. package/src/coerce/string-to-array.ts +2 -2
  302. package/src/coerce/string-to-primitive.ts +72 -13
  303. package/src/coerce/string-to-set.ts +2 -2
  304. package/src/definitions/define-arguments.ts +1 -1
  305. package/src/definitions/define-cli.ts +65 -30
  306. package/src/definitions/define-options.ts +1 -1
  307. package/src/definitions/define-subcommand.ts +47 -17
  308. package/src/definitions/validate-cli-definition.ts +287 -172
  309. package/src/help-message/format-arguments.ts +1 -1
  310. package/src/help-message/format-options.ts +1 -1
  311. package/src/help-message/format-subcommands.ts +1 -1
  312. package/src/help-message/generate-for-cli.ts +1 -1
  313. package/src/help-message/terminal-markdown.ts +3 -4
  314. package/src/index.ts +16 -0
  315. package/src/markdown/generate-markdown.ts +5 -4
  316. package/src/metadata/arguments-metadata.ts +2 -1
  317. package/src/metadata/options-metadata.ts +2 -1
  318. package/src/parse/context/cli-context-builder.ts +166 -39
  319. package/src/parse/context/object-context-builder.ts +37 -11
  320. package/src/parse/parser-utilities.ts +24 -10
  321. package/src/parse/safe-parse.ts +3 -6
  322. package/src/parse/validation/validate-context.ts +1 -1
  323. package/src/parse/validation/validators/arguments.ts +42 -14
  324. package/src/parse/validation/validators/conflict.ts +11 -20
  325. package/src/parse/validation/validators/exclusive.ts +16 -25
  326. package/src/parse/validation/validators/options.ts +40 -12
  327. package/src/parse/validation/validators/requires.ts +11 -20
  328. package/src/types/definitions-types.ts +36 -8
  329. package/src/types/error-types.ts +326 -0
  330. package/src/types/types.ts +100 -7
  331. package/src/types/utilities-types.ts +0 -10
  332. package/src/utilities/parse-argv.ts +79 -0
  333. package/src/utilities/schema-utilities.ts +72 -0
  334. package/src/{utilities.ts → utilities/utilities.ts} +25 -138
  335. package/lib/cjs/autocomplete-scripts/bash-autocomplete-script.cjs +0 -2
  336. package/lib/cjs/autocomplete-scripts/bash-autocomplete-script.cjs.map +0 -1
  337. package/lib/cjs/autocomplete-scripts/powershell-autocomplete-script.cjs +0 -2
  338. package/lib/cjs/autocomplete-scripts/powershell-autocomplete-script.cjs.map +0 -1
  339. package/lib/cjs/autocomplete-scripts/zsh-autocomplete-script.cjs +0 -42
  340. package/lib/cjs/autocomplete-scripts/zsh-autocomplete-script.cjs.map +0 -1
  341. package/lib/cjs/coerce/coerce-methods.cjs +0 -2
  342. package/lib/cjs/coerce/coerce-methods.cjs.map +0 -1
  343. package/lib/cjs/coerce/string-to-array.cjs +0 -2
  344. package/lib/cjs/coerce/string-to-array.cjs.map +0 -1
  345. package/lib/cjs/coerce/string-to-primitive.cjs +0 -2
  346. package/lib/cjs/coerce/string-to-primitive.cjs.map +0 -1
  347. package/lib/cjs/coerce/string-to-set.cjs +0 -2
  348. package/lib/cjs/coerce/string-to-set.cjs.map +0 -1
  349. package/lib/cjs/definitions/define-arguments.cjs +0 -2
  350. package/lib/cjs/definitions/define-arguments.cjs.map +0 -1
  351. package/lib/cjs/definitions/define-cli.cjs +0 -2
  352. package/lib/cjs/definitions/define-cli.cjs.map +0 -1
  353. package/lib/cjs/definitions/define-options.cjs +0 -2
  354. package/lib/cjs/definitions/define-options.cjs.map +0 -1
  355. package/lib/cjs/definitions/define-subcommand.cjs +0 -2
  356. package/lib/cjs/definitions/define-subcommand.cjs.map +0 -1
  357. package/lib/cjs/definitions/validate-cli-definition.cjs +0 -2
  358. package/lib/cjs/definitions/validate-cli-definition.cjs.map +0 -1
  359. package/lib/cjs/help-message/format-arguments.cjs +0 -2
  360. package/lib/cjs/help-message/format-arguments.cjs.map +0 -1
  361. package/lib/cjs/help-message/format-options.cjs +0 -2
  362. package/lib/cjs/help-message/format-options.cjs.map +0 -1
  363. package/lib/cjs/help-message/format-subcommands.cjs +0 -2
  364. package/lib/cjs/help-message/format-subcommands.cjs.map +0 -1
  365. package/lib/cjs/help-message/generate-for-cli.cjs +0 -2
  366. package/lib/cjs/help-message/generate-for-cli.cjs.map +0 -1
  367. package/lib/cjs/help-message/generate-for-subcommand.cjs +0 -2
  368. package/lib/cjs/help-message/generate-for-subcommand.cjs.map +0 -1
  369. package/lib/cjs/help-message/print-help.cjs +0 -2
  370. package/lib/cjs/help-message/print-help.cjs.map +0 -1
  371. package/lib/cjs/help-message/set-defaults.cjs +0 -2
  372. package/lib/cjs/help-message/set-defaults.cjs.map +0 -1
  373. package/lib/cjs/help-message/styles.cjs +0 -2
  374. package/lib/cjs/help-message/styles.cjs.map +0 -1
  375. package/lib/cjs/help-message/terminal-markdown.cjs +0 -2
  376. package/lib/cjs/help-message/terminal-markdown.cjs.map +0 -1
  377. package/lib/cjs/index.cjs +0 -2
  378. package/lib/cjs/index.cjs.map +0 -1
  379. package/lib/cjs/markdown/generate-markdown.cjs +0 -2
  380. package/lib/cjs/markdown/generate-markdown.cjs.map +0 -1
  381. package/lib/cjs/metadata/arguments-metadata.cjs +0 -2
  382. package/lib/cjs/metadata/arguments-metadata.cjs.map +0 -1
  383. package/lib/cjs/metadata/cli-metadata.cjs +0 -2
  384. package/lib/cjs/metadata/cli-metadata.cjs.map +0 -1
  385. package/lib/cjs/metadata/options-metadata.cjs +0 -2
  386. package/lib/cjs/metadata/options-metadata.cjs.map +0 -1
  387. package/lib/cjs/metadata/subcommands-metadata.cjs +0 -2
  388. package/lib/cjs/metadata/subcommands-metadata.cjs.map +0 -1
  389. package/lib/cjs/parse/context/cli-context-builder.cjs +0 -2
  390. package/lib/cjs/parse/context/cli-context-builder.cjs.map +0 -1
  391. package/lib/cjs/parse/context/object-context-builder.cjs +0 -2
  392. package/lib/cjs/parse/context/object-context-builder.cjs.map +0 -1
  393. package/lib/cjs/parse/parser-utilities.cjs +0 -2
  394. package/lib/cjs/parse/parser-utilities.cjs.map +0 -1
  395. package/lib/cjs/parse/safe-parse.cjs +0 -2
  396. package/lib/cjs/parse/safe-parse.cjs.map +0 -1
  397. package/lib/cjs/parse/validation/validate-context.cjs +0 -2
  398. package/lib/cjs/parse/validation/validate-context.cjs.map +0 -1
  399. package/lib/cjs/parse/validation/validators/arguments.cjs +0 -2
  400. package/lib/cjs/parse/validation/validators/arguments.cjs.map +0 -1
  401. package/lib/cjs/parse/validation/validators/conflict.cjs +0 -2
  402. package/lib/cjs/parse/validation/validators/conflict.cjs.map +0 -1
  403. package/lib/cjs/parse/validation/validators/exclusive.cjs +0 -2
  404. package/lib/cjs/parse/validation/validators/exclusive.cjs.map +0 -1
  405. package/lib/cjs/parse/validation/validators/explicitly-passed.cjs +0 -2
  406. package/lib/cjs/parse/validation/validators/explicitly-passed.cjs.map +0 -1
  407. package/lib/cjs/parse/validation/validators/options.cjs +0 -2
  408. package/lib/cjs/parse/validation/validators/options.cjs.map +0 -1
  409. package/lib/cjs/parse/validation/validators/requires.cjs +0 -2
  410. package/lib/cjs/parse/validation/validators/requires.cjs.map +0 -1
  411. package/lib/cjs/utilities.cjs +0 -2
  412. package/lib/cjs/utilities.cjs.map +0 -1
  413. package/lib/esm/utilities.js +0 -2
  414. package/lib/esm/utilities.js.map +0 -1
  415. package/lib/mjs/utilities.mjs +0 -2
  416. package/lib/mjs/utilities.mjs.map +0 -1
  417. package/lib/typescript/autocomplete-scripts/powershell-autocomplete-script.d.ts +0 -14
  418. package/lib/typescript/autocomplete-scripts/zsh-autocomplete-script.d.ts +0 -11
  419. package/lib/typescript/coerce/coerce-methods.d.ts +0 -20
  420. package/lib/typescript/coerce/coerce-methods.d.ts.map +0 -1
  421. package/lib/typescript/coerce/string-to-array.d.ts.map +0 -1
  422. package/lib/typescript/coerce/string-to-primitive.d.ts +0 -5
  423. package/lib/typescript/coerce/string-to-primitive.d.ts.map +0 -1
  424. package/lib/typescript/definitions/define-cli.d.ts.map +0 -1
  425. package/lib/typescript/definitions/define-subcommand.d.ts.map +0 -1
  426. package/lib/typescript/definitions/validate-cli-definition.d.ts.map +0 -1
  427. package/lib/typescript/parse/context/object-context-builder.d.ts.map +0 -1
  428. package/lib/typescript/types/definitions-types.d.ts.map +0 -1
  429. package/lib/typescript/types/types.d.ts +0 -61
  430. package/lib/typescript/types/types.d.ts.map +0 -1
  431. package/lib/typescript/utilities.d.ts.map +0 -1
  432. /package/lib/{typescript → types}/autocomplete-scripts/bash-autocomplete-script.d.ts +0 -0
  433. /package/lib/{typescript → types}/definitions/define-arguments.d.ts +0 -0
  434. /package/lib/{typescript → types}/definitions/define-arguments.d.ts.map +0 -0
  435. /package/lib/{typescript → types}/definitions/define-options.d.ts +0 -0
  436. /package/lib/{typescript → types}/definitions/define-options.d.ts.map +0 -0
  437. /package/lib/{typescript → types}/help-message/format-arguments.d.ts +0 -0
  438. /package/lib/{typescript → types}/help-message/format-arguments.d.ts.map +0 -0
  439. /package/lib/{typescript → types}/help-message/format-options.d.ts +0 -0
  440. /package/lib/{typescript → types}/help-message/format-options.d.ts.map +0 -0
  441. /package/lib/{typescript → types}/help-message/format-subcommands.d.ts +0 -0
  442. /package/lib/{typescript → types}/help-message/format-subcommands.d.ts.map +0 -0
  443. /package/lib/{typescript → types}/help-message/generate-for-cli.d.ts +0 -0
  444. /package/lib/{typescript → types}/help-message/generate-for-cli.d.ts.map +0 -0
  445. /package/lib/{typescript → types}/help-message/generate-for-subcommand.d.ts +0 -0
  446. /package/lib/{typescript → types}/help-message/generate-for-subcommand.d.ts.map +0 -0
  447. /package/lib/{typescript → types}/help-message/print-help.d.ts +0 -0
  448. /package/lib/{typescript → types}/help-message/print-help.d.ts.map +0 -0
  449. /package/lib/{typescript → types}/help-message/set-defaults.d.ts +0 -0
  450. /package/lib/{typescript → types}/help-message/set-defaults.d.ts.map +0 -0
  451. /package/lib/{typescript → types}/help-message/styles.d.ts +0 -0
  452. /package/lib/{typescript → types}/help-message/styles.d.ts.map +0 -0
  453. /package/lib/{typescript → types}/help-message/terminal-markdown.d.ts +0 -0
  454. /package/lib/{typescript → types}/markdown/generate-markdown.d.ts +0 -0
  455. /package/lib/{typescript → types}/markdown/generate-markdown.d.ts.map +0 -0
  456. /package/lib/{typescript → types}/metadata/arguments-metadata.d.ts +0 -0
  457. /package/lib/{typescript → types}/metadata/cli-metadata.d.ts +0 -0
  458. /package/lib/{typescript → types}/metadata/cli-metadata.d.ts.map +0 -0
  459. /package/lib/{typescript → types}/metadata/options-metadata.d.ts +0 -0
  460. /package/lib/{typescript → types}/metadata/subcommands-metadata.d.ts +0 -0
  461. /package/lib/{typescript → types}/metadata/subcommands-metadata.d.ts.map +0 -0
  462. /package/lib/{typescript → types}/parse/safe-parse.d.ts +0 -0
  463. /package/lib/{typescript → types}/parse/validation/validators/explicitly-passed.d.ts +0 -0
  464. /package/lib/{typescript → types}/parse/validation/validators/explicitly-passed.d.ts.map +0 -0
  465. /package/lib/{typescript → types}/types/context-types.d.ts +0 -0
  466. /package/lib/{typescript → types}/types/context-types.d.ts.map +0 -0
  467. /package/lib/{typescript → types}/types/help-message-types.d.ts +0 -0
  468. /package/lib/{typescript → types}/types/help-message-types.d.ts.map +0 -0
  469. /package/lib/{typescript → types}/types/io-types.d.ts +0 -0
  470. /package/lib/{typescript → types}/types/io-types.d.ts.map +0 -0
  471. /package/lib/{typescript → types}/types/metadata-types.d.ts +0 -0
  472. /package/lib/{typescript → types}/types/metadata-types.d.ts.map +0 -0
  473. /package/lib/{typescript → types}/types/schema-types.d.ts +0 -0
  474. /package/lib/{typescript → types}/types/schema-types.d.ts.map +0 -0
@@ -1,12 +1,19 @@
1
+ import { CliError } from "../cli-error/cli-error.ts";
2
+ import { ErrorCause } from "../cli-error/error-cause.ts";
3
+ import { DefinitionErrorCode } from "../cli-error/error-code/definition-error-code.ts";
4
+ import { InternalErrorCode } from "../cli-error/error-code/internal-error-code.ts";
1
5
  import { transformOptionToArgument } from "../parse/parser-utilities.ts";
2
- import { findDuplicateStrings } from "../utilities.ts";
3
6
 
4
7
  import type { Cli, Subcommand } from "../types/definitions-types.ts";
5
8
 
6
- /** @throws {Error} If validation fails. */
9
+ /** @throws {CliError} If validation fails. */
7
10
  export function validateCliDefinition(cliDefinition: Cli) {
8
11
  if (!cliDefinition.cliName) {
9
- throw new Error(`invalid cli definition: "cliName" property is required.`);
12
+ throw new CliError({
13
+ cause: ErrorCause.Definition,
14
+ code: DefinitionErrorCode.MissingDefinitionName,
15
+ context: { commandKind: "command" },
16
+ });
10
17
  }
11
18
 
12
19
  // validate cli options
@@ -20,52 +27,86 @@ export function validateCliDefinition(cliDefinition: Cli) {
20
27
 
21
28
  // no empty subcommands array
22
29
  if (subcommands.length === 0) {
23
- throw new Error(
24
- `invalid cli definition "${cliDefinition.cliName}": "subcommands" property is optional but cannot be empty.`,
25
- );
30
+ throw new CliError({
31
+ cause: ErrorCause.Definition,
32
+ code: DefinitionErrorCode.EmptyDefinitionGroup,
33
+ context: { commandKind: "command", commandName: cliDefinition.cliName, kind: "subcommands" },
34
+ });
26
35
  }
27
36
 
28
- const commandsNames = subcommands.map(c => c.name);
37
+ const commandsNames = new Set(subcommands.map(c => c.name));
29
38
 
30
- // required subcommand name
31
- if (commandsNames.some(c => !c)) {
32
- throw new Error(`invalid subcommand definition: subcommand's "name" property is required.`);
33
- }
34
-
35
- // no duplicate subcommand names
36
- const commandsNamesDuplicates = findDuplicateStrings(commandsNames).map(c => `"${c}"`);
37
- if (commandsNamesDuplicates.length > 0) {
38
- throw new Error(
39
- `invalid cli definition "${cliDefinition.cliName}" has duplicated subcommands: ${commandsNamesDuplicates.join(", ")}.`,
40
- );
41
- }
39
+ const visitedSubcommandNames = new Set<string>();
42
40
 
43
41
  for (const subcommand of subcommands) {
42
+ if (!subcommand.name) {
43
+ throw new CliError({
44
+ cause: ErrorCause.Definition,
45
+ code: DefinitionErrorCode.MissingDefinitionName,
46
+ context: { commandKind: "subcommand" },
47
+ });
48
+ }
49
+
50
+ // no duplicate subcommand names
51
+ if (visitedSubcommandNames.has(subcommand.name)) {
52
+ throw new CliError({
53
+ cause: ErrorCause.Definition,
54
+ code: DefinitionErrorCode.DuplicateDefinitionName,
55
+ context: {
56
+ commandKind: "command",
57
+ commandName: cliDefinition.cliName,
58
+ kind: "subcommand",
59
+ name: subcommand.name,
60
+ foundInKind: "subcommand",
61
+ },
62
+ });
63
+ }
64
+ visitedSubcommandNames.add(subcommand.name);
65
+
44
66
  // command aliases check
45
67
  if (subcommand.aliases) {
46
- // no duplicated aliases
47
- const aliasesDuplicates = findDuplicateStrings(subcommand.aliases).map(c => `"${c}"`);
48
- if (aliasesDuplicates.length > 0) {
49
- throw new Error(`subcommand "${subcommand.name}" has duplicated aliases: ${aliasesDuplicates.join(", ")}.`);
50
- }
51
-
52
68
  for (const alias of subcommand.aliases) {
53
69
  // no empty alias
54
70
  if (alias === "") {
55
- throw new Error(`subcommand "${subcommand.name}" has an empty string alias.`);
71
+ throw new CliError({
72
+ cause: ErrorCause.Definition,
73
+ code: DefinitionErrorCode.EmptyStringAliasName,
74
+ context: { commandKind: "subcommand", commandName: subcommand.name },
75
+ });
56
76
  }
57
77
 
58
78
  // no conflict with subcommand name
59
- if (commandsNames.includes(alias)) {
60
- throw new Error(`subcommand "${subcommand.name}" alias "${alias}" conflicts with another subcommand name.`);
79
+ if (commandsNames.has(alias)) {
80
+ throw new CliError({
81
+ cause: ErrorCause.Definition,
82
+ code: DefinitionErrorCode.DuplicateDefinitionName,
83
+ context: {
84
+ commandKind: "command",
85
+ commandName: cliDefinition.cliName,
86
+ kind: "subcommand",
87
+ name: subcommand.name,
88
+ foundInKind: "subcommand",
89
+ duplicatedAlias: alias,
90
+ },
91
+ });
61
92
  }
62
93
 
63
94
  // no conflict with another alias
64
95
  const aliasConflicts = subcommands.filter(c => c.name !== subcommand.name && c.aliases?.includes(alias));
65
96
  if (aliasConflicts.length > 0) {
66
- throw new Error(
67
- `subcommand "${subcommand.name}" alias "${alias}" conflicts with another subcommand alias: "${aliasConflicts[0].name}".`,
68
- );
97
+ throw new CliError({
98
+ cause: ErrorCause.Definition,
99
+ code: DefinitionErrorCode.DuplicateDefinitionName,
100
+ context: {
101
+ commandKind: "command",
102
+ commandName: cliDefinition.cliName,
103
+ kind: "subcommand",
104
+ name: subcommand.name,
105
+ foundInKind: "subcommand",
106
+ duplicatedAlias: alias,
107
+ foundInName: aliasConflicts[0].name,
108
+ },
109
+ });
69
110
  }
70
111
  }
71
112
  }
@@ -82,74 +123,124 @@ function validateOptions(commandDefinition: Cli | Subcommand) {
82
123
  if (!commandDefinition.options) return; // ok
83
124
 
84
125
  const isCli = "cliName" in commandDefinition;
85
- const name = isCli ? commandDefinition.cliName : commandDefinition.name;
86
-
87
- const createError = (message: string) => {
88
- return new Error(`invalid ${isCli ? "cli" : "subcommand"} definition "${name}": ${message}`);
89
- };
126
+ const commandName = isCli ? commandDefinition.cliName : commandDefinition.name;
127
+ const commandKind = isCli ? "command" : "subcommand";
90
128
 
91
129
  const optionsDefinitionEntries = Object.entries(commandDefinition.options);
92
130
 
93
131
  // no empty options
94
132
  if (optionsDefinitionEntries.length === 0) {
95
- throw createError(`"options" property is optional but cannot be empty.`);
133
+ throw new CliError({
134
+ cause: ErrorCause.Definition,
135
+ code: DefinitionErrorCode.EmptyDefinitionGroup,
136
+ context: { commandKind, commandName, kind: "option" },
137
+ });
96
138
  }
97
139
 
98
140
  for (const [name, option] of optionsDefinitionEntries) {
99
141
  // required type
100
142
  if (!option.schema) {
101
- throw createError(`the option "${name}" missing a required property: "schema".`);
143
+ throw new CliError({
144
+ cause: ErrorCause.Definition,
145
+ code: DefinitionErrorCode.MissingSchema,
146
+ context: { commandKind, commandName, kind: "option", name },
147
+ });
102
148
  }
103
149
 
104
150
  // should not happen
105
151
  if (!option._preparedType) {
106
- throw createError(`internal error: missing prepared type for option "${name}".`);
152
+ throw new CliError({
153
+ cause: ErrorCause.Internal,
154
+ code: InternalErrorCode.MissingPreparedTypes,
155
+ context: { commandKind, commandName, kind: "option", name },
156
+ });
107
157
  }
108
158
 
109
159
  // no negated option name for boolean options
110
160
  if (isNegatedOptionName(name)) {
111
- throw createError(`the option "${name}" is a negated option name.`);
161
+ throw new CliError({
162
+ cause: ErrorCause.Definition,
163
+ code: DefinitionErrorCode.InvalidDefinitionOptionName,
164
+ context: { commandKind, commandName, optionName: name },
165
+ });
112
166
  }
113
167
 
114
168
  // no conflict with argument name
115
169
  if (commandDefinition.arguments && name in commandDefinition.arguments) {
116
- throw createError(`the option "${name}" name conflicts with an argument name.`);
170
+ throw new CliError({
171
+ cause: ErrorCause.Definition,
172
+ code: DefinitionErrorCode.DuplicateDefinitionName,
173
+ context: { commandKind, commandName, kind: "option", name, foundInKind: "argument" },
174
+ });
117
175
  }
118
176
 
119
177
  if (option.aliases) {
120
- // no duplicate aliases
121
- const aliasesDuplicates = findDuplicateStrings(option.aliases);
122
- if (aliasesDuplicates.length > 0) {
123
- throw createError(`the option "${name}" has duplicated aliases: ${aliasesDuplicates.join(", ")}.`);
124
- }
125
-
126
- for (const alias of option.aliases) {
178
+ for (const aliasName of option.aliases) {
127
179
  // no empty string aliases
128
- if (alias === "") {
129
- throw createError(`the option "${name}" has an empty string alias.`);
180
+ if (aliasName === "") {
181
+ throw new CliError({
182
+ cause: ErrorCause.Definition,
183
+ code: DefinitionErrorCode.EmptyStringAliasName,
184
+ context: { commandKind, commandName, optionName: name },
185
+ });
130
186
  }
131
187
 
132
188
  // no negated alias name for boolean options
133
- if (isNegatedOptionName(alias)) {
134
- throw createError(`the alias "${alias}" of the option "${name}" is a negated option name.`);
189
+ if (isNegatedOptionName(aliasName)) {
190
+ throw new CliError({
191
+ cause: ErrorCause.Definition,
192
+ code: DefinitionErrorCode.InvalidDefinitionOptionName,
193
+ context: { commandKind, commandName, optionName: name, negatedAliasName: aliasName },
194
+ });
135
195
  }
136
196
 
137
197
  // no alias name should conflict with any option name
138
- if (commandDefinition.options[alias]) {
139
- throw createError(`the alias "${alias}" of the option "${name}" conflicts with another option name.`);
198
+ if (commandDefinition.options[aliasName]) {
199
+ throw new CliError({
200
+ cause: ErrorCause.Definition,
201
+ code: DefinitionErrorCode.DuplicateDefinitionName,
202
+ context: {
203
+ commandKind,
204
+ commandName,
205
+ kind: "option",
206
+ name,
207
+ duplicatedAlias: aliasName,
208
+ foundInKind: "option",
209
+ },
210
+ });
140
211
  }
141
212
 
142
213
  // no alias name should conflict with any argument name
143
- if (commandDefinition.arguments && alias in commandDefinition.arguments) {
144
- throw createError(`the alias "${alias}" of the option "${name}" conflicts with an argument name.`);
214
+ if (commandDefinition.arguments && aliasName in commandDefinition.arguments) {
215
+ throw new CliError({
216
+ cause: ErrorCause.Definition,
217
+ code: DefinitionErrorCode.DuplicateDefinitionName,
218
+ context: {
219
+ commandKind,
220
+ commandName,
221
+ kind: "option",
222
+ name,
223
+ duplicatedAlias: aliasName,
224
+ foundInKind: "argument",
225
+ },
226
+ });
145
227
  }
146
228
 
147
229
  // no alias name should conflict with any other alias name
148
- const findConflict = optionsDefinitionEntries.find(([n, d]) => n !== name && d.aliases?.includes(alias));
230
+ const findConflict = optionsDefinitionEntries.find(([n, d]) => n !== name && d.aliases?.includes(aliasName));
149
231
  if (findConflict) {
150
- throw createError(
151
- `the alias "${alias}" of the option "${name}" conflicts with another alias name of the option "${findConflict[0]}".`,
152
- );
232
+ throw new CliError({
233
+ cause: ErrorCause.Definition,
234
+ code: DefinitionErrorCode.DuplicateDefinitionName,
235
+ context: {
236
+ commandKind,
237
+ commandName,
238
+ kind: "option",
239
+ name: aliasName,
240
+ foundInKind: "option",
241
+ foundInName: findConflict[0],
242
+ },
243
+ });
153
244
  }
154
245
  }
155
246
  }
@@ -157,20 +248,22 @@ function validateOptions(commandDefinition: Cli | Subcommand) {
157
248
  if (option.requires) {
158
249
  // no self require
159
250
  if (option.requires.includes(name)) {
160
- throw createError(`the option "${name}" cannot require itself.`);
161
- }
162
-
163
- // no duplicate requires
164
- const duplicateRequires = findDuplicateStrings(option.requires).map(required => `"${required}"`);
165
- if (duplicateRequires.length > 0) {
166
- throw createError(`the option "${name}" has duplicate requires: ${duplicateRequires.join(", ")}.`);
251
+ throw new CliError({
252
+ cause: ErrorCause.Definition,
253
+ code: DefinitionErrorCode.SelfRequire,
254
+ context: { commandKind, commandName, kind: "option", name: name },
255
+ });
167
256
  }
168
257
 
169
258
  // no unknown required name
170
- for (const required of option.requires) {
171
- const exits = required in commandDefinition.options || required in (commandDefinition.arguments ?? []);
259
+ for (const requiredName of option.requires) {
260
+ const exits = requiredName in commandDefinition.options || requiredName in (commandDefinition.arguments ?? []);
172
261
  if (!exits) {
173
- throw createError(`the option "${name}" requires "${required}", but it does not exist.`);
262
+ throw new CliError({
263
+ cause: ErrorCause.Definition,
264
+ code: DefinitionErrorCode.UnknownRequireName,
265
+ context: { commandKind, commandName, kind: "option", name: name, requiredName },
266
+ });
174
267
  }
175
268
  }
176
269
  }
@@ -178,20 +271,22 @@ function validateOptions(commandDefinition: Cli | Subcommand) {
178
271
  if (option.conflictWith) {
179
272
  // no self conflict
180
273
  if (option.conflictWith.includes(name)) {
181
- throw createError(`the option "${name}" cannot conflict itself.`);
182
- }
183
-
184
- // no duplicate conflicts
185
- const duplicateRequires = findDuplicateStrings(option.conflictWith).map(conflict => `"${conflict}"`);
186
- if (duplicateRequires.length > 0) {
187
- throw createError(`the option "${name}" has duplicate conflicts: ${duplicateRequires.join(", ")}.`);
274
+ throw new CliError({
275
+ cause: ErrorCause.Definition,
276
+ code: DefinitionErrorCode.SelfConflict,
277
+ context: { commandKind, commandName, kind: "option", name: name },
278
+ });
188
279
  }
189
280
 
190
281
  // no unknown conflict name
191
- for (const required of option.conflictWith) {
192
- const exits = required in commandDefinition.options || required in (commandDefinition.arguments ?? []);
282
+ for (const requiredName of option.conflictWith) {
283
+ const exits = requiredName in commandDefinition.options || requiredName in (commandDefinition.arguments ?? []);
193
284
  if (!exits) {
194
- throw createError(`the option "${name}" conflict with "${required}", but it does not exist.`);
285
+ throw new CliError({
286
+ cause: ErrorCause.Definition,
287
+ code: DefinitionErrorCode.UnknownConflictName,
288
+ context: { commandKind, commandName, kind: "option", name: name, requiredName },
289
+ });
195
290
  }
196
291
  }
197
292
  }
@@ -202,13 +297,14 @@ function validateOptions(commandDefinition: Cli | Subcommand) {
202
297
  const conflictsSet = new Set(option.conflictWith);
203
298
 
204
299
  const intersection = requiresSet.intersection(conflictsSet);
205
- const intersectionArray = Array.from(intersection).map(name => `"${name}"`);
206
-
207
- if (intersectionArray.length > 0) {
208
- const s = intersectionArray.length > 1 ? "s" : "";
209
- throw createError(
210
- `the option "${name}" cannot require and conflict with the same name${s}: ${intersectionArray.join(", ")}.`,
211
- );
300
+ const intersectedNames = Array.from(intersection).map(name => `"${name}"`);
301
+
302
+ if (intersectedNames.length > 0) {
303
+ throw new CliError({
304
+ cause: ErrorCause.Definition,
305
+ code: DefinitionErrorCode.DefinitionRequiresConflictOverlap,
306
+ context: { commandKind, commandName, kind: "option", name: name, intersectedNames },
307
+ });
212
308
  }
213
309
  }
214
310
  }
@@ -218,109 +314,128 @@ function validateArguments(commandDefinition: Cli | Subcommand) {
218
314
  if (!commandDefinition.arguments) return; // ok
219
315
 
220
316
  const isCli = "cliName" in commandDefinition;
221
- const name = isCli ? commandDefinition.cliName : commandDefinition.name;
222
-
223
- const createError = (message: string) => {
224
- return new Error(`invalid ${isCli ? "cli" : "subcommand"} definition "${name}": ${message}`);
225
- };
226
-
227
- if (commandDefinition.arguments) {
228
- const argumentsDefinitionEntries = Object.entries(commandDefinition.arguments);
317
+ const commandName = isCli ? commandDefinition.cliName : commandDefinition.name;
318
+ const commandKind = isCli ? "command" : "subcommand";
319
+
320
+ const argumentsDefinitionEntries = Object.entries(commandDefinition.arguments);
321
+
322
+ // no empty arguments record
323
+ if (argumentsDefinitionEntries.length === 0) {
324
+ throw new CliError({
325
+ cause: ErrorCause.Definition,
326
+ code: DefinitionErrorCode.EmptyDefinitionGroup,
327
+ context: { commandKind, commandName, kind: "argument" },
328
+ });
329
+ }
229
330
 
230
- // no empty arguments record
231
- if (argumentsDefinitionEntries.length === 0) {
232
- throw createError(`"arguments" property is optional but cannot be empty.`);
331
+ for (const [index, [name, argument]] of argumentsDefinitionEntries.entries()) {
332
+ // no number key name
333
+ if (/^\d+$/.test(name)) {
334
+ throw new CliError({
335
+ cause: ErrorCause.Definition,
336
+ code: DefinitionErrorCode.InvalidDefinitionArgumentName,
337
+ context: { commandKind, commandName, name },
338
+ });
233
339
  }
234
340
 
235
- for (const [index, [name, argument]] of argumentsDefinitionEntries.entries()) {
236
- // no number key name
237
- if (/^\d+$/.test(name)) {
238
- throw createError(`the argument "${name}" name cannot be a number.`);
239
- }
240
-
241
- // should not happen
242
- if (!argument._preparedType) {
243
- throw createError(`internal error: missing prepared type for argument "${name}".`);
244
- }
341
+ // should not happen
342
+ if (!argument._preparedType) {
343
+ throw new CliError({
344
+ cause: ErrorCause.Internal,
345
+ code: InternalErrorCode.MissingPreparedTypes,
346
+ context: { commandKind, commandName, kind: "argument", name },
347
+ });
348
+ }
245
349
 
246
- // no missing type
247
- if (!argument.schema) {
248
- throw createError(`the argument "${name}" missing a required property: "schema".`);
249
- }
350
+ // no missing schema
351
+ if (!argument.schema) {
352
+ throw new CliError({
353
+ cause: ErrorCause.Definition,
354
+ code: DefinitionErrorCode.MissingSchema,
355
+ context: { commandKind, commandName, kind: "argument", name },
356
+ });
357
+ }
250
358
 
251
- // no conflicting option
252
- if (commandDefinition.options && name in commandDefinition.options) {
253
- throw createError(`the argument "${name}" name conflicts with an option name.`);
254
- }
359
+ if (!argument._preparedType.optional) continue; // ok
255
360
 
256
- if (!argument._preparedType.optional) continue; // ok
361
+ // no optional argument when "allowPositionals" is enabled
362
+ if (commandDefinition.allowPositionals) {
363
+ throw new CliError({
364
+ cause: ErrorCause.Definition,
365
+ code: DefinitionErrorCode.InvalidOptionalArgumentDefinition,
366
+ context: { commandKind, commandName, name, allowPositionals: true },
367
+ });
368
+ }
257
369
 
258
- // no optional argument when "allowPositionals" is enabled
259
- if (commandDefinition.allowPositionals) {
260
- throw createError(`the argument "${name}" cannot be optional when "allowPositionals" is enabled.`);
261
- }
370
+ // only last argument can be optional
371
+ if (index !== argumentsDefinitionEntries.length - 1) {
372
+ throw new CliError({
373
+ cause: ErrorCause.Definition,
374
+ code: DefinitionErrorCode.InvalidOptionalArgumentDefinition,
375
+ context: { commandKind, commandName, name, allowPositionals: false },
376
+ });
377
+ }
262
378
 
263
- // only last argument can be optional
264
- if (index !== argumentsDefinitionEntries.length - 1) {
265
- throw createError(`the argument "${name}" cannot be optional unless it is the last argument.`);
379
+ if (argument.requires) {
380
+ // no self require
381
+ if (argument.requires.includes(name)) {
382
+ throw new CliError({
383
+ cause: ErrorCause.Definition,
384
+ code: DefinitionErrorCode.SelfRequire,
385
+ context: { commandKind, commandName, kind: "argument", name },
386
+ });
266
387
  }
267
388
 
268
- if (argument.requires) {
269
- // no self require
270
- if (argument.requires.includes(name)) {
271
- throw createError(`the argument "${name}" cannot require itself.`);
272
- }
273
-
274
- // no duplicate requires
275
- const duplicateRequires = findDuplicateStrings(argument.requires).map(required => `"${required}"`);
276
- if (duplicateRequires.length > 0) {
277
- throw createError(`the argument "${name}" has duplicate requires: ${duplicateRequires.join(", ")}.`);
278
- }
279
-
280
- // no unknown require
281
- for (const required of argument.requires) {
282
- const exits = required in (commandDefinition.options ?? {}) || required in commandDefinition.arguments;
283
- if (!exits) {
284
- throw createError(`the argument "${name}" requires "${required}", but it does not exist.`);
285
- }
389
+ // no unknown require
390
+ for (const requiredName of argument.requires) {
391
+ const exits = requiredName in (commandDefinition.options ?? {}) || requiredName in commandDefinition.arguments;
392
+ if (!exits) {
393
+ throw new CliError({
394
+ cause: ErrorCause.Definition,
395
+ code: DefinitionErrorCode.UnknownRequireName,
396
+ context: { commandKind, commandName, kind: "argument", name, requiredName },
397
+ });
286
398
  }
287
399
  }
400
+ }
288
401
 
289
- if (argument.conflictWith) {
290
- // no self conflict
291
- if (argument.conflictWith.includes(name)) {
292
- throw createError(`the argument "${name}" cannot conflict itself.`);
293
- }
294
-
295
- // no duplicate conflicts
296
- const duplicateRequires = findDuplicateStrings(argument.conflictWith).map(conflict => `"${conflict}"`);
297
- if (duplicateRequires.length > 0) {
298
- throw createError(`the argument "${name}" has duplicate conflicts: ${duplicateRequires.join(", ")}.`);
299
- }
402
+ if (argument.conflictWith) {
403
+ // no self conflict
404
+ if (argument.conflictWith.includes(name)) {
405
+ throw new CliError({
406
+ cause: ErrorCause.Definition,
407
+ code: DefinitionErrorCode.SelfConflict,
408
+ context: { commandKind, commandName, kind: "argument", name },
409
+ });
410
+ }
300
411
 
301
- // no unknown conflict
302
- for (const required of argument.conflictWith) {
303
- const exits = required in (commandDefinition.options ?? {}) || required in commandDefinition.arguments;
304
- if (!exits) {
305
- throw createError(`the argument "${name}" conflict with "${required}", but it does not exist.`);
306
- }
412
+ // no unknown conflict
413
+ for (const requiredName of argument.conflictWith) {
414
+ const exits = requiredName in (commandDefinition.options ?? {}) || requiredName in commandDefinition.arguments;
415
+ if (!exits) {
416
+ throw new CliError({
417
+ cause: ErrorCause.Definition,
418
+ code: DefinitionErrorCode.UnknownConflictName,
419
+ context: { commandKind, commandName, kind: "argument", name, requiredName },
420
+ });
307
421
  }
308
422
  }
423
+ }
309
424
 
310
- // no intersection between requires and conflicts
311
- if (argument.requires && argument.conflictWith) {
312
- const requiresSet = new Set(argument.requires);
313
- const conflictsSet = new Set(argument.conflictWith);
314
-
315
- const intersection = requiresSet.intersection(conflictsSet);
316
- const intersectionArray = Array.from(intersection).map(name => `"${name}"`);
425
+ // no intersection between requires and conflicts
426
+ if (argument.requires && argument.conflictWith) {
427
+ const requiresSet = new Set(argument.requires);
428
+ const conflictsSet = new Set(argument.conflictWith);
317
429
 
318
- if (intersectionArray.length > 0) {
319
- const s = intersectionArray.length > 1 ? "s" : "";
320
- throw createError(
321
- `the argument "${name}" cannot require and conflict with the same name${s}: ${intersectionArray.join(", ")}.`,
322
- );
323
- }
430
+ const intersection = requiresSet.intersection(conflictsSet);
431
+ const intersectedNames = Array.from(intersection).map(name => `"${name}"`);
432
+
433
+ if (intersectedNames.length > 0) {
434
+ throw new CliError({
435
+ cause: ErrorCause.Definition,
436
+ code: DefinitionErrorCode.DefinitionRequiresConflictOverlap,
437
+ context: { commandKind, commandName, kind: "argument", name, intersectedNames },
438
+ });
324
439
  }
325
440
  }
326
441
  }
@@ -1,4 +1,4 @@
1
- import { indent, indentLines, insertAtEndOfFirstLine, ln, toKebabCase } from "../utilities.ts";
1
+ import { indent, indentLines, insertAtEndOfFirstLine, ln, toKebabCase } from "../utilities/utilities.ts";
2
2
  import { terminalMarkdown } from "./terminal-markdown.ts";
3
3
 
4
4
  import type { ArgumentMetadata } from "../types/metadata-types.ts";
@@ -1,4 +1,4 @@
1
- import { indent, indentLines, insertAtEndOfFirstLine, ln } from "../utilities.ts";
1
+ import { indent, indentLines, insertAtEndOfFirstLine, ln } from "../utilities/utilities.ts";
2
2
  import { terminalMarkdown } from "./terminal-markdown.ts";
3
3
 
4
4
  import type { OptionMetadata } from "../types/metadata-types.ts";
@@ -1,4 +1,4 @@
1
- import { indent, indentLines, ln, subcommandPlaceholder } from "../utilities.ts";
1
+ import { indent, indentLines, ln, subcommandPlaceholder } from "../utilities/utilities.ts";
2
2
  import { terminalMarkdown } from "./terminal-markdown.ts";
3
3
 
4
4
  import type { SubcommandMetadata } from "../types/metadata-types.ts";
@@ -1,5 +1,5 @@
1
1
  import { getCliMetadata } from "../metadata/cli-metadata.ts";
2
- import { indent, indentLines, ln, subcommandPlaceholder } from "../utilities.ts";
2
+ import { indent, indentLines, ln, subcommandPlaceholder } from "../utilities/utilities.ts";
3
3
  import { formatHelpMessageArguments } from "./format-arguments.ts";
4
4
  import { formatHelpMessageOptions } from "./format-options.ts";
5
5
  import { formatHelpMessageCommands } from "./format-subcommands.ts";
@@ -7,7 +7,7 @@ const markdownStyle: Record<string, ColorFunctionType> = {
7
7
  bold: c.bold,
8
8
  italic: c.italic,
9
9
  boldItalic: c.bold.italic,
10
- code: (...string) => c.bgHex("#333333").whiteBright(` ${string.join(" ")} `),
10
+ code: (...string) => c.bgHex("#282828").whiteBright(` ${string.join(" ")} `),
11
11
  strikethrough: c.strikethrough,
12
12
  link: c.underline,
13
13
  listBullet: c.whiteBright,
@@ -125,9 +125,6 @@ const terminalRenderer: RendererObject<string, string> = {
125
125
  },
126
126
  };
127
127
 
128
- const terminalMarked = new Marked();
129
- terminalMarked.use({ renderer: terminalRenderer });
130
-
131
128
  export function terminalMarkdown(
132
129
  text: string,
133
130
  renderer: "terminal" | "html" = "terminal",
@@ -138,6 +135,8 @@ export function terminalMarkdown(
138
135
  }
139
136
 
140
137
  if (renderer === "terminal") {
138
+ const terminalMarked = new Marked();
139
+ terminalMarked.use({ renderer: terminalRenderer });
141
140
  return ansiTextColor(terminalMarked.parse(text) as string);
142
141
  }
143
142