@jhlagado/azm 0.2.7 → 0.2.9

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 (253) hide show
  1. package/README.md +239 -76
  2. package/dist/src/api-artifacts.d.ts +20 -0
  3. package/dist/src/api-artifacts.js +165 -0
  4. package/dist/src/api-compile.d.ts +8 -2
  5. package/dist/src/api-compile.js +55 -227
  6. package/dist/src/api-register-contracts.d.ts +9 -0
  7. package/dist/src/api-register-contracts.js +77 -0
  8. package/dist/src/api-tooling.d.ts +2 -2
  9. package/dist/src/api-tooling.js +1 -1
  10. package/dist/src/assembly/address-planning.d.ts +1 -2
  11. package/dist/src/assembly/address-planning.js +119 -218
  12. package/dist/src/assembly/address-symbols.d.ts +12 -0
  13. package/dist/src/assembly/address-symbols.js +118 -0
  14. package/dist/src/assembly/assemble-program.js +5 -0
  15. package/dist/src/assembly/fixup-emission.js +30 -48
  16. package/dist/src/assembly/import-visibility.d.ts +3 -0
  17. package/dist/src/assembly/import-visibility.js +204 -0
  18. package/dist/src/assembly/program-emission.js +163 -164
  19. package/dist/src/cli/artifact-files.d.ts +15 -0
  20. package/dist/src/cli/artifact-files.js +86 -0
  21. package/dist/src/cli/parse-args.d.ts +6 -5
  22. package/dist/src/cli/parse-args.js +162 -136
  23. package/dist/src/cli/run.js +4 -1
  24. package/dist/src/cli/usage.d.ts +1 -0
  25. package/dist/src/cli/usage.js +33 -0
  26. package/dist/src/cli/write-artifacts.js +18 -91
  27. package/dist/src/core/compile.js +51 -274
  28. package/dist/src/core/conditional-assembly.d.ts +6 -0
  29. package/dist/src/core/conditional-assembly.js +181 -0
  30. package/dist/src/expansion/op-constant-expression.d.ts +3 -0
  31. package/dist/src/expansion/op-constant-expression.js +52 -0
  32. package/dist/src/expansion/op-expand-selected.d.ts +5 -0
  33. package/dist/src/expansion/op-expand-selected.js +143 -0
  34. package/dist/src/expansion/op-expansion.d.ts +5 -53
  35. package/dist/src/expansion/op-expansion.js +85 -815
  36. package/dist/src/expansion/op-instruction-instantiation.d.ts +3 -0
  37. package/dist/src/expansion/op-instruction-instantiation.js +194 -0
  38. package/dist/src/expansion/op-local-labels.d.ts +8 -0
  39. package/dist/src/expansion/op-local-labels.js +166 -0
  40. package/dist/src/expansion/op-operand-splitting.d.ts +1 -0
  41. package/dist/src/expansion/op-operand-splitting.js +44 -0
  42. package/dist/src/expansion/op-operands.d.ts +53 -0
  43. package/dist/src/expansion/op-operands.js +66 -0
  44. package/dist/src/expansion/op-selection.d.ts +18 -0
  45. package/dist/src/expansion/op-selection.js +172 -0
  46. package/dist/src/index.d.ts +2 -1
  47. package/dist/src/index.js +1 -1
  48. package/dist/src/model/diagnostic.d.ts +4 -0
  49. package/dist/src/model/diagnostic.js +4 -0
  50. package/dist/src/node/source-host.js +40 -13
  51. package/dist/src/outputs/asm80-expression-evaluation.d.ts +10 -0
  52. package/dist/src/outputs/asm80-expression-evaluation.js +75 -0
  53. package/dist/src/outputs/asm80-expressions.d.ts +5 -0
  54. package/dist/src/outputs/asm80-expressions.js +47 -0
  55. package/dist/src/outputs/asm80-instruction-operands.d.ts +16 -0
  56. package/dist/src/outputs/asm80-instruction-operands.js +38 -0
  57. package/dist/src/outputs/asm80-instructions.d.ts +5 -0
  58. package/dist/src/outputs/asm80-instructions.js +272 -0
  59. package/dist/src/outputs/asm80-ld-operands.d.ts +10 -0
  60. package/dist/src/outputs/asm80-ld-operands.js +157 -0
  61. package/dist/src/outputs/asm80-strings.d.ts +4 -0
  62. package/dist/src/outputs/asm80-strings.js +14 -0
  63. package/dist/src/outputs/d8-files.d.ts +10 -0
  64. package/dist/src/outputs/d8-files.js +103 -0
  65. package/dist/src/outputs/d8-helpers.d.ts +21 -0
  66. package/dist/src/outputs/d8-helpers.js +136 -0
  67. package/dist/src/outputs/hex.js +26 -18
  68. package/dist/src/outputs/types.d.ts +16 -10
  69. package/dist/src/outputs/write-asm80.js +72 -597
  70. package/dist/src/outputs/write-d8.js +6 -216
  71. package/dist/src/register-contracts/accept-output.d.ts +2 -0
  72. package/dist/src/register-contracts/analyze-helpers.d.ts +29 -0
  73. package/dist/src/register-contracts/analyze-helpers.js +162 -0
  74. package/dist/src/{register-care → register-contracts}/analyze.d.ts +6 -6
  75. package/dist/src/register-contracts/analyze.js +73 -0
  76. package/dist/src/register-contracts/annotate.d.ts +11 -0
  77. package/dist/src/{register-care → register-contracts}/annotate.js +3 -3
  78. package/dist/src/register-contracts/annotations.d.ts +8 -0
  79. package/dist/src/{register-care → register-contracts}/annotations.js +3 -3
  80. package/dist/src/register-contracts/boundaryHints.d.ts +3 -0
  81. package/dist/src/register-contracts/boundaryHints.js +24 -0
  82. package/dist/src/register-contracts/carriers.d.ts +2 -0
  83. package/dist/src/register-contracts/constants.d.ts +4 -0
  84. package/dist/src/register-contracts/constants.js +51 -0
  85. package/dist/src/register-contracts/controlFlow.d.ts +5 -0
  86. package/dist/src/register-contracts/controlFlow.js +55 -0
  87. package/dist/src/register-contracts/fix.d.ts +11 -0
  88. package/dist/src/{register-care → register-contracts}/fix.js +47 -30
  89. package/dist/src/register-contracts/instruction-head.d.ts +2 -0
  90. package/dist/src/register-contracts/instruction-head.js +3 -0
  91. package/dist/src/register-contracts/instruction-operands.d.ts +3 -0
  92. package/dist/src/register-contracts/instruction-operands.js +101 -0
  93. package/dist/src/register-contracts/instruction-predicates.d.ts +6 -0
  94. package/dist/src/register-contracts/instruction-predicates.js +44 -0
  95. package/dist/src/register-contracts/interfaceContracts.d.ts +2 -0
  96. package/dist/src/register-contracts/interfaceContracts.js +68 -0
  97. package/dist/src/register-contracts/liveness.d.ts +3 -0
  98. package/dist/src/{register-care → register-contracts}/liveness.js +111 -79
  99. package/dist/src/register-contracts/operand-register-name.d.ts +2 -0
  100. package/dist/src/register-contracts/operand-register-name.js +13 -0
  101. package/dist/src/{register-care → register-contracts}/profiles.d.ts +5 -5
  102. package/dist/src/{register-care → register-contracts}/profiles.js +2 -2
  103. package/dist/src/register-contracts/programModel-boundaries.d.ts +6 -0
  104. package/dist/src/register-contracts/programModel-boundaries.js +64 -0
  105. package/dist/src/register-contracts/programModel-routines.d.ts +7 -0
  106. package/dist/src/register-contracts/programModel-routines.js +144 -0
  107. package/dist/src/register-contracts/programModel.d.ts +3 -0
  108. package/dist/src/register-contracts/programModel.js +14 -0
  109. package/dist/src/register-contracts/report.d.ts +5 -0
  110. package/dist/src/{register-care → register-contracts}/report.js +34 -17
  111. package/dist/src/register-contracts/routine-summaries.d.ts +6 -0
  112. package/dist/src/{register-care → register-contracts}/routine-summaries.js +11 -1
  113. package/dist/src/register-contracts/smartCommentBlocks.d.ts +5 -0
  114. package/dist/src/register-contracts/smartCommentBlocks.js +30 -0
  115. package/dist/src/register-contracts/smartCommentParsing.d.ts +3 -0
  116. package/dist/src/register-contracts/smartCommentParsing.js +80 -0
  117. package/dist/src/register-contracts/smartComments.d.ts +5 -0
  118. package/dist/src/register-contracts/smartComments.js +92 -0
  119. package/dist/src/register-contracts/summaries.d.ts +12 -0
  120. package/dist/src/{register-care → register-contracts}/summaries.js +7 -7
  121. package/dist/src/register-contracts/summary-boundary.d.ts +2 -0
  122. package/dist/src/register-contracts/summary-boundary.js +40 -0
  123. package/dist/src/register-contracts/summary-contract.d.ts +2 -0
  124. package/dist/src/register-contracts/summary-contract.js +45 -0
  125. package/dist/src/register-contracts/summary-result.d.ts +7 -0
  126. package/dist/src/register-contracts/summary-result.js +122 -0
  127. package/dist/src/register-contracts/summary-state.d.ts +23 -0
  128. package/dist/src/register-contracts/summary-state.js +88 -0
  129. package/dist/src/register-contracts/summary-token-transfer.d.ts +3 -0
  130. package/dist/src/register-contracts/summary-token-transfer.js +67 -0
  131. package/dist/src/register-contracts/summary.d.ts +3 -0
  132. package/dist/src/register-contracts/summary.js +266 -0
  133. package/dist/src/register-contracts/tooling.d.ts +57 -0
  134. package/dist/src/{register-care → register-contracts}/tooling.js +8 -6
  135. package/dist/src/register-contracts/types.d.ts +188 -0
  136. package/dist/src/semantics/binary-operators.d.ts +2 -0
  137. package/dist/src/semantics/binary-operators.js +15 -0
  138. package/dist/src/semantics/byte-functions.d.ts +2 -0
  139. package/dist/src/semantics/byte-functions.js +7 -0
  140. package/dist/src/semantics/constant-operator-types.d.ts +10 -0
  141. package/dist/src/semantics/constant-operator-types.js +1 -0
  142. package/dist/src/semantics/constant-operators.d.ts +3 -0
  143. package/dist/src/semantics/constant-operators.js +3 -0
  144. package/dist/src/semantics/diagnostics.d.ts +3 -0
  145. package/dist/src/semantics/diagnostics.js +10 -0
  146. package/dist/src/semantics/expression-evaluation.d.ts +11 -19
  147. package/dist/src/semantics/expression-evaluation.js +22 -334
  148. package/dist/src/semantics/layout-evaluation.d.ts +23 -0
  149. package/dist/src/semantics/layout-evaluation.js +202 -0
  150. package/dist/src/semantics/layout-format.d.ts +5 -0
  151. package/dist/src/semantics/layout-format.js +31 -0
  152. package/dist/src/semantics/layout-path.d.ts +24 -0
  153. package/dist/src/semantics/layout-path.js +58 -0
  154. package/dist/src/semantics/unary-operators.d.ts +2 -0
  155. package/dist/src/semantics/unary-operators.js +8 -0
  156. package/dist/src/source/line-comment-scanner.d.ts +1 -0
  157. package/dist/src/source/line-comment-scanner.js +51 -0
  158. package/dist/src/source/logical-lines.d.ts +3 -0
  159. package/dist/src/source/source-span.d.ts +2 -0
  160. package/dist/src/source/strip-line-comment.js +8 -44
  161. package/dist/src/syntax/directive-aliases.js +36 -22
  162. package/dist/src/syntax/expression-tokenizer.d.ts +30 -0
  163. package/dist/src/syntax/expression-tokenizer.js +310 -0
  164. package/dist/src/syntax/parse-directive-statement.d.ts +9 -0
  165. package/dist/src/syntax/parse-directive-statement.js +309 -0
  166. package/dist/src/syntax/parse-expression.d.ts +2 -2
  167. package/dist/src/syntax/parse-expression.js +7 -568
  168. package/dist/src/syntax/parse-layout-declarations.d.ts +9 -0
  169. package/dist/src/syntax/parse-layout-declarations.js +189 -0
  170. package/dist/src/syntax/parse-layout-expression.d.ts +5 -0
  171. package/dist/src/syntax/parse-layout-expression.js +175 -0
  172. package/dist/src/syntax/parse-line.js +21 -273
  173. package/dist/src/syntax/parse-token-expression.d.ts +3 -0
  174. package/dist/src/syntax/parse-token-expression.js +133 -0
  175. package/dist/src/tooling/api.js +1 -1
  176. package/dist/src/tooling/case-style.js +47 -30
  177. package/dist/src/z80/effect-groups.d.ts +38 -0
  178. package/dist/src/z80/effect-groups.js +265 -0
  179. package/dist/src/z80/effect-units.d.ts +18 -0
  180. package/dist/src/z80/effect-units.js +165 -0
  181. package/dist/src/z80/effects.d.ts +1 -1
  182. package/dist/src/z80/effects.js +94 -557
  183. package/dist/src/z80/encode-core.d.ts +2 -0
  184. package/dist/src/z80/encode-core.js +42 -0
  185. package/dist/src/z80/encode-ld-helpers.d.ts +25 -0
  186. package/dist/src/z80/encode-ld-helpers.js +172 -0
  187. package/dist/src/z80/encode-ld.d.ts +2 -0
  188. package/dist/src/z80/encode-ld.js +285 -0
  189. package/dist/src/z80/encode.js +190 -542
  190. package/dist/src/z80/ld-support.d.ts +3 -0
  191. package/dist/src/z80/ld-support.js +146 -0
  192. package/dist/src/z80/operand-split-state.d.ts +8 -0
  193. package/dist/src/z80/operand-split-state.js +46 -0
  194. package/dist/src/z80/operand-split.d.ts +1 -0
  195. package/dist/src/z80/operand-split.js +13 -0
  196. package/dist/src/z80/parse-basic.d.ts +4 -0
  197. package/dist/src/z80/parse-basic.js +39 -0
  198. package/dist/src/z80/parse-branch.d.ts +4 -0
  199. package/dist/src/z80/parse-branch.js +218 -0
  200. package/dist/src/z80/parse-conditions.d.ts +6 -0
  201. package/dist/src/z80/parse-conditions.js +10 -0
  202. package/dist/src/z80/parse-exchange.d.ts +2 -0
  203. package/dist/src/z80/parse-exchange.js +30 -0
  204. package/dist/src/z80/parse-instruction.js +224 -1010
  205. package/dist/src/z80/parse-io-control.d.ts +5 -0
  206. package/dist/src/z80/parse-io-control.js +108 -0
  207. package/dist/src/z80/parse-ld.d.ts +2 -0
  208. package/dist/src/z80/parse-ld.js +83 -0
  209. package/dist/src/z80/parse-operands.d.ts +41 -0
  210. package/dist/src/z80/parse-operands.js +259 -0
  211. package/docs/codebase/01-orientation-and-repository-layout.md +192 -0
  212. package/docs/codebase/02-source-loading-and-parsing.md +263 -0
  213. package/docs/codebase/03-assembly-and-z80-emission.md +251 -0
  214. package/docs/codebase/04-ops-and-register-contracts.md +237 -0
  215. package/docs/codebase/05-interfaces-and-output-artifacts.md +253 -0
  216. package/docs/codebase/06-verification-and-maintenance.md +202 -0
  217. package/docs/codebase/appendices/a-directory-file-reference.md +253 -0
  218. package/docs/codebase/appendices/b-compile-flow-reference.md +103 -0
  219. package/docs/codebase/appendices/c-public-surface-reference.md +106 -0
  220. package/docs/codebase/appendices/index.md +16 -0
  221. package/docs/codebase/index.md +46 -0
  222. package/package.json +2 -3
  223. package/dist/src/register-care/accept-output.d.ts +0 -2
  224. package/dist/src/register-care/analyze.js +0 -166
  225. package/dist/src/register-care/annotate.d.ts +0 -11
  226. package/dist/src/register-care/annotations.d.ts +0 -8
  227. package/dist/src/register-care/boundaryHints.d.ts +0 -3
  228. package/dist/src/register-care/boundaryHints.js +0 -80
  229. package/dist/src/register-care/carriers.d.ts +0 -2
  230. package/dist/src/register-care/controlFlow.d.ts +0 -5
  231. package/dist/src/register-care/controlFlow.js +0 -38
  232. package/dist/src/register-care/fix.d.ts +0 -11
  233. package/dist/src/register-care/instruction-shape.d.ts +0 -11
  234. package/dist/src/register-care/instruction-shape.js +0 -129
  235. package/dist/src/register-care/liveness.d.ts +0 -3
  236. package/dist/src/register-care/programModel.d.ts +0 -3
  237. package/dist/src/register-care/programModel.js +0 -266
  238. package/dist/src/register-care/report.d.ts +0 -5
  239. package/dist/src/register-care/routine-summaries.d.ts +0 -6
  240. package/dist/src/register-care/smartComments.d.ts +0 -5
  241. package/dist/src/register-care/smartComments.js +0 -243
  242. package/dist/src/register-care/summaries.d.ts +0 -12
  243. package/dist/src/register-care/summary.d.ts +0 -3
  244. package/dist/src/register-care/summary.js +0 -474
  245. package/dist/src/register-care/tooling.d.ts +0 -43
  246. package/dist/src/register-care/types.d.ts +0 -172
  247. package/docs/reference/cli.md +0 -151
  248. package/docs/reference/tooling-api.md +0 -316
  249. /package/dist/src/{register-care → register-contracts}/accept-output.js +0 -0
  250. /package/dist/src/{register-care → register-contracts}/carriers.js +0 -0
  251. /package/dist/src/{register-care → register-contracts}/sourceText.d.ts +0 -0
  252. /package/dist/src/{register-care → register-contracts}/sourceText.js +0 -0
  253. /package/dist/src/{register-care → register-contracts}/types.js +0 -0
