fcdev 0.1.0 → 0.3.0

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 (260) hide show
  1. package/README.md +21 -2
  2. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +164 -0
  3. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +157 -0
  4. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +123 -0
  5. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +51 -0
  6. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +100 -0
  7. package/docs/06-/345/217/215/346/261/207/347/274/226.md +103 -0
  8. package/docs/07-/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +74 -0
  9. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +72 -0
  10. package/docs/09-/345/217/221/345/270/203.md +67 -0
  11. package/docs/10-VS Code/346/211/251/345/261/225.md" +131 -0
  12. package/docs/nes/01-NES/347/233/256/346/240/207.md +52 -0
  13. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +252 -0
  14. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +797 -0
  15. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +27 -0
  16. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +46 -0
  17. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +10 -0
  18. package/package.json +4 -3
  19. package/src/api/header-parser.mjs +78 -0
  20. package/src/api/index.mjs +128 -0
  21. package/src/build/bank-link-config.mjs +74 -0
  22. package/src/build/index.mjs +1 -0
  23. package/src/build/program-builder.mjs +5 -2
  24. package/src/cli/commands/api-command.mjs +62 -0
  25. package/src/cli/commands/docs-command.mjs +58 -0
  26. package/src/cli/index.mjs +6 -0
  27. package/src/docs/doc-index.mjs +101 -0
  28. package/src/docs/doc-topics.mjs +38 -0
  29. package/src/docs/index.mjs +10 -0
  30. package/src/targets/target-registry.mjs +38 -0
  31. package/targets/nes/lib/fcnes.lib +0 -0
  32. package/targets/nes/lib/nes-font.o +0 -0
  33. package/targets/sb2000/api-reference.md +3295 -0
  34. package/targets/sb2000/api-unwrapped.json +36 -0
  35. package/targets/sb2000/asminc/sb2000.inc +203 -1
  36. package/targets/sb2000/include/sb2000-bank.h +74 -0
  37. package/targets/sb2000/include/sb2000-clock.h +68 -0
  38. package/targets/sb2000/include/sb2000-disk.h +141 -0
  39. package/targets/sb2000/include/sb2000-display.h +352 -0
  40. package/targets/sb2000/include/sb2000-file.h +273 -0
  41. package/targets/sb2000/include/sb2000-ime.h +158 -0
  42. package/targets/sb2000/include/sb2000-input.h +192 -0
  43. package/targets/sb2000/include/sb2000-math.h +228 -0
  44. package/targets/sb2000/include/sb2000-memory.h +115 -0
  45. package/targets/sb2000/include/sb2000-printer.h +116 -0
  46. package/targets/sb2000/include/sb2000-sound.h +134 -0
  47. package/targets/sb2000/include/sb2000-symbols.h +397 -1
  48. package/targets/sb2000/include/sb2000-system.h +219 -0
  49. package/targets/sb2000/include/sb2000-text.h +99 -0
  50. package/targets/sb2000/include/sb2000.h +13 -20
  51. package/targets/sb2000/lib/crt0.o +0 -0
  52. package/targets/sb2000/lib/sb2000.lib +0 -0
  53. package/targets/sb2000/lib-build.json +1 -1
  54. package/targets/sb2000/link-banked.cfg +42 -0
  55. package/targets/sb2000/src/crt0.s +89 -4
  56. package/targets/sb2000/src/lib/bank/sb-bank-current.c +18 -0
  57. package/targets/sb2000/src/lib/bank/sb-bank-select.c +21 -0
  58. package/targets/sb2000/src/lib/bank/sbi-bank-trampoline.s +46 -0
  59. package/targets/sb2000/src/lib/clock/sb-clock-get-date.c +17 -0
  60. package/targets/sb2000/src/lib/clock/sb-clock-get-time.c +17 -0
  61. package/targets/sb2000/src/lib/clock/sb-clock-set-date.c +21 -0
  62. package/targets/sb2000/src/lib/clock/sb-clock-set-time.c +17 -0
  63. package/targets/sb2000/src/lib/clock/sbi-date-from-fat.c +20 -0
  64. package/targets/sb2000/src/lib/clock/sbi-date-to-fat.c +24 -0
  65. package/targets/sb2000/src/lib/clock/sbi-time-from-fat.c +20 -0
  66. package/targets/sb2000/src/lib/clock/sbi-time-to-fat.c +19 -0
  67. package/targets/sb2000/src/lib/disk/sb-disk-format-track.c +18 -0
  68. package/targets/sb2000/src/lib/disk/sb-disk-free-bytes.c +38 -0
  69. package/targets/sb2000/src/lib/disk/sb-disk-init.c +16 -0
  70. package/targets/sb2000/src/lib/disk/sb-disk-read-sector.c +24 -0
  71. package/targets/sb2000/src/lib/disk/sb-disk-read-sectors.c +17 -0
  72. package/targets/sb2000/src/lib/disk/sb-disk-scan-track.c +27 -0
  73. package/targets/sb2000/src/lib/disk/sb-disk-start.c +16 -0
  74. package/targets/sb2000/src/lib/disk/sb-disk-stop.c +16 -0
  75. package/targets/sb2000/src/lib/disk/sb-disk-write-sector.c +19 -0
  76. package/targets/sb2000/src/lib/disk/sb-disk-write-sectors.c +17 -0
  77. package/targets/sb2000/src/lib/disk/sbi-disk-batch.c +23 -0
  78. package/targets/sb2000/src/lib/disk/sbi-disk-call.c +17 -0
  79. package/targets/sb2000/src/lib/disk/sbi-disk-set-position.c +18 -0
  80. package/targets/sb2000/src/lib/display/sb-cell-address.c +20 -0
  81. package/targets/sb2000/src/lib/display/sb-cells-copy.c +27 -0
  82. package/targets/sb2000/src/lib/display/sb-cells-fill.c +25 -0
  83. package/targets/sb2000/src/lib/display/sb-cells-rect.c +20 -0
  84. package/targets/sb2000/src/lib/display/sb-display-mode.c +16 -0
  85. package/targets/sb2000/src/lib/display/sb-glyph-address.c +28 -0
  86. package/targets/sb2000/src/lib/display/sb-image-fill-rect.c +26 -0
  87. package/targets/sb2000/src/lib/display/sb-image-load-raw.c +22 -0
  88. package/targets/sb2000/src/lib/display/sb-image-show-full.c +20 -0
  89. package/targets/sb2000/src/lib/display/sb-image-show.c +25 -0
  90. package/targets/sb2000/src/lib/display/sb-image-unpack-map.c +28 -0
  91. package/targets/sb2000/src/lib/display/sb-image-unpack-tiles.c +20 -0
  92. package/targets/sb2000/src/lib/display/sb-image-unpack-to-memory.c +22 -0
  93. package/targets/sb2000/src/lib/display/sb-palette-write.c +20 -0
  94. package/targets/sb2000/src/lib/display/sb-screen-clear.c +19 -0
  95. package/targets/sb2000/src/lib/display/sb-screen-flush.c +16 -0
  96. package/targets/sb2000/src/lib/display/sb-text-draw.c +22 -0
  97. package/targets/sb2000/src/lib/display/sb-text-field-ascii.c +25 -0
  98. package/targets/sb2000/src/lib/display/sb-text-field.c +25 -0
  99. package/targets/sb2000/src/lib/display/sb-text-to-memory.c +27 -0
  100. package/targets/sb2000/src/lib/display/sb-vram-bank.c +17 -0
  101. package/targets/sb2000/src/lib/display/sb-vram-fill.c +21 -0
  102. package/targets/sb2000/src/lib/display/sb-vram-load.c +21 -0
  103. package/targets/sb2000/src/lib/display/sb-window-compact.c +16 -0
  104. package/targets/sb2000/src/lib/display/sb-window-init.c +16 -0
  105. package/targets/sb2000/src/lib/display/sb-window-restore.c +17 -0
  106. package/targets/sb2000/src/lib/display/sb-window-save.c +21 -0
  107. package/targets/sb2000/src/lib/file/sb-dir-change.c +21 -0
  108. package/targets/sb2000/src/lib/file/sb-dir-current.c +27 -0
  109. package/targets/sb2000/src/lib/file/sb-dir-make.c +21 -0
  110. package/targets/sb2000/src/lib/file/sb-dir-open.c +61 -0
  111. package/targets/sb2000/src/lib/file/sb-dir-read.c +87 -0
  112. package/targets/sb2000/src/lib/file/sb-dir-remove.c +21 -0
  113. package/targets/sb2000/src/lib/file/sb-file-close.c +21 -0
  114. package/targets/sb2000/src/lib/file/sb-file-delete.c +21 -0
  115. package/targets/sb2000/src/lib/file/sb-file-get-attr.c +25 -0
  116. package/targets/sb2000/src/lib/file/sb-file-get-date.c +25 -0
  117. package/targets/sb2000/src/lib/file/sb-file-get-time.c +25 -0
  118. package/targets/sb2000/src/lib/file/sb-file-load.c +50 -0
  119. package/targets/sb2000/src/lib/file/sb-file-open.c +26 -0
  120. package/targets/sb2000/src/lib/file/sb-file-read.c +52 -0
  121. package/targets/sb2000/src/lib/file/sb-file-rename.c +30 -0
  122. package/targets/sb2000/src/lib/file/sb-file-save.c +31 -0
  123. package/targets/sb2000/src/lib/file/sb-file-set-attr.c +22 -0
  124. package/targets/sb2000/src/lib/file/sb-file-set-date.c +25 -0
  125. package/targets/sb2000/src/lib/file/sb-file-set-time.c +22 -0
  126. package/targets/sb2000/src/lib/file/sb-file-size.c +27 -0
  127. package/targets/sb2000/src/lib/file/sb-file-write-all.c +32 -0
  128. package/targets/sb2000/src/lib/file/sb-file-write.c +60 -0
  129. package/targets/sb2000/src/lib/file/sbi-dir-state.c +15 -0
  130. package/targets/sb2000/src/lib/file/sbi-dos-call.c +17 -0
  131. package/targets/sb2000/src/lib/file/sbi-load-sector.c +18 -0
  132. package/targets/sb2000/src/lib/file/sbi-select-handle.c +20 -0
  133. package/targets/sb2000/src/lib/file/sbi-set-path.c +26 -0
  134. package/targets/sb2000/src/lib/ime/sb-ime-get-method.c +17 -0
  135. package/targets/sb2000/src/lib/ime/sb-ime-get-state.c +18 -0
  136. package/targets/sb2000/src/lib/ime/sb-ime-hex.c +20 -0
  137. package/targets/sb2000/src/lib/ime/sb-ime-init.c +26 -0
  138. package/targets/sb2000/src/lib/ime/sb-ime-key-wait.c +19 -0
  139. package/targets/sb2000/src/lib/ime/sb-ime-key.c +19 -0
  140. package/targets/sb2000/src/lib/ime/sb-ime-parse.c +23 -0
  141. package/targets/sb2000/src/lib/ime/sb-ime-resume.c +16 -0
  142. package/targets/sb2000/src/lib/ime/sb-ime-select.c +19 -0
  143. package/targets/sb2000/src/lib/ime/sb-ime-set-state.c +18 -0
  144. package/targets/sb2000/src/lib/ime/sb-ime-set-width.c +16 -0
  145. package/targets/sb2000/src/lib/ime/sb-ime-suspend.c +16 -0
  146. package/targets/sb2000/src/lib/input/sb-break-disable.c +16 -0
  147. package/targets/sb2000/src/lib/input/sb-break-enable.c +16 -0
  148. package/targets/sb2000/src/lib/input/sb-key-count.c +17 -0
  149. package/targets/sb2000/src/lib/input/sb-key-flush.c +16 -0
  150. package/targets/sb2000/src/lib/input/sb-key-init.c +16 -0
  151. package/targets/sb2000/src/lib/input/sb-key-modifiers.c +16 -0
  152. package/targets/sb2000/src/lib/input/sb-key-poll.c +17 -0
  153. package/targets/sb2000/src/lib/input/sb-key-wait.c +17 -0
  154. package/targets/sb2000/src/lib/input/sb-keyboard-reset.c +17 -0
  155. package/targets/sb2000/src/lib/input/sb-mouse-buttons.c +21 -0
  156. package/targets/sb2000/src/lib/input/sb-mouse-position.c +18 -0
  157. package/targets/sb2000/src/lib/input/sb-mouse-reset.c +17 -0
  158. package/targets/sb2000/src/lib/input/sb-mouse-set-double-click.c +17 -0
  159. package/targets/sb2000/src/lib/input/sb-mouse-set-limits.c +26 -0
  160. package/targets/sb2000/src/lib/input/sb-mouse-set-position.c +18 -0
  161. package/targets/sb2000/src/lib/input/sb-pad-init.c +17 -0
  162. package/targets/sb2000/src/lib/input/sb-pad-poll.c +17 -0
  163. package/targets/sb2000/src/lib/input/sb-pad-state.c +16 -0
  164. package/targets/sb2000/src/lib/input/sb-pad-wait.c +17 -0
  165. package/targets/sb2000/src/lib/math/sb-float-add.c +19 -0
  166. package/targets/sb2000/src/lib/math/sb-float-div.c +19 -0
  167. package/targets/sb2000/src/lib/math/sb-float-from-text.c +18 -0
  168. package/targets/sb2000/src/lib/math/sb-float-mul.c +19 -0
  169. package/targets/sb2000/src/lib/math/sb-float-sub.c +19 -0
  170. package/targets/sb2000/src/lib/math/sb-float-to-text.c +19 -0
  171. package/targets/sb2000/src/lib/math/sb-int24-add.c +21 -0
  172. package/targets/sb2000/src/lib/math/sb-int24-div.c +26 -0
  173. package/targets/sb2000/src/lib/math/sb-int24-mul.c +20 -0
  174. package/targets/sb2000/src/lib/math/sb-int24-sub.c +21 -0
  175. package/targets/sb2000/src/lib/math/sb-int40-from-text.c +19 -0
  176. package/targets/sb2000/src/lib/math/sb-int40-to-text.c +27 -0
  177. package/targets/sb2000/src/lib/math/sb-line-step.c +21 -0
  178. package/targets/sb2000/src/lib/math/sb-math-div16.c +27 -0
  179. package/targets/sb2000/src/lib/math/sb-math-time-text.c +21 -0
  180. package/targets/sb2000/src/lib/math/sb-random-next.c +20 -0
  181. package/targets/sb2000/src/lib/math/sb-random-seed.c +19 -0
  182. package/targets/sb2000/src/lib/math/sb-random-warm-up.c +16 -0
  183. package/targets/sb2000/src/lib/math/sbi-peek.c +20 -0
  184. package/targets/sb2000/src/lib/math/sbi-poke.c +20 -0
  185. package/targets/sb2000/src/lib/memory/sb-address-to-far.c +20 -0
  186. package/targets/sb2000/src/lib/memory/sb-far-read-byte.c +17 -0
  187. package/targets/sb2000/src/lib/memory/sb-far-read.c +36 -0
  188. package/targets/sb2000/src/lib/memory/sb-far-write-byte.c +17 -0
  189. package/targets/sb2000/src/lib/memory/sb-far-write.c +36 -0
  190. package/targets/sb2000/src/lib/memory/sb-page-alloc.c +19 -0
  191. package/targets/sb2000/src/lib/memory/sb-page-free.c +19 -0
  192. package/targets/sb2000/src/lib/memory/sb-page-largest-free.c +17 -0
  193. package/targets/sb2000/src/lib/memory/sb-window-map-group.c +17 -0
  194. package/targets/sb2000/src/lib/memory/sb-window-map.c +18 -0
  195. package/targets/sb2000/src/lib/memory/sbi-far-copy-in.s +17 -0
  196. package/targets/sb2000/src/lib/memory/sbi-far-copy-out.s +17 -0
  197. package/targets/sb2000/src/lib/memory/sbi-far-read-byte.s +19 -0
  198. package/targets/sb2000/src/lib/memory/sbi-far-write-byte.s +17 -0
  199. package/targets/sb2000/src/lib/printer/sb-printer-carriage-return.c +16 -0
  200. package/targets/sb2000/src/lib/printer/sb-printer-feed.c +17 -0
  201. package/targets/sb2000/src/lib/printer/sb-printer-graphics-mode.c +16 -0
  202. package/targets/sb2000/src/lib/printer/sb-printer-home.c +16 -0
  203. package/targets/sb2000/src/lib/printer/sb-printer-init-port.c +16 -0
  204. package/targets/sb2000/src/lib/printer/sb-printer-page-left.c +16 -0
  205. package/targets/sb2000/src/lib/printer/sb-printer-page-length.c +17 -0
  206. package/targets/sb2000/src/lib/printer/sb-printer-position.c +18 -0
  207. package/targets/sb2000/src/lib/printer/sb-printer-reset.c +16 -0
  208. package/targets/sb2000/src/lib/printer/sb-printer-send-byte.c +18 -0
  209. package/targets/sb2000/src/lib/printer/sb-printer-text.c +29 -0
  210. package/targets/sb2000/src/lib/sb-internal.h +111 -0
  211. package/targets/sb2000/src/lib/sound/sb-sound-effect-from.c +19 -0
  212. package/targets/sb2000/src/lib/sound/sb-sound-play-from.c +18 -0
  213. package/targets/sb2000/src/lib/sound/sb-sound-play-wav-from.c +18 -0
  214. package/targets/sb2000/src/lib/sound/sb-sound-play-wav.c +16 -0
  215. package/targets/sb2000/src/lib/sound/sb-sound-repeat-wav-from.c +19 -0
  216. package/targets/sb2000/src/lib/sound/sb-sound-status.c +17 -0
  217. package/targets/sb2000/src/lib/sound/sb-sound-stop.c +16 -0
  218. package/targets/sb2000/src/lib/sound/sb-sound-tempo.c +17 -0
  219. package/targets/sb2000/src/lib/sound/sb-sound-transpose.c +17 -0
  220. package/targets/sb2000/src/lib/sound/sb-speech-off.c +16 -0
  221. package/targets/sb2000/src/lib/sound/sb-speech-send-entry-from.c +21 -0
  222. package/targets/sb2000/src/lib/sound/sb-speech-send-from.c +19 -0
  223. package/targets/sb2000/src/lib/sound/sb-speech-send.c +16 -0
  224. package/targets/sb2000/src/lib/system/sb-call-banked.c +19 -0
  225. package/targets/sb2000/src/lib/system/sb-context-restore.c +16 -0
  226. package/targets/sb2000/src/lib/system/sb-context-save.c +19 -0
  227. package/targets/sb2000/src/lib/system/sb-display-off.c +16 -0
  228. package/targets/sb2000/src/lib/system/sb-display-on.c +16 -0
  229. package/targets/sb2000/src/lib/system/sb-display-option.c +18 -0
  230. package/targets/sb2000/src/lib/system/sb-exec.c +22 -0
  231. package/targets/sb2000/src/lib/system/sb-irq-enable.c +19 -0
  232. package/targets/sb2000/src/lib/system/sb-irq-hook-reset.c +20 -0
  233. package/targets/sb2000/src/lib/system/sb-irq-hook-set.c +39 -0
  234. package/targets/sb2000/src/lib/system/sb-irq-mask.c +19 -0
  235. package/targets/sb2000/src/lib/system/sb-jump-banked.s +25 -0
  236. package/targets/sb2000/src/lib/system/sb-nmi-disable.c +16 -0
  237. package/targets/sb2000/src/lib/system/sb-nmi-enable.c +16 -0
  238. package/targets/sb2000/src/lib/system/sb-nmi-hook-reset.c +20 -0
  239. package/targets/sb2000/src/lib/system/sb-nmi-hook-set.c +33 -0
  240. package/targets/sb2000/src/lib/system/sb-nmi-service.c +19 -0
  241. package/targets/sb2000/src/lib/system/sb-stack-pointer.s +18 -0
  242. package/targets/sb2000/src/lib/system/sb-system-init.c +16 -0
  243. package/targets/sb2000/src/lib/system/sb-system-state.c +20 -0
  244. package/targets/sb2000/src/lib/system/sb-wait-frames.s +19 -0
  245. package/targets/sb2000/src/lib/system/sbi-exec-run.s +43 -0
  246. package/targets/sb2000/src/lib/system/sbi-interrupts-off.s +19 -0
  247. package/targets/sb2000/src/lib/system/sbi-interrupts-restore.s +17 -0
  248. package/targets/sb2000/src/lib/text/sb-beep.c +16 -0
  249. package/targets/sb2000/src/lib/text/sb-cursor-column.c +16 -0
  250. package/targets/sb2000/src/lib/text/sb-cursor-left.c +16 -0
  251. package/targets/sb2000/src/lib/text/sb-cursor-right.c +16 -0
  252. package/targets/sb2000/src/lib/text/sb-cursor-row.c +16 -0
  253. package/targets/sb2000/src/lib/text/sb-cursor-set-column.c +18 -0
  254. package/targets/sb2000/src/lib/text/sb-cursor-up.c +16 -0
  255. package/targets/sb2000/src/lib/text/sb-print-hex.c +22 -0
  256. package/targets/sb2000/src/lib/text/sb-print-uint.c +25 -0
  257. package/targets/sb2000/src/lib/text/sb-print.c +35 -0
  258. package/targets/sb2000/src/lib/text/sb-putc.c +26 -0
  259. package/targets/sb2000/src/sb2000.s +0 -3
  260. package/targets/sb2000/target.json +14 -0
