@diy-accounting-uk/diya-gl 1.0.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 (157) hide show
  1. package/README.md +63 -0
  2. package/bin/diya-gl-mcp.js +10 -0
  3. package/bin/diya-gl-read-workbook.js +11 -0
  4. package/bin/diya-gl-recalc.js +10 -0
  5. package/bin/diya-gl-write-workbook.js +12 -0
  6. package/bin/diya-gl.js +24 -0
  7. package/bin/run-dist-bin.js +23 -0
  8. package/dist/app/bin/build-diya-gl-spec.js +680 -0
  9. package/dist/app/bin/build-packages.js +149 -0
  10. package/dist/app/bin/build-reconciliation-pages.js +1052 -0
  11. package/dist/app/bin/build-sitemaps.js +51 -0
  12. package/dist/app/bin/compliance-report.js +125 -0
  13. package/dist/app/bin/cross-package-reconciliation.js +92 -0
  14. package/dist/app/bin/diya-gl-mcp.js +27 -0
  15. package/dist/app/bin/export.js +318 -0
  16. package/dist/app/bin/extract-scenarios.js +1348 -0
  17. package/dist/app/bin/generate.js +353 -0
  18. package/dist/app/bin/judge-reconciliation.js +649 -0
  19. package/dist/app/bin/reconcile.js +247 -0
  20. package/dist/app/bin/report.js +291 -0
  21. package/dist/app/bin/verify-roundtrip.js +941 -0
  22. package/dist/app/bin/verify-stability.js +429 -0
  23. package/dist/app/bin/write-workbook.js +106 -0
  24. package/dist/app/data/filing/ct-computation-v1.1.toml +1033 -0
  25. package/dist/app/data/filing/ct600-v3.toml +2329 -0
  26. package/dist/app/data/filing/frs105-formats.toml +244 -0
  27. package/dist/app/data/fixture-master-gaps.json +247 -0
  28. package/dist/app/data/hmrc/SOURCE.md +14 -0
  29. package/dist/app/data/hmrc/form-layouts/bst.json +116 -0
  30. package/dist/app/data/hmrc/form-layouts/ltd.json +452 -0
  31. package/dist/app/data/hmrc/form-layouts/se.json +485 -0
  32. package/dist/app/data/hmrc/form-layouts/taxi.json +117 -0
  33. package/dist/app/data/hmrc/sa103-mtd-mapping.json +1078 -0
  34. package/dist/app/data/hmrc/sa103f_mapping_v3.csv +111 -0
  35. package/dist/app/data/judge-rubric.md +52 -0
  36. package/dist/app/data/ltd-2020.toml +49 -0
  37. package/dist/app/data/ltd-2021.toml +49 -0
  38. package/dist/app/data/ltd-2022.toml +49 -0
  39. package/dist/app/data/ltd-2023.toml +49 -0
  40. package/dist/app/data/ltd-2024.toml +49 -0
  41. package/dist/app/data/ltd-2025.toml +49 -0
  42. package/dist/app/data/ltd-2026.toml +53 -0
  43. package/dist/app/data/ltd-2027.toml +51 -0
  44. package/dist/app/data/render-unrepresentable/bst.json +24 -0
  45. package/dist/app/data/render-unrepresentable/ltd.json +863 -0
  46. package/dist/app/data/render-unrepresentable/se.json +455 -0
  47. package/dist/app/data/render-unrepresentable/taxi.json +16 -0
  48. package/dist/app/data/roundtrip-budget.json +38 -0
  49. package/dist/app/data/roundtrip-matrix-budget.json +26 -0
  50. package/dist/app/data/roundtrip-unrepresentable.json +401 -0
  51. package/dist/app/data/se-2020-2021.toml +52 -0
  52. package/dist/app/data/se-2021-2022.toml +52 -0
  53. package/dist/app/data/se-2022-2023.toml +55 -0
  54. package/dist/app/data/se-2023-2024.toml +54 -0
  55. package/dist/app/data/se-2024-2025.toml +51 -0
  56. package/dist/app/data/se-2025-2026.toml +51 -0
  57. package/dist/app/data/se-2026-2027.toml +51 -0
  58. package/dist/app/data/volatile-cells.json +16 -0
  59. package/dist/app/lib/anchors/bst.js +79 -0
  60. package/dist/app/lib/anchors/ltd.js +626 -0
  61. package/dist/app/lib/anchors/run.js +100 -0
  62. package/dist/app/lib/anchors/se.js +456 -0
  63. package/dist/app/lib/anchors/taxi.js +164 -0
  64. package/dist/app/lib/app-resources.js +80 -0
  65. package/dist/app/lib/book-checks/ltd.js +408 -0
  66. package/dist/app/lib/book-checks/se.js +687 -0
  67. package/dist/app/lib/book-checks/taxi.js +215 -0
  68. package/dist/app/lib/book-checks.js +872 -0
  69. package/dist/app/lib/books-engine.js +197 -0
  70. package/dist/app/lib/books-interchange.js +533 -0
  71. package/dist/app/lib/calculators/bst.js +381 -0
  72. package/dist/app/lib/calculators/ltd.js +1938 -0
  73. package/dist/app/lib/calculators/se.js +1239 -0
  74. package/dist/app/lib/calculators/shared.js +131 -0
  75. package/dist/app/lib/calculators/taxi.js +461 -0
  76. package/dist/app/lib/canonical-report-value.js +77 -0
  77. package/dist/app/lib/compliance-report.js +341 -0
  78. package/dist/app/lib/diya-gl-calculator.js +52 -0
  79. package/dist/app/lib/diya-gl-canonical.js +355 -0
  80. package/dist/app/lib/diya-gl-edits-ltd.js +144 -0
  81. package/dist/app/lib/diya-gl-edits.js +361 -0
  82. package/dist/app/lib/diya-gl-loader.js +774 -0
  83. package/dist/app/lib/diya-gl-schema.js +212 -0
  84. package/dist/app/lib/generator.js +1912 -0
  85. package/dist/app/lib/guide.js +33 -0
  86. package/dist/app/lib/headlines.js +293 -0
  87. package/dist/app/lib/link-caches.js +421 -0
  88. package/dist/app/lib/ltd-layout.js +139 -0
  89. package/dist/app/lib/mcp/diya-gl-tools.js +330 -0
  90. package/dist/app/lib/mcp/jsonrpc-stdio.js +66 -0
  91. package/dist/app/lib/mcp/server.js +65 -0
  92. package/dist/app/lib/overtype-sidecar.js +180 -0
  93. package/dist/app/lib/package-builder.js +202 -0
  94. package/dist/app/lib/payslips-date-chain.js +481 -0
  95. package/dist/app/lib/payslips-layout.js +235 -0
  96. package/dist/app/lib/period-shift.js +111 -0
  97. package/dist/app/lib/product-workbook.js +317 -0
  98. package/dist/app/lib/products.js +27 -0
  99. package/dist/app/lib/provenance-data.js +36 -0
  100. package/dist/app/lib/provenance.js +92 -0
  101. package/dist/app/lib/report-generator.js +374 -0
  102. package/dist/app/lib/report-indicators.js +468 -0
  103. package/dist/app/lib/report-serializer.js +392 -0
  104. package/dist/app/lib/scenario-extractor.js +1403 -0
  105. package/dist/app/lib/scenario-loader.js +84 -0
  106. package/dist/app/lib/sitemap-builder.js +59 -0
  107. package/dist/app/lib/spreadsheet-runner.js +566 -0
  108. package/dist/app/lib/tax/capital-allowances.js +77 -0
  109. package/dist/app/lib/tax/corporation-tax.js +144 -0
  110. package/dist/app/lib/tax/income-tax.js +122 -0
  111. package/dist/app/lib/tax/mileage.js +69 -0
  112. package/dist/app/lib/tax/national-insurance.js +31 -0
  113. package/dist/app/lib/tax/vat.js +188 -0
  114. package/dist/app/lib/tax-year.js +31 -0
  115. package/dist/app/lib/template-formula-map.js +253 -0
  116. package/dist/app/lib/workbook-set.js +153 -0
  117. package/dist/app/lib/xlsx-exporter.js +2815 -0
  118. package/dist/app/lib/xlsx-parts.js +111 -0
  119. package/dist/app/lib/xlsx-reader.js +84 -0
  120. package/dist/app/products/bst.js +727 -0
  121. package/dist/app/products/ltd.js +4270 -0
  122. package/dist/app/products/se.js +3403 -0
  123. package/dist/app/products/taxi.js +912 -0
  124. package/dist/app/templates/bst/bst-excel.xlsx +0 -0
  125. package/dist/app/templates/bst/meta.toml +27 -0
  126. package/dist/app/templates/ltd/Cashaccount.xlsx +0 -0
  127. package/dist/app/templates/ltd/Companysecretary.xlsx +0 -0
  128. package/dist/app/templates/ltd/Creditcardaccount.xlsx +0 -0
  129. package/dist/app/templates/ltd/Currentaccount.xlsx +0 -0
  130. package/dist/app/templates/ltd/Dividend Voucher.docx +0 -0
  131. package/dist/app/templates/ltd/Financialaccounts.xlsx +0 -0
  132. package/dist/app/templates/ltd/Fixedassets.xlsx +0 -0
  133. package/dist/app/templates/ltd/Payslips.xlsx +0 -0
  134. package/dist/app/templates/ltd/Purchases.xlsx +0 -0
  135. package/dist/app/templates/ltd/Sales.xlsx +0 -0
  136. package/dist/app/templates/ltd/Salesinvoice.xlsx +0 -0
  137. package/dist/app/templates/ltd/Savingaccount.xlsx +0 -0
  138. package/dist/app/templates/ltd/Vatreturns.xlsx +0 -0
  139. package/dist/app/templates/ltd/expensesform.xlsx +0 -0
  140. package/dist/app/templates/ltd/meta.toml +54 -0
  141. package/dist/app/templates/meta.toml +12 -0
  142. package/dist/app/templates/se/Bank.xlsx +0 -0
  143. package/dist/app/templates/se/Cash.xlsx +0 -0
  144. package/dist/app/templates/se/Financialaccounts.xlsx +0 -0
  145. package/dist/app/templates/se/Fixedassets.xlsx +0 -0
  146. package/dist/app/templates/se/Payslips.xlsx +0 -0
  147. package/dist/app/templates/se/Purchases.xlsx +0 -0
  148. package/dist/app/templates/se/Sales.xlsx +0 -0
  149. package/dist/app/templates/se/Salesinvoice.xlsx +0 -0
  150. package/dist/app/templates/se/Vat.xlsx +0 -0
  151. package/dist/app/templates/se/meta.toml +43 -0
  152. package/dist/app/templates/taxi/meta.toml +43 -0
  153. package/dist/app/templates/taxi/taxi-excel.xlsx +0 -0
  154. package/dist/web/spreadsheets.diyaccounting.co.uk/public/schema/diya-gl-book-v2.schema.json +713 -0
  155. package/dist/web/spreadsheets.diyaccounting.co.uk/public/schema/diya-gl-docs.md +930 -0
  156. package/dist/web/spreadsheets.diyaccounting.co.uk/public/schema/diya-gl-lines-v2.schema.json +220 -0
  157. package/package.json +37 -0