@@ -0,0 +1,253 @@
1
+ ---
2
+ layout: default
3
+ title: 'Appendix A - Directory and File Reference'
4
+ parent: 'Appendices'
5
+ grand_parent: 'AZM Engineering Manual'
6
+ nav_order: 1
7
+ ---
8
+
9
+ [<- Verification and Maintenance](../06-verification-and-maintenance.md) | [Appendix B ->](b-compile-flow-reference.md)
10
+
11
+ # Appendix A - Directory and File Reference
12
+
13
+ This appendix is the file-by-file map of the AZM implementation. Use it when
14
+ you need to find the owner of a behaviour quickly.
15
+
16
+ ## Root Source Files
17
+
18
+ | File | Role |
19
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
20
+ | `src/index.ts` | Main package export surface. Re-exports compile, tooling, diagnostics, register contract and D8 map types. |
21
+ | `src/api-compile.ts` | File-backed public compile API. Coordinates loading, analysis, register contracts, assembly and artifact writers. |
22
+ | `src/api-artifacts.ts` | Assembly artifact helper for the compile API. Builds BIN, HEX, D8 and lowered ASM80 artifacts from assembled output. |
23
+ | `src/api-register-contracts.ts` | Register contract helper for the compile API. Loads `.asmi` interfaces, runs analysis and converts results to artifacts. |
24
+ | `src/api-tooling.ts` | Public tooling API re-export layer. Keeps editor-facing imports stable. |
25
+ | `src/cli.ts` | CLI executable entry. Calls `runCli()` and sets process exit code. |
26
+
27
+ ## `src/assembly/`
28
+
29
+ | File | Role |
30
+ | --------------------- | ------------------------------------------------------------------------------------------------------------ |
31
+ | `assemble-program.ts` | Assembly coordinator. Builds address state, emits program image and returns assembled result data. |
32
+ | `address-planning.ts` | Defines labels, equates, enum members, layouts and type aliases; calculates directive and instruction sizes. |
33
+ | `address-symbols.ts` | Symbol-definition helpers for labels, equates and enums. |
34
+ | `placement.ts` | Tracks placement state plus origin and address movement for code and data. |
35
+ | `program-emission.ts` | Writes bytes into the emitted image and records source segments. |
36
+ | `fixup-emission.ts` | Resolves symbolic instruction fragments such as ABS16, IMM8 and REL8. |
37
+
38
+ ## `src/cli/`
39
+
40
+ | File | Role |
41
+ | -------------------- | ---------------------------------------------------------------------------------------- |
42
+ | `artifact-files.ts` | Writes in-memory artifacts to disk paths. |
43
+ | `parse-args.ts` | Parses CLI switches and validates command shape. |
44
+ | `run.ts` | Runs the CLI: parse args, compile, print diagnostics, write artifacts and return status. |
45
+ | `usage.ts` | CLI help text. |
46
+ | `write-artifacts.ts` | Maps parsed options to compile options and calculates output stems. |
47
+
48
+ ## `src/core/`
49
+
50
+ | File | Role |
51
+ | ------------------------- | ----------------------------------------------------------------------- |
52
+ | `compile.ts` | In-memory source-item parsing path and legacy compile helpers. |
53
+ | `compile-artifacts.ts` | Artifact-oriented compile helpers used by older or lower-level callers. |
54
+ | `conditional-assembly.ts` | `.if` / `.else` / `.endif` filtering before final source-item parsing. |
55
+
56
+ ## `src/diagnostics/`
57
+
58
+ | File | Role |
59
+ | ----------- | --------------------------------------------------- |
60
+ | `format.ts` | Formats structured diagnostics for CLI text output. |
61
+
62
+ ## `src/expansion/`
63
+
64
+ | File | Role |
65
+ | --------------------------------- | ------------------------------------------------------------ |
66
+ | `op-expansion.ts` | Coordinates op collection, invocation parsing and expansion. |
67
+ | `op-operands.ts` | Op parameter and operand model. |
68
+ | `op-operand-splitting.ts` | Splits invocation operands for overload matching. |
69
+ | `op-selection.ts` | Selects the matching op overload. |
70
+ | `op-expand-selected.ts` | Expands the selected overload. |
71
+ | `op-instruction-instantiation.ts` | Substitutes operands into op body instructions. |
72
+ | `op-local-labels.ts` | Rewrites expansion-local labels to unique generated labels. |
73
+ | `op-constant-expression.ts` | Constant-expression support for op expansion. |
74
+
75
+ ## `src/model/`
76
+
77
+ | File | Role |
78
+ | ---------------- | ------------------------------------------------------------------------------------ |
79
+ | `diagnostic.ts` | Diagnostic severity, IDs and common diagnostic shape. |
80
+ | `expression.ts` | Expression and type-expression AST types. |
81
+ | `fixup.ts` | Fixup fragment model for symbolic byte emission. |
82
+ | `source-item.ts` | Parsed source item model shared by parser, assembly, outputs and register contracts. |
83
+ | `symbol.ts` | Symbol table type. |
84
+
85
+ ## `src/node/`
86
+
87
+ | File | Role |
88
+ | ---------------- | ------------------------------------------------------------------------------------------------------------ |
89
+ | `source-host.ts` | File-backed source loading, entry extension checks, include expansion, source text capture and comment maps. |
90
+
91
+ ## `src/outputs/`
92
+
93
+ | File | Role |
94
+ | -------------------------------- | ------------------------------------------------------------ |
95
+ | `types.ts` | Artifact, byte map, source segment, symbol and D8 map types. |
96
+ | `index.ts` | Default writer set used by the compile API. |
97
+ | `range.ts` | Written-range helpers for sparse byte maps. |
98
+ | `hex.ts` | Low-level Intel HEX record writer. |
99
+ | `write-bin.ts` | Flat binary artifact writer. |
100
+ | `write-hex.ts` | HEX artifact writer around `hex.ts`. |
101
+ | `write-d8.ts` | Debug80 map writer and source segment grouping. |
102
+ | `write-asm80.ts` | Lowered ASM80-compatible source writer. |
103
+ | `d8-files.ts` | D8 source-file and path helpers. |
104
+ | `d8-helpers.ts` | D8 segment and symbol helpers. |
105
+ | `asm80-expressions.ts` | ASM80 expression lowering helpers. |
106
+ | `asm80-expression-evaluation.ts` | ASM80-side constant evaluation for lowering. |
107
+ | `asm80-instruction-operands.ts` | ASM80 instruction operand lowering helpers. |
108
+ | `asm80-instructions.ts` | ASM80 instruction lowering helpers. |
109
+ | `asm80-ld-operands.ts` | ASM80 `ld` operand lowering helpers. |
110
+ | `asm80-strings.ts` | ASM80 string rendering helpers. |
111
+
112
+ ## `src/register-contracts/`
113
+
114
+ | File | Role |
115
+ | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
116
+ | `analyze.ts` | Main register contract analysis coordinator. |
117
+ | `analyze-helpers.ts` | Shared helpers for analysis orchestration. |
118
+ | `programModel.ts` | Builds routines, labels, instructions and direct call boundaries from source items. |
119
+ | `programModel-boundaries.ts` | Routine-boundary detection helpers. |
120
+ | `programModel-routines.ts` | Routine construction helpers. |
121
+ | `smartComments.ts` | Parses AZMDoc comments and `.asmi` interface contracts. |
122
+ | `smartCommentBlocks.ts` | Groups generated and hand-written smart-comment blocks. |
123
+ | `smartCommentParsing.ts` | Parses smart-comment tokens into contract facts. |
124
+ | `interfaceContracts.ts` | Parses external `.asmi` interface contracts. |
125
+ | `summary.ts` | Infers a routine summary from instruction effects and contracts. |
126
+ | `summary-boundary.ts` | Summary behaviour at routine boundaries. |
127
+ | `summary-contract.ts` | Contract-to-summary helpers. |
128
+ | `summary-result.ts` | Summary result construction. |
129
+ | `summary-state.ts` | Mutable summary state helpers. |
130
+ | `summary-token-transfer.ts` | Token transfer helpers used during summary inference. |
131
+ | `routine-summaries.ts` | Computes routine summaries to a fixed point and applies external contracts. |
132
+ | `summaries.ts` | Builds summary lookup tables, profile summaries, unknown-boundary diagnostics and candidate fixability. |
133
+ | `liveness.ts` | Computes live register contract units and detects caller/callee conflicts. |
134
+ | `constants.ts` | Shared register contract constants. |
135
+ | `instruction-head.ts` | Extracts instruction heads for analysis. |
136
+ | `instruction-operands.ts` | Extracts operands for analysis. |
137
+ | `instruction-predicates.ts` | Instruction shape predicates used by analysis. |
138
+ | `operand-register-name.ts` | Converts operand names into register contract register names. |
139
+ | `carriers.ts` | Normalizes register contract carrier names and expands register pairs. |
140
+ | `controlFlow.ts` | Successor logic for routine instruction flow. |
141
+ | `profiles.ts` | Built-in external routine profiles such as MON-3. |
142
+ | `report.ts` | Renders `.regcontracts.txt`, `.asmi` and compact source contract blocks. |
143
+ | `annotate.ts` | Inserts or replaces generated contract blocks near routine labels. |
144
+ | `annotations.ts` | Builds source annotation artifact data. |
145
+ | `fix.ts` | Finds and applies conservative expected-output fixes. |
146
+ | `accept-output.ts` | Parses user-accepted output candidate options. |
147
+ | `tooling.ts` | Editor-friendly register contract diagnostics and code actions. |
148
+ | `types.ts` | Register contract unit, routine, effect, summary, contract and report types. |
149
+ | `sourceText.ts` | Source line splitting and joining helpers for text edits. |
150
+ | `boundaryHints.ts` | Small helpers for naming external service boundaries. |
151
+
152
+ ## `src/semantics/`
153
+
154
+ | File | Role |
155
+ | ---------------------------- | ------------------------------------------------------------------------- |
156
+ | `expression-evaluation.ts` | Coordinates expression evaluation against the assembler-time environment. |
157
+ | `binary-operators.ts` | Binary arithmetic, bitwise, comparison and logical operators. |
158
+ | `unary-operators.ts` | Unary numeric operators. |
159
+ | `constant-operator-types.ts` | Shared constant-operator typing. |
160
+ | `constant-operators.ts` | Constant-operator dispatch. |
161
+ | `byte-functions.ts` | Byte extraction helpers such as `LSB` and `MSB`. |
162
+ | `layout-evaluation.ts` | Layout type expression, `sizeof` and `offset` evaluation. |
163
+ | `layout-format.ts` | Layout name formatting for diagnostics. |
164
+ | `layout-path.ts` | Field and array path evaluation for layout casts. |
165
+ | `diagnostics.ts` | Shared semantic diagnostics. |
166
+
167
+ ## `src/source/`
168
+
169
+ | File | Role |
170
+ | ------------------------- | -------------------------------------------------------- |
171
+ | `source-file.ts` | Creates source file records from name and text. |
172
+ | `logical-lines.ts` | Splits source text into logical line records. |
173
+ | `source-span.ts` | Defines source span shape. |
174
+ | `line-comment-scanner.ts` | Finds semicolon comments while respecting quoted text. |
175
+ | `strip-line-comment.ts` | Removes semicolon comments while respecting quoted text. |
176
+
177
+ ## `src/syntax/`
178
+
179
+ | File | Role |
180
+ | ------------------------------ | ----------------------------------------------------- |
181
+ | `parse-line.ts` | Parses single logical lines into source items. |
182
+ | `expression-tokenizer.ts` | Tokenizes expression text. |
183
+ | `parse-token-expression.ts` | Parses tokenized expressions into ASTs. |
184
+ | `parse-expression.ts` | Public expression parse wrapper. |
185
+ | `parse-directive-statement.ts` | Parses directive statements with structured operands. |
186
+ | `parse-layout-declarations.ts` | Parses layout declaration forms. |
187
+ | `parse-layout-expression.ts` | Parses layout type expressions. |
188
+ | `parse-diagnostics.ts` | Shared parse diagnostic helpers. |
189
+ | `directive-aliases.ts` | Built-in and project directive alias policy. |
190
+
191
+ ## `src/tooling/`
192
+
193
+ | File | Role |
194
+ | --------------- | --------------------------------------------------------------------- |
195
+ | `api.ts` | `loadProgramNext()` and `analyzeProgramNext()` for tooling consumers. |
196
+ | `case-style.ts` | Mnemonic, register and op-head case-style linting. |
197
+
198
+ ## `src/z80/`
199
+
200
+ | File | Role |
201
+ | ------------------------ | ---------------------------------------------------------------------- |
202
+ | `instruction.ts` | Z80 instruction and operand type model. |
203
+ | `parse-instruction.ts` | Dispatches instruction parsing by instruction family. |
204
+ | `parse-basic.ts` | Parses basic one-head instruction forms. |
205
+ | `parse-branch.ts` | Parses branch and call forms. |
206
+ | `parse-conditions.ts` | Parses condition-code operands. |
207
+ | `parse-exchange.ts` | Parses exchange forms. |
208
+ | `parse-io-control.ts` | Parses I/O and control forms. |
209
+ | `parse-ld.ts` | Parses `ld` forms. |
210
+ | `parse-operands.ts` | Parses and classifies instruction operands. |
211
+ | `operand-split.ts` | Splits operands while respecting parentheses, strings and expressions. |
212
+ | `operand-split-state.ts` | State machine helpers for operand splitting. |
213
+ | `ld-support.ts` | Shared `ld` form support. |
214
+ | `encode.ts` | Dispatches encoding by instruction family. |
215
+ | `encode-core.ts` | Core encoder helpers. |
216
+ | `encode-ld.ts` | `ld` encoder. |
217
+ | `encode-ld-helpers.ts` | Shared `ld` encoder helpers. |
218
+ | `effects.ts` | Describes register and flag effects for Z80 instructions. |
219
+ | `effect-groups.ts` | Shared effect groups. |
220
+ | `effect-units.ts` | Effect unit definitions. |
221
+
222
+ ## `test/`
223
+
224
+ | Directory | Role |
225
+ | -------------------------------------- | ------------------------------------------------ |
226
+ | `test/unit/syntax/` | Parser and expression unit tests. |
227
+ | `test/unit/source/` | Source-line and comment helpers. |
228
+ | `test/unit/z80/` | Z80 parser and encoder tests. |
229
+ | `test/unit/outputs/` | Artifact writer tests. |
230
+ | `test/unit/expansion/` | Op expansion tests. |
231
+ | `test/unit/register-contracts/` | Register contract analysis units. |
232
+ | `test/integration/` | Cross-stage compiler tests. |
233
+ | `test/integration/register-contracts/` | End-to-end register contract tests. |
234
+ | `test/cli/` | CLI option, artifact and exit-code contracts. |
235
+ | `test/asm80/` | ASM80 compatibility and real-program acceptance. |
236
+ | `test/differential/` | Differential comparison fixtures and runners. |
237
+ | `test/fixtures/` | Source fixture programs. |
238
+ | `test/helpers/` | Shared test setup and helpers. |
239
+ | `test/types/` | Public TypeScript surface checks. |
240
+
241
+ ## `docs/`
242
+
243
+ | Directory | Role |
244
+ | ---------------- | --------------------------------------------- |
245
+ | `docs/codebase/` | Maintained engineering manual and appendices. |
246
+
247
+ ## `scripts/`
248
+
249
+ | Directory | Role |
250
+ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
251
+ | `scripts/ci/` | CI checks and policy scripts. |
252
+ | `scripts/dev/` | Developer utilities for alpha guardrails, corpus checks, ASM80 parity, binary mismatch analysis, package smoke tests and coverage. |
253
+ | `scripts/` root | General maintenance scripts such as source-size checks and grammar generation. |
@@ -0,0 +1,103 @@
1
+ ---
2
+ layout: default
3
+ title: 'Appendix B - Compile Flow Reference'
4
+ parent: 'Appendices'
5
+ grand_parent: 'AZM Engineering Manual'
6
+ nav_order: 2
7
+ ---
8
+
9
+ [<- Appendix A](a-directory-file-reference.md) | [Appendix C ->](c-public-surface-reference.md)
10
+
11
+ # Appendix B - Compile Flow Reference
12
+
13
+ This appendix gives the compact compile-flow map.
14
+
15
+ ## File-Backed Compile API
16
+
17
+ ```text
18
+ compile(entryFile, options, deps)
19
+ normalize entry path
20
+ loadProgramNext()
21
+ expandSourceForTooling()
22
+ read entry source
23
+ expand textual .include and tooling .import
24
+ collect source texts
25
+ collect source line comments
26
+ attach source ownership metadata
27
+ scan logical lines
28
+ read directive alias profiles
29
+ build directive alias policy
30
+ parseNextSourceItems()
31
+ applyConditionalAssembly()
32
+ collect op definitions
33
+ tokenize and parse expressions
34
+ parse layouts, aliases, enums, directives and instructions
35
+ expand op invocations
36
+ analyzeProgramNext()
37
+ assembleProgram() for symbols
38
+ lintCaseStyleNext()
39
+ optionally runRegisterContracts()
40
+ load .asmi interfaces
41
+ build program model
42
+ read AZMDoc and .asmi contracts
43
+ infer summaries
44
+ run liveness
45
+ build report, interface and annotation artifacts
46
+ assembleProgram()
47
+ buildAddressState()
48
+ emitProgramImage()
49
+ emitAssemblyArtifacts()
50
+ writeBin()
51
+ writeHex()
52
+ writeD8m()
53
+ writeAsm80()
54
+ return diagnostics and in-memory artifacts
55
+ ```
56
+
57
+ ## CLI Flow
58
+
59
+ ```text
60
+ cli.ts
61
+ runCli(argv)
62
+ parseCliArgs(argv)
63
+ artifactBase()
64
+ buildCompileOptions()
65
+ compile()
66
+ format diagnostics
67
+ writeArtifacts()
68
+ writeArtifactFiles()
69
+ return exit code
70
+ ```
71
+
72
+ ## Tooling Flow
73
+
74
+ ```text
75
+ loadProgramNext()
76
+ expand source
77
+ parse source items
78
+ return LoadedProgramNext
79
+
80
+ analyzeProgramNext(loaded)
81
+ assemble for symbols
82
+ run case-style lint
83
+ return diagnostics and symbol environment
84
+
85
+ analyzeRegisterContractsForTools(loaded)
86
+ run register contract analysis in audit-oriented tooling mode
87
+ return candidate diagnostics and code actions
88
+ ```
89
+
90
+ `analyzeRegisterCareForTools()` remains as a deprecated compatibility export for
91
+ tooling integrations that still use the older name.
92
+
93
+ ## Data Handoffs
94
+
95
+ | Stage | Input | Output |
96
+ | ------------------ | -------------------- | ------------------------------------- |
97
+ | Source loading | entry path | logical lines with ownership metadata, source texts, comments |
98
+ | Parsing | logical lines | source items |
99
+ | Analysis | source items | diagnostics, symbols |
100
+ | Register contracts | loaded program | summaries, conflicts, reports |
101
+ | Assembly | source items | byte map, symbols, source segments |
102
+ | Outputs | byte map and symbols | artifacts |
103
+ | CLI | artifacts | files on disk |
@@ -0,0 +1,106 @@
1
+ ---
2
+ layout: default
3
+ title: 'Appendix C - Public Surface Reference'
4
+ parent: 'Appendices'
5
+ grand_parent: 'AZM Engineering Manual'
6
+ nav_order: 3
7
+ ---
8
+
9
+ [<- Appendix B](b-compile-flow-reference.md)
10
+
11
+ # Appendix C - Public Surface Reference
12
+
13
+ This appendix lists the public package surfaces that should remain stable across
14
+ ordinary implementation changes.
15
+
16
+ ## Package Paths
17
+
18
+ ```text
19
+ @jhlagado/azm
20
+ @jhlagado/azm/compile
21
+ @jhlagado/azm/tooling
22
+ @jhlagado/azm/cli
23
+ @jhlagado/azm/package.json
24
+ ```
25
+
26
+ ## Root Exports
27
+
28
+ `@jhlagado/azm` re-exports the stable compile, tooling, diagnostic,
29
+ register contract and output types. It is the broad package entry for consumers that
30
+ want one import path.
31
+
32
+ ## Compile Exports
33
+
34
+ `@jhlagado/azm/compile` exposes:
35
+
36
+ - `compile`
37
+ - `defaultFormatWriters`
38
+ - `writeHex`
39
+ - compile option and result types
40
+ - artifact types
41
+ - D8 map types
42
+ - output writer types
43
+
44
+ Use this path for build tools, Debug80 integration and scripts that need bytes
45
+ or artifacts.
46
+
47
+ ## Tooling Exports
48
+
49
+ `@jhlagado/azm/tooling` exposes:
50
+
51
+ - `loadProgram`
52
+ - `loadProgramNext`
53
+ - `analyzeProgram`
54
+ - `analyzeProgramNext`
55
+ - `analyzeRegisterContractsForTools`
56
+ - diagnostic types
57
+ - case-style mode types
58
+ - register contract tooling result types
59
+
60
+ Use this path for editors, linters and language tooling.
61
+
62
+ `analyzeRegisterCareForTools` remains as a deprecated compatibility export.
63
+
64
+ Tooling consumers should treat parsed item spans as provenance-bearing data.
65
+ When present, `sourceUnit` names the owning source unit and `sourceRelation`
66
+ records whether that unit entered the load through `entry`, `include` or
67
+ `import`.
68
+
69
+ ## CLI Export
70
+
71
+ `@jhlagado/azm/cli` exposes the compiled CLI module and backs the `azm` binary.
72
+ The user-facing command is the package binary:
73
+
74
+ ```sh
75
+ azm [options] <entry.asm|entry.z80>
76
+ ```
77
+
78
+ ## Package Metadata Export
79
+
80
+ `@jhlagado/azm/package.json` exposes package metadata for tools that need the
81
+ installed package version or package fields without importing implementation
82
+ modules.
83
+
84
+ ## Public Data Shapes
85
+
86
+ Treat these as public contracts:
87
+
88
+ - `Diagnostic`
89
+ - `CompileNextFunctionOptions`
90
+ - `CompileNextResult`
91
+ - `Artifact`
92
+ - `D8mJson`
93
+ - `D8mArtifact`
94
+ - `D8mSegment`
95
+ - `D8mSymbol`
96
+ - `LoadedProgramNext`
97
+ - `AnalyzeProgramNextResult`
98
+ - `RegisterContractsCandidateDiagnostic`
99
+ - `RegisterContractsCodeAction`
100
+
101
+ For tooling consumers, this contract also includes the optional
102
+ `SourceSpan.sourceUnit` and `SourceSpan.sourceRelation` fields carried on parsed
103
+ items.
104
+
105
+ When these shapes change, update package tests, TypeScript type tests, README
106
+ examples, repo-local reference docs and this manual.
@@ -0,0 +1,16 @@
1
+ ---
2
+ layout: default
3
+ title: 'Appendices'
4
+ parent: 'AZM Engineering Manual'
5
+ nav_order: 7
6
+ has_children: true
7
+ has_toc: false
8
+ ---
9
+
10
+ # Appendices
11
+
12
+ Quick-reference material for engineers working with the AZM codebase.
13
+
14
+ - [Appendix A - Directory and File Reference](a-directory-file-reference.md)
15
+ - [Appendix B - Compile Flow Reference](b-compile-flow-reference.md)
16
+ - [Appendix C - Public Surface Reference](c-public-surface-reference.md)
@@ -0,0 +1,46 @@
1
+ ---
2
+ layout: default
3
+ title: 'AZM Engineering Manual'
4
+ nav_order: 91
5
+ has_children: true
6
+ has_toc: false
7
+ ---
8
+
9
+ # AZM Engineering Manual
10
+
11
+ This book is a technical reference for engineers working on the AZM assembler.
12
+ It explains the repository structure, the compile pipeline, the public APIs, the
13
+ source parser, the assembly model, the Z80 encoder, register contract analysis,
14
+ artifact writing and the verification lanes that support the implementation.
15
+
16
+ This manual is updated against the AZM codebase state through **2026-06-04**.
17
+ Use it as the map when planning changes. Use the TypeScript source and tests as
18
+ the final authority when a detail has changed.
19
+
20
+ AZM is deliberately compact. The codebase is organised around one central path:
21
+ load source, parse it into source items, expand visible ops, build assembler-time
22
+ facts, emit bytes, resolve fixups and write artifacts. Most files either support
23
+ one step on that path or expose the path to the CLI, Debug80 or tests.
24
+
25
+ Recent implementation work split several broad modules into smaller files and
26
+ renamed the register contract subsystem around the `register-contracts` term.
27
+ Parsing, expression evaluation, Z80 encoding, ASM80 lowering, D8 map writing,
28
+ register contract summaries and CLI artifact writing now have dedicated helper
29
+ modules. The directory appendix is the current file map for those modules.
30
+
31
+ ---
32
+
33
+ ## Chapters
34
+
35
+ - [Chapter 1 - Orientation and Repository Layout](01-orientation-and-repository-layout.md)
36
+ - [Chapter 2 - Source Loading and Parsing](02-source-loading-and-parsing.md)
37
+ - [Chapter 3 - Assembly and Z80 Emission](03-assembly-and-z80-emission.md)
38
+ - [Chapter 4 - Ops and Register Contracts](04-ops-and-register-contracts.md)
39
+ - [Chapter 5 - Interfaces and Output Artifacts](05-interfaces-and-output-artifacts.md)
40
+ - [Chapter 6 - Verification and Maintenance](06-verification-and-maintenance.md)
41
+
42
+ ## Appendices
43
+
44
+ - [Appendix A - Directory and File Reference](appendices/a-directory-file-reference.md)
45
+ - [Appendix B - Compile Flow Reference](appendices/b-compile-flow-reference.md)
46
+ - [Appendix C - Public Surface Reference](appendices/c-public-surface-reference.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jhlagado/azm",
3
- "version": "0.2.7",
3
+ "version": "0.2.9",
4
4
  "description": "AZM assembler for the Z80 family (Node.js CLI)",
5
5
  "license": "GPL-3.0-only",
6
6
  "engines": {
@@ -33,8 +33,7 @@
33
33
  },
34
34
  "files": [
35
35
  "dist/src",
36
- "docs/reference/cli.md",
37
- "docs/reference/tooling-api.md"
36
+ "docs/codebase"
38
37
  ],
39
38
  "publishConfig": {
40
39
  "access": "public"
@@ -1,2 +0,0 @@
1
- import type { RegisterCareUnit } from './types.js';
2
- export declare function parseAcceptedOutputCandidates(items?: readonly string[]): Map<string, RegisterCareUnit[]>;