@@ -0,0 +1,101 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:doc-index.mjs
3
+ // 说明:开发文档的查询:列出全部主题,按主题名、文件名或关键词查找,给出每份文档的本机路径与在线地址。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-11
7
+ // 备注:文档随主包发布在包根的 docs 目录;在线地址由 package.json 的 repository 推出,分支固定为 master。
8
+ // ------------------------------------------------------------------------
9
+ import path from 'node:path';
10
+ import { fileURLToPath } from 'node:url';
11
+ import { FcdevError, readJsonFile } from '../shared/index.mjs';
12
+ import { DOC_TOPICS } from './doc-topics.mjs';
13
+
14
+ /** 在线文档所在的分支 */
15
+ const ONLINE_BRANCH = 'master';
16
+
17
+ /** 主包根目录 */
18
+ const PACKAGE_DIR = fileURLToPath(new URL('../../', import.meta.url));
19
+
20
+ /**
21
+ * @typedef {object} DocInfo
22
+ * @property {string} topic 主题名
23
+ * @property {string} title 标题
24
+ * @property {string} summary 一句话说明
25
+ * @property {string} file 文件路径:相对 docs 目录,`inPackage` 为 true 时相对主包根目录
26
+ * @property {boolean} [inPackage] 文件在主包根目录下的其他位置,不在 docs 目录里
27
+ * @property {string} localPath 本机的绝对路径
28
+ * @property {string} onlineUrl 在线地址
29
+ */
30
+
31
+ /**
32
+ * docs 目录的绝对路径。
33
+ * @returns {string} 目录路径
34
+ */
35
+ export function docsDirectory() {
36
+ return path.join(PACKAGE_DIR, 'docs');
37
+ }
38
+
39
+ /**
40
+ * 主包在线目录的地址,以 / 结尾。
41
+ * @returns {string} 地址
42
+ * @throws {FcdevError} package.json 里没有仓库地址
43
+ */
44
+ function onlineBase() {
45
+ const { repository } = readJsonFile(path.join(PACKAGE_DIR, 'package.json'));
46
+ if (!repository?.url) {
47
+ throw new FcdevError('package.json 里没有 repository 地址,无法给出在线地址', { code: 'DOCS_NO_REPOSITORY' });
48
+ }
49
+ const repositoryUrl = repository.url.replace(/\.git$/, '');
50
+ const directory = (repository.directory ?? '').replace(/^\/+|\/+$/g, '');
51
+ return `${repositoryUrl}/blob/${ONLINE_BRANCH}/${directory ? `${directory}/` : ''}`;
52
+ }
53
+
54
+ /**
55
+ * 把登记项补全成带路径与地址的文档信息。
56
+ * @param {import('./doc-topics.mjs').DocTopic} entry 登记项
57
+ * @param {string} base 主包在线目录的地址
58
+ * @returns {DocInfo} 文档信息
59
+ */
60
+ function describe(entry, base) {
61
+ const segments = entry.file.split('/');
62
+ return {
63
+ ...entry,
64
+ localPath: path.join(entry.inPackage ? PACKAGE_DIR : docsDirectory(), ...segments),
65
+ onlineUrl: base + (entry.inPackage ? '' : 'docs/') + segments.map(encodeURIComponent).join('/'),
66
+ };
67
+ }
68
+
69
+ /**
70
+ * 列出全部文档。
71
+ * @returns {DocInfo[]} 按登记顺序
72
+ */
73
+ export function listDocs() {
74
+ const base = onlineBase();
75
+ return DOC_TOPICS.map((entry) => describe(entry, base));
76
+ }
77
+
78
+ /**
79
+ * 文件名去掉序号前缀与扩展名后的部分,如 `sb2000/02-系统调用手册.md` 得到 `系统调用手册`。
80
+ * @param {string} file 相对 docs 目录的文件路径
81
+ * @returns {string} 名称
82
+ */
83
+ function fileLabel(file) {
84
+ return path.posix.basename(file, '.md').replace(/^\d+-/, '');
85
+ }
86
+
87
+ /**
88
+ * 按词查找文档:先按主题名精确匹配,再按文件名,最后按主题、标题与说明里的关键词。
89
+ * @param {string} query 查询词,不分大小写
90
+ * @returns {{kind: 'topic'|'file'|'text'|'none', matches: DocInfo[]}} 匹配方式与结果
91
+ */
92
+ export function queryDocs(query) {
93
+ const word = query.trim().toLowerCase();
94
+ const docs = listDocs();
95
+ const byTopic = docs.filter((doc) => doc.topic === word);
96
+ if (byTopic.length > 0) return { kind: 'topic', matches: byTopic };
97
+ const byFile = docs.filter((doc) => path.posix.basename(doc.file, '.md').toLowerCase() === word || fileLabel(doc.file).toLowerCase() === word);
98
+ if (byFile.length > 0) return { kind: 'file', matches: byFile };
99
+ const byText = docs.filter((doc) => [doc.topic, doc.title, doc.summary].some((text) => text.toLowerCase().includes(word)));
100
+ return { kind: byText.length > 0 ? 'text' : 'none', matches: byText };
101
+ }
@@ -0,0 +1,38 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:doc-topics.mjs
3
+ // 说明:开发文档的主题登记表:每份文档的主题名、相对 docs 目录的文件、标题和一句话说明。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-11
7
+ // 备注:新增、改名或删除文档时同步改这里与 docs/01-软件架构设计.md 第 9 节;主题名只用小写字母、数字与连字符,便于在任何终端里输入。
8
+ // ------------------------------------------------------------------------
9
+
10
+ /**
11
+ * @typedef {object} DocTopic
12
+ * @property {string} topic 主题名
13
+ * @property {string} file 文件路径,用 / 分隔;默认相对 docs 目录,`inPackage` 为 true 时相对主包根目录
14
+ * @property {boolean} [inPackage] 文件不在 docs 目录里、而在主包其他目录下(如目标目录里由头文件生成的接口参考)
15
+ * @property {string} title 标题
16
+ * @property {string} summary 一句话说明
17
+ */
18
+
19
+ /** @type {DocTopic[]} */
20
+ export const DOC_TOPICS = [
21
+ { topic: 'architecture', file: '01-软件架构设计.md', title: '软件架构设计', summary: '包的划分、目录、分层规则、设计决策与文档清单' },
22
+ { topic: 'build', file: '02-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
23
+ { topic: 'targets', file: '03-目标规范.md', title: '目标规范', summary: '目标定义、打包器、新增机型的步骤' },
24
+ { topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与平台包' },
25
+ { topic: 'emulator', file: '05-模拟器与调试.md', title: '模拟器与调试', summary: '运行方案、调试服务与命令表、模拟器包' },
26
+ { topic: 'disasm', file: '06-反汇编.md', title: '反汇编', summary: '反汇编前端的流程、输入与限制' },
27
+ { topic: 'create', file: '07-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
28
+ { topic: 'testing', file: '08-测试与验证.md', title: '测试与验证', summary: '测试分层、环境变量与运行方法' },
29
+ { topic: 'release', file: '09-发布.md', title: '发布', summary: '发布顺序、前提与检查' },
30
+ { topic: 'vscode', file: '10-VS Code扩展.md', title: 'VS Code 扩展', summary: '智能感知、语法高亮、项目信息来源、目录分层与打包' },
31
+ { topic: 'nes', file: 'nes/01-NES目标.md', title: 'NES 目标', summary: 'NES 目标的内存与映射器、fcnes 函数、字库、运行' },
32
+ { topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
33
+ { topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
34
+ { topic: 'hardware', file: 'sb2000/03-硬件说明.md', title: 'SB2000 硬件说明', summary: 'SB2000 的硬件行为与寄存器' },
35
+ { topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 fcdev api' },
36
+ { topic: 'todo', file: '待办备忘.md', title: '待办备忘', summary: '已确定以后再做的事项' },
37
+ { topic: 'bugs', file: '缺陷记录.md', title: '缺陷记录', summary: '发现的缺陷及修复情况' },
38
+ ];
@@ -0,0 +1,10 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:index.mjs
3
+ // 说明:docs 目录的对外入口:开发文档的主题登记与查询。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-11
7
+ // 备注:其他目录只能经这个文件引用 docs。
8
+ // ------------------------------------------------------------------------
9
+ export { docsDirectory, listDocs, queryDocs } from './doc-index.mjs';
10
+ export { DOC_TOPICS } from './doc-topics.mjs';
@@ -23,6 +23,16 @@ const RUN_MODES = new Set(['rom', 'firmware-disk']);
23
23
  /** 目标专用选项允许的类型 */
24
24
  const OPTION_TYPES = new Set(['boolean', 'string', 'number']);
25
25
 
26
+ /**
27
+ * @typedef {object} BankedSpec 多页(换页)程序的定义
28
+ * @property {string} option 目标专用选项名,值为库页个数
29
+ * @property {string} linkConfig 链接配置模板(路径值),含 %BANK_MEMORY% 与 %BANK_SEGMENTS% 两行
30
+ * @property {number} generatedFrom 模板里已写出前面的库页,从这一页起由 fcdev 按个数生成
31
+ * @property {number} maxBanks 库页个数的上限
32
+ * @property {string} memory 一个库页的内存区行,{n} 换成库页号
33
+ * @property {string} segment 一个库页的段行,{n} 换成库页号
34
+ */
35
+
26
36
  /**
27
37
  * @typedef {object} Target
28
38
  * @property {string} name 标识
@@ -44,6 +54,7 @@ const OPTION_TYPES = new Set(['boolean', 'string', 'number']);
44
54
  * @property {object|null} disk 磁盘镜像能力
45
55
  * @property {object|null} run 运行方案
46
56
  * @property {Record<string, {type: string, default: unknown, links: string[]}>} options 目标专用选项;布尔选项为 true 时额外链接 links 里的文件(路径值)
57
+ * @property {BankedSpec|null} banked 多页(换页)程序的定义;不支持时为 null
47
58
  */
48
59
 
49
60
  /**
@@ -60,6 +71,28 @@ function requireStringArray(value, field, name) {
60
71
  return value;
61
72
  }
62
73
 
74
+ /**
75
+ * 校验并规范化多页程序的定义。
76
+ * @param {unknown} raw target.json 里的 banked;没有时为 undefined
77
+ * @param {string} name 目标名
78
+ * @param {Record<string, {type: string}>} options 已解析的目标专用选项
79
+ * @returns {BankedSpec|null} 多页定义;没有时为 null
80
+ * @throws {FcdevError} 字段缺失、类型不对,或对应的选项不是数字选项
81
+ */
82
+ function parseBanked(raw, name, options) {
83
+ if (raw === undefined) return null;
84
+ const invalid = (reason) => new FcdevError(`目标 ${name} 的 banked ${reason}`, { code: 'TARGET_INVALID' });
85
+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw invalid('必须是对象');
86
+ for (const field of ['option', 'linkConfig', 'memory', 'segment']) {
87
+ if (typeof raw[field] !== 'string' || raw[field] === '') throw invalid(`缺少字符串字段 ${field}`);
88
+ }
89
+ for (const field of ['generatedFrom', 'maxBanks']) {
90
+ if (!Number.isInteger(raw[field]) || raw[field] < 1) throw invalid(`的 ${field} 必须是不小于 1 的整数`);
91
+ }
92
+ if (options[raw.option]?.type !== 'number') throw invalid(`的 option(${raw.option})必须是 options 里的数字选项`);
93
+ return { option: raw.option, linkConfig: raw.linkConfig, generatedFrom: raw.generatedFrom, maxBanks: raw.maxBanks, memory: raw.memory, segment: raw.segment };
94
+ }
95
+
63
96
  /**
64
97
  * 校验并规范化目标定义。
65
98
  * @param {unknown} raw target.json 的内容
@@ -95,6 +128,7 @@ export function parseTarget(raw, dir) {
95
128
  }
96
129
  options[key] = { type: spec.type, default: spec.default, links: spec.links ?? [] };
97
130
  }
131
+ const banked = parseBanked(raw.banked, raw.name, options);
98
132
  return {
99
133
  name: raw.name,
100
134
  title: raw.title,
@@ -115,6 +149,7 @@ export function parseTarget(raw, dir) {
115
149
  disk: raw.disk ?? null,
116
150
  run: raw.run ?? null,
117
151
  options,
152
+ banked,
118
153
  };
119
154
  }
120
155
 
@@ -181,6 +216,9 @@ export function resolveTargetOptions(target, given) {
181
216
  if (typeof value !== spec.type) {
182
217
  throw new FcdevError(`目标 ${target.name} 的选项 ${key} 类型应为 ${spec.type}`, { code: 'TARGET_OPTION_INVALID' });
183
218
  }
219
+ if (target.banked?.option === key && (!Number.isInteger(value) || value < 0 || value > target.banked.maxBanks)) {
220
+ throw new FcdevError(`目标 ${target.name} 的选项 ${key} 必须是 0 到 ${target.banked.maxBanks} 的整数`, { code: 'TARGET_OPTION_INVALID' });
221
+ }
184
222
  result[key] = value;
185
223
  }
186
224
  return result;
Binary file
Binary file