@@ -0,0 +1,235 @@
1
+ // SPDX-License-Identifier: AGPL-3.0-only
2
+ // Copyright (C) 2026 DIY Accounting Ltd
3
+ //
4
+ // payslips-layout.js — where a month tab's monthly payroll block sits on
5
+ // Payslips.xlsx, and the cells the printed payslip joins through. One rule in
6
+ // one module, because the writers that fill the block, the JS engine that
7
+ // recomputes it and the exporter that reads it back all have to agree on the
8
+ // row. Separate copies drifted once and the export silently lost every month
9
+ // the copies disagreed on.
10
+
11
+ // The payroll months take four, four and five weeks a quarter, with a sixth
12
+ // week on the last. The tax calendar fixes this, so it is the same array
13
+ // whatever the package's year end.
14
+ export const PAYROLL_WEEKS_PER_MONTH = [4, 4, 5, 4, 4, 5, 4, 4, 5, 4, 4, 6];
15
+
16
+ /**
17
+ * The row a month tab's monthly payroll block starts on. The tab stacks one
18
+ * ten-row block per tax week from row 8, then the monthly block below them,
19
+ * so the start follows the weeks that month holds. The layout belongs to the
20
+ * sheet, so it is indexed by the month's place in the package's own year --
21
+ * index 0 is the first month tab, whatever month that tab is named.
22
+ * @param {number} monthIndex - 0-11
23
+ * @returns {number}
24
+ */
25
+ export const monthlyPayrollBlockRow = (monthIndex) => 8 + 10 * PAYROLL_WEEKS_PER_MONTH[monthIndex];
26
+
27
+ /**
28
+ * The cell holding the date the month's wages were paid, one row below the
29
+ * block start. It closes the period the block opens with three columns to
30
+ * its left, and a book overwrites it with the day the wages actually went
31
+ * out. It is the only date on the tab any writer touches.
32
+ * @param {number} monthIndex - 0-11
33
+ * @returns {string}
34
+ */
35
+ export const payslipsWagesPaidCell = (monthIndex) => `M${monthlyPayrollBlockRow(monthIndex) + 1}`;
36
+
37
+ /**
38
+ * The cell a month tab's monthly payroll block opens its period in, on the
39
+ * same row as the wages-paid date that closes it. Nothing writes to it, so it
40
+ * is the tab's own calendar whether the package carries a book or not.
41
+ * @param {number} monthIndex - 0-11
42
+ * @returns {string}
43
+ */
44
+ export const payslipsPeriodStartCell = (monthIndex) => `K${monthlyPayrollBlockRow(monthIndex) + 1}`;
45
+
46
+ /**
47
+ * The days a month tab's monthly payroll block covers: the tab's own month of
48
+ * the accounting period, index 0 being the month the period opens in. A March
49
+ * year end runs its accounts over the same twelve months as its payroll, and
50
+ * its first block opens with the payroll year on 6 April rather than on the
51
+ * 1st.
52
+ * @param {Date} periodStart - the accounting period's first day
53
+ * @param {number} monthIndex - 0-11
54
+ * @param {Date} payrollYearStart - payrollYearStart() for this package
55
+ * @returns {{first: Date, last: Date}}
56
+ */
57
+ export function payslipsMonthPeriod(periodStart, monthIndex, payrollYearStart) {
58
+ const months = periodStart.getUTCFullYear() * 12 + periodStart.getUTCMonth() + monthIndex;
59
+ const first = new Date(Date.UTC(Math.floor(months / 12), months % 12, 1));
60
+ const last = new Date(Date.UTC(Math.floor(months / 12), (months % 12) + 1, 0));
61
+ const opensWithPayrollYear =
62
+ monthIndex === 0 &&
63
+ payrollYearStart.getUTCFullYear() === first.getUTCFullYear() &&
64
+ payrollYearStart.getUTCMonth() === first.getUTCMonth();
65
+ return { first: opensWithPayrollYear ? payrollYearStart : first, last };
66
+ }
67
+
68
+ /**
69
+ * The five employee rows of a month's monthly block, from block row + 3.
70
+ * @param {number} monthIndex - 0-11
71
+ * @returns {number[]}
72
+ */
73
+ export const payslipsMonthEntryRows = (monthIndex) => [0, 1, 2, 3, 4].map((i) => monthlyPayrollBlockRow(monthIndex) + 3 + i);
74
+
75
+ // The columns one employee's payslip row carries: D the tax code (headed
76
+ // "Tax Code" in D3, which heads every weekly and monthly block on the tab),
77
+ // F the name, M gross pay, N income tax, O employee NI, R net pay, S the
78
+ // payslip's own reference (a blank spacer in the template that no formula
79
+ // reads) and T employer NI, the entry cell the block's own total row sums.
80
+ export const PAYSLIPS_ENTRY_COLUMNS = {
81
+ taxCode: "D",
82
+ name: "F",
83
+ grossPay: "M",
84
+ incomeTax: "N",
85
+ employeeNI: "O",
86
+ netPay: "R",
87
+ reference: "S",
88
+ employerNI: "T",
89
+ };
90
+
91
+ // The columns the template ships as a literal zero on every row of a monthly
92
+ // block, filled or not. An unused row keeps them, so both engines carry a nil
93
+ // there and neither carries anything in the other four columns.
94
+ export const PAYSLIPS_ZERO_FILLED_COLUMNS = [
95
+ PAYSLIPS_ENTRY_COLUMNS.incomeTax,
96
+ PAYSLIPS_ENTRY_COLUMNS.employeeNI,
97
+ PAYSLIPS_ENTRY_COLUMNS.employerNI,
98
+ ];
99
+
100
+ // The two template positions the reconciliation reads a month tab at
101
+ // directly, by the month's place in the package's year. Both shipped with
102
+ // dead #REF! cells the Payment and Admin aggregates never touch, so each is
103
+ // read on its own month rather than only through a total. Both engines follow
104
+ // this list, so a month tab reaches R from one side only if it reaches R from
105
+ // the other.
106
+ export const PAYSLIPS_DIRECTLY_READ_MONTH_INDEXES = [3, 4];
107
+
108
+ // The Employee sheet keeps one employee per 26-row block, and the start date
109
+ // sits eleven rows down each block. The month tab reads it back as a payroll
110
+ // month number and prints nothing for an employee whose month has not
111
+ // arrived, so the whole printed page hangs off this one cell.
112
+ export const PAYSLIPS_EMPLOYEE_BASE_ROWS = [13, 39, 65, 91, 117];
113
+ export const PAYSLIPS_EMPLOYEE_START_DATE_OFFSET = 11;
114
+
115
+ /**
116
+ * The first day of the payroll year the package's Payslips calendar runs on.
117
+ * The workbook follows the tax year rather than the accounting period, so a
118
+ * company with a June year end still dates its payslips from 6 April.
119
+ * @param {number} financialYear - the year the package's tax data opens in
120
+ * @returns {Date}
121
+ */
122
+ export const payrollYearStart = (financialYear) => new Date(Date.UTC(financialYear, 3, 6));
123
+
124
+ /**
125
+ * The start date to put on the Employee sheet. The sheet finds an employee's
126
+ * first payroll month by looking the date up on its own calendar, and the
127
+ * calendar only covers the payroll year, so a date outside it has no month to
128
+ * find. Anyone who was already being paid when the book's payroll record
129
+ * opens gets the payroll year's first day, which is what the sheet's own
130
+ * caption tells the employer to enter for an existing employee; anyone who
131
+ * joined after that keeps their own day, and still never a day before the
132
+ * calendar opens.
133
+ * @param {Date} joined - the day the employee started, in the book's own frame
134
+ * @param {Date} booksOpened - the earliest payroll the book records, or null
135
+ * @param {Date} onSheet - `joined` shifted into the package's frame
136
+ * @param {Date} yearStart - payrollYearStart() for this package
137
+ * @returns {Date}
138
+ */
139
+ export const payslipsStartDate = (joined, booksOpened, onSheet, yearStart) =>
140
+ (booksOpened && joined < booksOpened) || onSheet < yearStart ? yearStart : onSheet;
141
+
142
+ /**
143
+ * The earliest day the scenario's payroll records a payslip on, which is when
144
+ * the book's own payroll record opens.
145
+ * @param {Object} payroll - scenario.payroll, month key to entries
146
+ * @param {(value: string) => Date} parse
147
+ * @returns {Date|null}
148
+ */
149
+ export function payrollRecordOpened(payroll, parse) {
150
+ let earliest = null;
151
+ for (const entries of Object.values(payroll || {})) {
152
+ for (const entry of entries) {
153
+ if (!entry.date) continue;
154
+ const day = parse(entry.date);
155
+ if (!earliest || day < earliest) earliest = day;
156
+ }
157
+ }
158
+ return earliest;
159
+ }
160
+
161
+ // ── The PAYE remittance schedule (the Payment sheet) ────────────────────────
162
+ //
163
+ // One row per tax month from row 4. B holds the month end and C the day the
164
+ // payment falls due. The rows are the same on every package, whatever its year
165
+ // end, because the tax calendar is.
166
+ //
167
+ // The template reaches both dates by counting a fixed number of days down the
168
+ // Admin calendar, and the count cannot be right for a leap payroll year and a
169
+ // common one at once: the month-end rows land a day early on every month after
170
+ // a leap February, and the last two due-date rows land on the 20th in a year
171
+ // without one. So the generator writes both columns as the dates they are.
172
+ export const PAYE_SCHEDULE_FIRST_ROW = 4;
173
+ export const PAYE_MONTH_END_ROWS = [26, 57, 87, 118, 149, 179, 210, 240, 271, 302, 330, 361];
174
+ export const PAYE_DUE_DATE_ROWS = [45, 76, 106, 137, 168, 198, 229, 259, 290, 321, 350, 381];
175
+ // The day of the month a PAYE payment falls due, in the month after the tax
176
+ // month it settles.
177
+ export const PAYE_DUE_DAY = 19;
178
+
179
+ /**
180
+ * The two dates a PAYE schedule row carries: the end of the calendar month the
181
+ * tax month runs to, and the day the payment for it falls due.
182
+ * @param {Date} payrollYearOpens - payrollYearStart() for this package
183
+ * @param {number} taxMonthIndex - 0-11, row 4 being 0
184
+ * @returns {{ends: Date, due: Date}}
185
+ */
186
+ export function payeTaxMonthDates(payrollYearOpens, taxMonthIndex) {
187
+ const months = payrollYearOpens.getUTCFullYear() * 12 + payrollYearOpens.getUTCMonth() + taxMonthIndex;
188
+ return {
189
+ ends: new Date(Date.UTC(Math.floor(months / 12), (months % 12) + 1, 0)),
190
+ due: new Date(Date.UTC(Math.floor((months + 1) / 12), (months + 1) % 12, PAYE_DUE_DAY)),
191
+ };
192
+ }
193
+
194
+ // The month tab each row takes its figures from: the tab named for the
195
+ // calendar month that tax month ends in, which is the tab a month's payroll is
196
+ // written to. Row 4 is April whatever the package's year end, so this list
197
+ // does not move with the tabs.
198
+ export const PAYE_SCHEDULE_MONTH_TABS = ["Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec", "Jan", "Feb", "Mar"];
199
+
200
+ // The row-1 aggregates a schedule row reads its month tab through. The
201
+ // schedule owes HMRC the whole month's figures, so these are the tab's own
202
+ // totals rather than either side of the employee/director split.
203
+ export const PAYE_SCHEDULE_MONTH_TAB_CELLS = { employerNI: "T1", employeeNI: "O1", incomeTax: "N1", studentLoan: "P1" };
204
+
205
+ // The Payslips sheet is the page an employer prints and hands over. F3 picks
206
+ // weekly or monthly payslips and F4 the period; H3 and H4 turn that pair into
207
+ // a month tab name and a block start row, and every printed figure is an
208
+ // INDIRECT through them.
209
+ export const PAYSLIP_PRINT_SHEET = "Payslips";
210
+ export const PAYSLIP_PRINT_CELLS = {
211
+ frequency: "F3",
212
+ period: "F4",
213
+ tab: "H3",
214
+ blockRow: "H4",
215
+ heading: "L7",
216
+ periodEnd: "I9",
217
+ periodNumber: "I10",
218
+ };
219
+ export const PAYSLIP_PRINT_MONTHLY_HEADING = "MONTHLY PAYROLL";
220
+
221
+ // The payroll number the writer gives the first employee, which is the number
222
+ // the page's own join adds to the block row to reach their line. The page
223
+ // prints the first employee's payslip, so this is the gate every figure below
224
+ // the heading passes through.
225
+ export const PAYSLIP_PRINT_FIRST_PAYROLL_NUMBER = 1;
226
+
227
+ // The printed figures for the period, and the same four accumulated from the
228
+ // payroll year's first month, each keyed by the payslip field it carries.
229
+ export const PAYSLIP_PRINT_PERIOD_CELLS = { G14: "grossPay", H14: "incomeTax", I14: "employeeNI", M14: "netPay" };
230
+ export const PAYSLIP_PRINT_TO_DATE_CELLS = { G16: "grossPay", H16: "incomeTax", I16: "employeeNI", M16: "netPay" };
231
+
232
+ // Nothing downstream reads the printed page, so the reconciliation asks it
233
+ // for a period other than the sheet's own default of 1 -- a join stuck on the
234
+ // default prints the wrong period with every other check still green.
235
+ export const PAYSLIP_PRINT_PERIOD = 2;
@@ -0,0 +1,111 @@
1
+ // SPDX-License-Identifier: AGPL-3.0-only
2
+ // Copyright (C) 2026 DIY Accounting Ltd
3
+ //
4
+ // period-shift.js — the whole-month, whole-year gap between the accounting
5
+ // period a scenario's dates sit in and the period a package covers, and the
6
+ // primitive that moves a date across it. Shared by every product whose
7
+ // writer dates postings onto a package generated for a year other than the
8
+ // scenario's own.
9
+
10
+ import { parseDate } from "./scenario-loader.js";
11
+
12
+ // Move a date forward by whole months. A day the shifted month does not have
13
+ // clamps to that month's end, so each of the period's twelve months lands on
14
+ // its own tab: a 31st shifted into a 30-day month stays in that month rather
15
+ // than rolling into the next one and doubling up with the month after it.
16
+ export function shiftMonths(d, monthOffset) {
17
+ const year = d.getUTCFullYear();
18
+ const month = d.getUTCMonth() + monthOffset;
19
+ const lastDayOfShiftedMonth = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
20
+ return new Date(Date.UTC(year, month, Math.min(d.getUTCDate(), lastDayOfShiftedMonth)));
21
+ }
22
+
23
+ // The year the scenario's own accounting period opens in, read off the
24
+ // earliest date its posting journals carry. A date outside the period is not
25
+ // a posting -- a charge registered years before it, a straddling VAT entry
26
+ // after it -- so only the four journals whose entries belong to the period
27
+ // are read. A scenario with no postings at all has no period to read.
28
+ export function postingPeriodStartYear(scenario, startMonth) {
29
+ let earliest = null;
30
+ for (const journal of ["sales", "purchases", "bank", "payroll"]) {
31
+ for (const entries of Object.values(scenario[journal] || {})) {
32
+ for (const entry of entries) {
33
+ const date = parseDate(entry.date);
34
+ if (earliest === null || date < earliest) earliest = date;
35
+ }
36
+ }
37
+ }
38
+ if (earliest === null) return null;
39
+ return earliest.getUTCFullYear() - (earliest.getUTCMonth() < startMonth ? 1 : 0);
40
+ }
41
+
42
+ /**
43
+ * The whole-month gap between the accounting period a scenario's dates sit in
44
+ * and the period a package covers, counting years as well as months. The
45
+ * package's period opens the day after its year-end month, eleven months
46
+ * back; the scenario states the month its own period opens in, and its year
47
+ * comes from the book that declared it or from the earliest date its journals
48
+ * post. A scenario already in the package's period has a zero gap and is
49
+ * written as it stands, which is what makes exporting a package and
50
+ * generating from the export reproduce the same cells.
51
+ *
52
+ * @param {Object} scenario
53
+ * @param {number} targetStartYear - the year the package's period opens in
54
+ * for every year end but December's, which generate.js still names as the
55
+ * year before the year end
56
+ * @param {number} yearEndMonth - 1-indexed month the package's year end falls in
57
+ * @returns {number} months to shift each of the scenario's dates by
58
+ */
59
+ export function periodShiftMonths(scenario, targetStartYear, yearEndMonth) {
60
+ const sourceStartMonth = (scenario.period_start_month || 4) - 1;
61
+ const sourceStartYear = scenario.period_start_year || postingPeriodStartYear(scenario, sourceStartMonth);
62
+ if (sourceStartYear === null) return 0;
63
+ if (!targetStartYear) {
64
+ throw new Error("cellWrites: a package needs the calendar year its accounting period opens in");
65
+ }
66
+ const targetStartIndex = (targetStartYear + 1) * 12 + (yearEndMonth - 1) - 11;
67
+ return targetStartIndex - (sourceStartYear * 12 + sourceStartMonth);
68
+ }
69
+
70
+ // The calendar month a book's own accounting period opens in, as a single
71
+ // monthly index (year*12 + zero-based month) so two periods' starts subtract
72
+ // straight into a whole-month gap, years included. documentInfo's own
73
+ // periodCoveredStart is authoritative when a book declares one; a book that
74
+ // does not falls back to the earliest date among its own lines, exactly as
75
+ // postingPeriodStartYear does for a scenario's journals.
76
+ function bookPeriodStartMonthIndex(book, lines) {
77
+ const declared = book?.documentInfo?.periodCoveredStart;
78
+ if (declared) {
79
+ const date = parseDate(declared);
80
+ return date.getUTCFullYear() * 12 + date.getUTCMonth();
81
+ }
82
+ let earliest = null;
83
+ for (const line of lines ?? []) {
84
+ if (line.postingDate === undefined) continue;
85
+ const date = parseDate(line.postingDate);
86
+ if (earliest === null || date < earliest) earliest = date;
87
+ }
88
+ if (earliest === null) return null;
89
+ return earliest.getUTCFullYear() * 12 + earliest.getUTCMonth();
90
+ }
91
+
92
+ /**
93
+ * The whole-month shift, years included, between the accounting period a
94
+ * fixture's own book declares and the period an export's book declares --
95
+ * read straight off the two book.tomls rather than passed as a flag, so a
96
+ * scorecard run needs no separate argument to know which frame the export's
97
+ * dates landed in.
98
+ * @param {Object} fixtureBook - the fixture's parsed book.toml
99
+ * @param {Array} fixtureLines - the fixture's parsed lines.jsonl, for a book
100
+ * that declares no period of its own
101
+ * @param {Object} exportBook - the export's parsed book.toml
102
+ * @param {Array} exportLines - the export's parsed lines.jsonl
103
+ * @returns {number} months to shift the fixture's dates by to land in the
104
+ * export's own period; 0 when either side's period cannot be read
105
+ */
106
+ export function bookPeriodShiftMonths(fixtureBook, fixtureLines, exportBook, exportLines) {
107
+ const fixtureStart = bookPeriodStartMonthIndex(fixtureBook, fixtureLines);
108
+ const exportStart = bookPeriodStartMonthIndex(exportBook, exportLines);
109
+ if (fixtureStart === null || exportStart === null) return 0;
110
+ return exportStart - fixtureStart;
111
+ }
@@ -0,0 +1,317 @@
1
+ // SPDX-License-Identifier: AGPL-3.0-only
2
+ // Copyright (C) 2026 DIY Accounting Ltd
3
+ //
4
+ // product-workbook.js — a book turned into its product's workbooks.
5
+ //
6
+ // The same steps the CLI runs to populate a package (app/bin/generate.js),
7
+ // with the filesystem behind an injectable resource loader: the default reads
8
+ // this repo's app/ directory, a browser supplies one backed by fetch. Nothing
9
+ // here recalculates; every workbook carries fullCalcOnLoad="1" so the
10
+ // spreadsheet app computes it on open. A multi-file package's link caches are
11
+ // filled from the calculator's own figures, so a workbook that reads a sibling
12
+ // shows the book's numbers before the app re-resolves the link.
13
+ //
14
+ // The product comes from the book itself, so one save path serves all four:
15
+ // a single-file product (Basic Sole Trader, Taxi Driver) writes one workbook,
16
+ // a multi-file product (Self Employed, Company) writes the whole set.
17
+
18
+ import JSZip from "jszip";
19
+ import { parse as parseTOML } from "smol-toml";
20
+
21
+ import { generateSpreadsheet, packageNaming, applyYearEndSequence, setFullCalcOnLoad } from "./generator.js";
22
+ import { taxYearFileName } from "./tax-year.js";
23
+ import { applyCellWrites } from "./spreadsheet-runner.js";
24
+ import { LINK_ORDER, refreshWorkbookLinkCaches, resultsReader } from "./link-caches.js";
25
+ import { calculateLinkCells } from "./diya-gl-calculator.js";
26
+ import { diyaGlToScenario } from "./diya-gl-loader.js";
27
+ import { nodeResourceLoader } from "./app-resources.js";
28
+ import { SCHEMA_PRODUCT_NAMES } from "./xlsx-exporter.js";
29
+ import * as bst from "../products/bst.js";
30
+ import * as taxi from "../products/taxi.js";
31
+ import * as se from "../products/se.js";
32
+ import * as ltd from "../products/ltd.js";
33
+
34
+ const SHARED_META = "templates/meta.toml";
35
+ const DOS_EPOCH = new Date(Date.UTC(1980, 0, 1));
36
+
37
+ const PRODUCT_MODULES = { bst, taxi, se, ltd };
38
+
39
+ const PRODUCT_BY_SCHEMA_NAME = Object.fromEntries(Object.entries(SCHEMA_PRODUCT_NAMES).map(([id, name]) => [name, id]));
40
+
41
+ /**
42
+ * A book that cannot be written into a workbook, naming the field at fault.
43
+ */
44
+ export class BookFieldError extends Error {
45
+ constructor(field, message) {
46
+ super(message);
47
+ this.name = "BookFieldError";
48
+ this.field = field;
49
+ }
50
+ }
51
+
52
+ function missingField(field, why) {
53
+ return new BookFieldError(field, `book has no ${field}, so ${why}`);
54
+ }
55
+
56
+ /**
57
+ * A product whose package is a set of workbooks, asked for as one workbook.
58
+ */
59
+ export class SingleFileOnlyError extends Error {
60
+ constructor(productName) {
61
+ super(`a ${productName} book saves as its package zip, not as one workbook`);
62
+ this.name = "SingleFileOnlyError";
63
+ this.productName = productName;
64
+ }
65
+ }
66
+
67
+ /**
68
+ * The product a book declares, under the short name the product map keys.
69
+ *
70
+ * @param {Object} book - parsed book.toml
71
+ * @returns {"bst"|"taxi"|"se"|"ltd"}
72
+ */
73
+ export function productOf(book) {
74
+ const declared = book?.entityInformation?.["diya-gl:product"];
75
+ if (!declared) {
76
+ throw missingField('entityInformation."diya-gl:product"', "the product to write it as is unknown");
77
+ }
78
+ const product = PRODUCT_BY_SCHEMA_NAME[declared];
79
+ if (!product) {
80
+ const known = Object.keys(PRODUCT_BY_SCHEMA_NAME).join(", ");
81
+ throw new Error(`book declares product "${declared}"; the products a workbook can be written for are ${known}`);
82
+ }
83
+ return product;
84
+ }
85
+
86
+ // Re-exported for product-workbook.js's own callers (books-engine.js,
87
+ // books-interchange.js, the workbook tests); its home is tax-year.js so
88
+ // diya-gl-loader.js can share it without importing this module.
89
+ export { taxYearFileName };
90
+
91
+ function periodCoveredEnd(book) {
92
+ const info = book?.documentInfo;
93
+ if (!info) throw missingField("documentInfo", "its accounting period is unknown");
94
+ if (!info.periodCoveredStart) {
95
+ throw missingField("documentInfo.periodCoveredStart", "its accounting period is unknown");
96
+ }
97
+ if (!info.periodCoveredEnd) {
98
+ throw missingField("documentInfo.periodCoveredEnd", "the tax year to generate for is unknown");
99
+ }
100
+ return new Date(info.periodCoveredEnd);
101
+ }
102
+
103
+ function isoDay(date) {
104
+ return date.toISOString().slice(0, 10);
105
+ }
106
+
107
+ // A company's package is twelve month tabs, a payroll calendar of twelve
108
+ // months and a year's rates, so a book covering anything else has no package
109
+ // to be written into. The refusal comes before the first template read: a
110
+ // half-written package is worse than none.
111
+ function refuseUnlessTwelveWholeMonths(book) {
112
+ const start = new Date(book.documentInfo.periodCoveredStart);
113
+ const end = new Date(book.documentInfo.periodCoveredEnd);
114
+ const twelfthMonthEnd = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth() + 12, 0));
115
+ if (start.getUTCDate() === 1 && end.getTime() === twelfthMonthEnd.getTime()) return;
116
+ throw new BookFieldError(
117
+ "documentInfo.periodCoveredEnd",
118
+ `book covers ${isoDay(start)} to ${isoDay(end)}, which is not the twelve whole months a company's accounts cover`,
119
+ );
120
+ }
121
+
122
+ /**
123
+ * The tax year data a book's own dates name, read through the resource loader.
124
+ * The calculator needs the same file the writer applies, so both take it from
125
+ * here rather than each resolving the year for itself.
126
+ *
127
+ * @param {Object} book - parsed book.toml
128
+ * @param {Object} [options]
129
+ * @param {Object} [options.resources] - resource loader; defaults to reading app/
130
+ * @param {string} [options.taxYearName] - override the tax year the book's dates imply
131
+ * @returns {Promise<Object>} the parsed app/data/<year>.toml
132
+ */
133
+ export async function loadTaxDataForBook(book, options = {}) {
134
+ const resources = options.resources || nodeResourceLoader();
135
+ const { taxRegime } = PRODUCT_MODULES[productOf(book)].PRODUCT;
136
+ const taxYearName = options.taxYearName || taxYearFileName(periodCoveredEnd(book), taxRegime);
137
+ return parseTOML(await resources.readText(`data/${taxYearName}.toml`));
138
+ }
139
+
140
+ /**
141
+ * Everything the writer derives before it touches a template: which product's
142
+ * templates to read, which year's data to apply, what the package is called,
143
+ * and which cells to write. Reading it all up front is what stops a book with
144
+ * a missing field producing a half-written package.
145
+ */
146
+ async function resolveInputs(book, lines, options) {
147
+ const resources = options.resources || nodeResourceLoader();
148
+
149
+ const product = productOf(book);
150
+ const productMod = PRODUCT_MODULES[product];
151
+ const bookPeriodEnd = periodCoveredEnd(book);
152
+ const templateDir = `templates/${productMod.PRODUCT.dir}`;
153
+
154
+ // A self-employment year always ends on 5 April, on the month tabs the
155
+ // templates already carry, and the tax file it belongs to declares that
156
+ // date. A company chooses its own year end, so its book's period is the
157
+ // year end: it names the package, sets the one date cell the Admin sheet
158
+ // computes the rest from, moves the month tabs and the links and the
159
+ // payroll periods, and shifts the scenario's dates onto them.
160
+ const yearEndFromBook = productMod.PRODUCT.taxRegime === "ltd";
161
+ if (yearEndFromBook) refuseUnlessTwelveWholeMonths(book);
162
+
163
+ const taxYearName = options.taxYearName || taxYearFileName(bookPeriodEnd, productMod.PRODUCT.taxRegime);
164
+ const taxFile = options.taxData || (await loadTaxDataForBook(book, { resources, taxYearName }));
165
+ const declaredYear = taxFile.tax_year || taxFile.financial_year;
166
+ if (!declaredYear) throw new Error(`${taxYearName}.toml declares neither tax_year nor financial_year`);
167
+
168
+ // The rates are the financial year's, the year end is this company's, and
169
+ // the generator reads both off the one object.
170
+ const endDate = yearEndFromBook ? bookPeriodEnd : new Date(declaredYear.end);
171
+ const yearInfo = yearEndFromBook ? { ...declaredYear, end: endDate } : declaredYear;
172
+ const taxData = yearEndFromBook ? { ...taxFile, financial_year: yearInfo } : taxFile;
173
+ const yearEndMonth = yearEndFromBook ? endDate.getUTCMonth() + 1 : 0;
174
+
175
+ const productMeta = parseTOML(await resources.readText(`${templateDir}/meta.toml`));
176
+ const sharedMeta = parseTOML(await resources.readText(SHARED_META));
177
+ const { dirName, xlsxFilename } = packageNaming(productMeta, sharedMeta, endDate);
178
+
179
+ const scenario = diyaGlToScenario(book, lines, product);
180
+ const multiFile = Boolean(productMod.MULTI_FILE);
181
+ // The tax year the writes are dated into: the year a statutory year opened
182
+ // in, and for a company the year before the one its year end falls in, which
183
+ // is what cellWrites turns into the payroll year the package opens with and
184
+ // what generate.js takes off the package directory's own year-end date.
185
+ // A single-file product's own book period is already the grid its dates
186
+ // are written onto, so its writer takes no target year at all -- passing
187
+ // one through would shift its dates by whatever the loaded tax file's
188
+ // year happens to disagree with the scenario's own dates by.
189
+ const targetStartYear = yearEndFromBook ? endDate.getUTCFullYear() - 1 : new Date(yearInfo.start).getUTCFullYear();
190
+ const writes = productMod.cellWrites(scenario, multiFile ? targetStartYear : undefined, yearEndMonth);
191
+
192
+ const templateFiles = productMeta.template.files || [productMeta.template.spreadsheet];
193
+
194
+ return {
195
+ resources,
196
+ product,
197
+ templateDir,
198
+ templateFiles,
199
+ multiFile,
200
+ taxData,
201
+ yearInfo,
202
+ endDate,
203
+ yearEndMonth,
204
+ productMeta,
205
+ dirName,
206
+ xlsxFilename,
207
+ scenario,
208
+ writes,
209
+ };
210
+ }
211
+
212
+ // One workbook of a package: the template with the year's rates in it, moved
213
+ // to the year end being written for, carrying the book's own figures. A file
214
+ // that is not a workbook (the Company package's dividend voucher) is copied.
215
+ async function composeFile(inputs, templateFile) {
216
+ const { resources, templateDir, multiFile, taxData, yearInfo, endDate, yearEndMonth, productMeta, writes } = inputs;
217
+ const fileKey = templateFile.replace(".xlsx", "").replace(".docx", "").toLowerCase();
218
+ const sheetsConfig = multiFile ? productMeta.sheets?.[fileKey] : productMeta.sheets;
219
+ const fileWrites = multiFile ? writes[templateFile] : writes;
220
+
221
+ let buffer = await resources.readBinary(`${templateDir}/${templateFile}`);
222
+ if (sheetsConfig && Object.keys(sheetsConfig).length > 0) {
223
+ buffer = await generateSpreadsheet(buffer, taxData, sheetsConfig);
224
+ }
225
+ if (!templateFile.endsWith(".xlsx")) return buffer;
226
+
227
+ buffer = await applyYearEndSequence(buffer, templateFile, sheetsConfig, yearEndMonth, endDate, yearInfo);
228
+ if (fileWrites) buffer = await applyCellWrites(buffer, fileWrites);
229
+ return setFullCalcOnLoad(buffer);
230
+ }
231
+
232
+ // Every workbook of the package, then every link-bearing one with its caches
233
+ // refreshed from the calculator. The calculator holds every figure before the
234
+ // first refresh, so the order is the declared one and nothing else.
235
+ async function composeFiles(inputs, book, lines) {
236
+ const files = [];
237
+ for (const templateFile of inputs.templateFiles) {
238
+ files.push({ name: templateFile, bytes: await composeFile(inputs, templateFile) });
239
+ }
240
+
241
+ const linkOrder = LINK_ORDER[inputs.product];
242
+ if (!linkOrder) return files;
243
+
244
+ const reader = resultsReader(calculateLinkCells(book, lines, inputs.product, inputs.taxData, inputs.scenario));
245
+ for (const name of linkOrder) {
246
+ const file = files.find((entry) => entry.name === name);
247
+ if (!file) throw new Error(`${name} is in LINK_ORDER.${inputs.product} but not among the ${inputs.product} template files`);
248
+ file.bytes = (await refreshWorkbookLinkCaches(file.bytes, reader)).bytes;
249
+ }
250
+ return files;
251
+ }
252
+
253
+ /**
254
+ * A book as the workbooks a spreadsheet app opens: one file for Basic Sole
255
+ * Trader and Taxi Driver, the whole set for Self Employed and Company.
256
+ *
257
+ * @param {Object} book - parsed book.toml
258
+ * @param {Array} lines - parsed lines.jsonl entries
259
+ * @param {Object} [options]
260
+ * @param {Object} [options.resources] - resource loader; defaults to reading app/
261
+ * @param {string} [options.taxYearName] - override the tax year the book's dates imply
262
+ * @param {Object} [options.taxData] - already-parsed tax data, skipping the load
263
+ * @returns {Promise<{ product: string, dirName: string, files: Array<{name: string, bytes: Uint8Array}> }>}
264
+ */
265
+ export async function saveWorkbookFiles(book, lines, options = {}) {
266
+ const inputs = await resolveInputs(book, lines, options);
267
+
268
+ const files = (await composeFiles(inputs, book, lines)).map(({ name, bytes }) => ({
269
+ name: inputs.multiFile ? name : inputs.xlsxFilename,
270
+ bytes,
271
+ }));
272
+
273
+ return { product: inputs.product, dirName: inputs.dirName, files };
274
+ }
275
+
276
+ /**
277
+ * A single-file product's book as the one workbook it writes.
278
+ *
279
+ * @returns {Promise<{ workbook: Uint8Array, filename: string }>}
280
+ */
281
+ export async function saveWorkbook(book, lines, options = {}) {
282
+ const inputs = await resolveInputs(book, lines, options);
283
+ if (inputs.multiFile) throw new SingleFileOnlyError(inputs.productMeta.product.name);
284
+
285
+ const workbook = await composeFile(inputs, inputs.templateFiles[0]);
286
+ return { workbook, filename: inputs.xlsxFilename };
287
+ }
288
+
289
+ /**
290
+ * The workbooks wrapped as the package zip the download page serves: a single
291
+ * workbook at the zip root under the package's own name, or the whole set in a
292
+ * directory named for the package. The shipped package also carries the PDF
293
+ * guides, which need a PDF renderer and so stay with the CLI.
294
+ *
295
+ * @returns {Promise<{ zip: Uint8Array, filename: string }>}
296
+ */
297
+ export async function savePackageZip(book, lines, options = {}) {
298
+ const inputs = await resolveInputs(book, lines, options);
299
+
300
+ const zip = new JSZip();
301
+ for (const { name, bytes } of await composeFiles(inputs, book, lines)) {
302
+ zip.file(inputs.multiFile ? `${inputs.dirName}/${name}` : inputs.xlsxFilename, bytes, { date: DOS_EPOCH });
303
+ }
304
+ // The package directory is an entry of its own, which JSZip dates with the
305
+ // time of the run; the zip is the same bytes every time without that.
306
+ for (const entry of Object.values(zip.files)) {
307
+ if (entry.dir) entry.date = DOS_EPOCH;
308
+ }
309
+
310
+ const buffer = await zip.generateAsync({
311
+ type: "uint8array",
312
+ compression: "DEFLATE",
313
+ compressionOptions: { level: 6 },
314
+ });
315
+
316
+ return { zip: buffer, filename: `${inputs.dirName}.zip` };
317
+ }