@diy-accounting-uk/diya-gl 1.2.40 → 1.2.42

package/README.md

@@ -37,11 +37,12 @@ docker run --rm -v "$PWD":/data ghcr.io/diy-accounting-uk/diya-gl:latest \
 diya-gl recalc --package bst --data my-book --years se-2025-2026 --output-dir out
 diya-gl read-workbook --file my-workbook.xlsx --output-dir out
 diya-gl write-workbook --data my-book --output-dir out
+diya-gl link my-book
 diya-gl mcp
 ```
 
 Each subcommand is also its own command, if you only want one on your `PATH`:
-`diya-gl-recalc`, `diya-gl-read-workbook`, `diya-gl-write-workbook`, `diya-gl-mcp`.
+`diya-gl-recalc`, `diya-gl-read-workbook`, `diya-gl-write-workbook`, `diya-gl-link`, `diya-gl-mcp`.
 
 - **recalc** takes a diya-gl book (`--data`) or a populated workbook (`--source-dir`,
   `--mode saved|recalculate`) and writes `report.json`: every figure, report section and
@@ -51,6 +52,11 @@ Each subcommand is also its own command, if you only want one on your `PATH`:
 - **write-workbook** takes a diya-gl book (`--data` or `--file`) and writes the Excel
   package its product composes onto its template — the same client-side path the DIYA-GL
   pages use, so it never needs LibreOffice. Add `--zip` for the package as one zip.
+- **link** takes a book (a directory with `book.toml` and `lines.jsonl`, a diya-gl zip or a
+  diya-gl JSON file) and prints the `https://diya-gl.co.uk/<product>.html#book=<data>` link that
+  opens it, the whole book carried in the fragment so nothing is uploaded. `--base <url>`
+  replaces the origin. The fragment length goes to stderr, with a warning past 64 KB (about
+  2,000 lines), where chat, email and QR codes start to cut links off.
 - **mcp** runs a stdio [MCP](https://modelcontextprotocol.io) server with four tools:
   `extract_book`, `report`, `edit_lines`, `save_workbook`. Point an MCP client at
   `diya-gl-mcp` (or `diya-gl mcp`) with no arguments.

package/bin/diya-gl-link.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// diya-gl-link.js — print the diya-gl.co.uk link that opens a whole book,
+// the book carried in the URL fragment.
+
+import { runDistBin } from "./run-dist-bin.js";
+runDistBin("app/bin/link.js", process.argv.slice(2));

package/bin/diya-gl.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2006-2026 DIY Accounting Limited
 //
-// diya-gl.js — the dispatcher: diya-gl <recalc|read-workbook|write-workbook|mcp> [args].
+// diya-gl.js — the dispatcher: diya-gl <recalc|read-workbook|write-workbook|link|mcp> [args].
 // Each subcommand is also its own bin (diya-gl-recalc, and so on), for a
 // caller that wants one command on its PATH without the others.
 
@@ -16,6 +16,7 @@ const SUBCOMMANDS = {
   "recalc": "app/bin/report.js",
   "read-workbook": "app/bin/export.js",
   "write-workbook": "app/bin/write-workbook.js",
+  "link": "app/bin/link.js",
   "mcp": "app/bin/diya-gl-mcp.js",
 };
 

package/dist/app/bin/export.js

@@ -132,10 +132,16 @@ function parseArgs(argv) {
 // buildReportDocument -- the same loop report.js's --data mode runs, so the
 // CLI's --file mode, report.js and the MCP server's tools never diverge on
 // how R is built from the same D. Pure: no disk access, no console output.
-export function buildFileReportDocument(book, lines, packageName, productMod) {
+//
+// attribute asks for each attributed figure's entryNumbers. A year's book
+// lists every line under each total it reaches, which multiplies R's size
+// many times over, so the written report.json leaves them out and a caller
+// that drills from a figure to its lines asks for them.
+export function buildFileReportDocument(book, lines, packageName, productMod, { attribute = false } = {}) {
   const taxData = extractTaxDataFromBook(book, packageName);
   const scenario = diyaGlToScenario(book, lines, packageName);
-  const results = calculateFromDiyaGl(book, lines, packageName, taxData, scenario);
+  const attribution = attribute ? {} : undefined;
+  const results = calculateFromDiyaGl(book, lines, packageName, taxData, scenario, { attribution });
   const mergedScenario = { ...scenario, ...scenario.expected };
   const periodEnd = book.documentInfo?.periodCoveredEnd;
   const yearEnd = periodEnd ? new Date(periodEnd).toISOString().slice(0, 10) : null;
@@ -147,6 +153,7 @@ export function buildFileReportDocument(book, lines, packageName, productMod) {
     packageName,
     engine: "js",
     results,
+    attribution,
     productMod,
     scenario: mergedScenario,
     taxData,

package/dist/app/bin/link.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// link.js — print the diya-gl.co.uk link that opens a whole book, the book
+// carried in the URL fragment.
+//
+// Usage:
+//   node app/bin/link.js examples/basic-taxi-driver
+//   node app/bin/link.js my-book-diya-gl.zip
+//   node app/bin/link.js my-book.json --base http://localhost:8080
+//
+// The book is a directory holding book.toml and lines.jsonl, or any diya-gl
+// zip or JSON file diya-gl-interchange.js reads. The link goes to stdout;
+// its length and any warning go to stderr.
+
+import { existsSync, readFileSync, statSync } from "fs";
+import { join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { parseDiyaGlData } from "../lib/diya-gl-loader.js";
+import { readBookSource } from "../lib/diya-gl-interchange.js";
+import { canonicalBookToml, canonicalLinesJsonl } from "../lib/diya-gl-canonical.js";
+import { productIdOf } from "../lib/xlsx-exporter.js";
+import { PRODUCTS } from "../lib/products.js";
+import { encodeBookFragment, FRAGMENT_KEY } from "../lib/diya-gl-link.js";
+
+const DEFAULT_BASE = "https://diya-gl.co.uk";
+const USAGE = "Usage: node app/bin/link.js <book directory | diya-gl zip | diya-gl JSON file> [--base <url>]";
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let base = DEFAULT_BASE;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--base") {
+      base = args[++i];
+      if (!base) throw new Error(`--base needs a URL. ${USAGE}`);
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  if (positional.length !== 1) throw new Error(USAGE);
+  return { source: positional[0], base: base.replace(/\/+$/, "") };
+}
+
+async function readBookText(source) {
+  const path = resolve(source);
+  if (!existsSync(path)) throw new Error(`${source} does not exist.`);
+  if (statSync(path).isDirectory()) {
+    const toml = readFileSync(join(path, "book.toml"), "utf8");
+    const lines = readFileSync(join(path, "lines.jsonl"), "utf8");
+    return { toml, lines, book: parseDiyaGlData(toml, lines).book };
+  }
+  const { book, lines } = await readBookSource(readFileSync(path), source, { products: PRODUCTS });
+  return { toml: canonicalBookToml(book), lines: canonicalLinesJsonl(lines), book };
+}
+
+export async function bookLink(source, base = DEFAULT_BASE) {
+  const { toml, lines, book } = await readBookText(source);
+  const declared = book.entityInformation && book.entityInformation["diya-gl:product"];
+  const product = productIdOf(declared);
+  if (!product)
+    throw new Error(`The book declares no product with a page: entityInformation."diya-gl:product" is ${JSON.stringify(declared)}.`);
+  const { fragment, length, warning } = encodeBookFragment({ toml, lines });
+  return { url: `${base}/${product}.html#${FRAGMENT_KEY}=${fragment}`, length, warning };
+}
+
+async function main() {
+  const { source, base } = parseArgs(process.argv);
+  const { url, length, warning } = await bookLink(source, base);
+  console.log(url);
+  console.error(`Fragment length: ${length} characters`);
+  if (warning) console.error(`Warning: ${warning}`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}

package/dist/app/bin/report.js

@@ -13,6 +13,8 @@
 //   --mode saved       (default) Read xlsx cell values as-is from XML. No LibreOffice needed.
 //   --mode recalculate Run xls roundtrip first, then read. Requires LibreOffice.
 //   --data <dir>       Compute reports from diya-gl data via JS engine. No Excel needed.
+//   --entry-numbers    With --data, give each attributed figure in report.json the
+//                      entryNumbers of the ledger lines behind it.
 //
 // Either mode writes report.json beside the markdown: R, the canonical
 // document verify-roundtrip.js scores. --data also writes its own input to
@@ -65,6 +67,7 @@ function parseArgs(argv) {
   const offset = getArg("--offset");
   const years = getArg("--years");
   const yearEndArg = getArg("--year-end");
+  const entryNumbers = args.includes("--entry-numbers");
 
   if (!packageName) {
     console.error("Error: --package is required (bst, taxi, se, ltd)");
@@ -79,7 +82,7 @@ function parseArgs(argv) {
     process.exit(1);
   }
 
-  return { packageName, sourceDir, outputDir, mode, dataDir, offset, years, yearEndArg };
+  return { packageName, sourceDir, outputDir, mode, dataDir, offset, years, yearEndArg, entryNumbers };
 }
 
 // R, the canonical report document, beside the markdown. Both engines write
@@ -92,7 +95,7 @@ function writeReportJson(outputDir, options) {
 }
 
 async function main() {
-  const { packageName, sourceDir, outputDir, mode, dataDir, offset, years, yearEndArg } = parseArgs(process.argv);
+  const { packageName, sourceDir, outputDir, mode, dataDir, offset, years, yearEndArg, entryNumbers } = parseArgs(process.argv);
 
   const productMod = PRODUCTS[packageName];
   if (!productMod) {
@@ -129,7 +132,8 @@ async function main() {
     // on the Excel side: opening balances, stock, debtors, creditors and
     // business details. Passing it through lights those up on the JS side too.
     const scenario = diyaGlToScenario(book, lines, packageName);
-    const results = calculateFromDiyaGl(book, lines, packageName, taxData, scenario);
+    const attribution = entryNumbers ? {} : undefined;
+    const results = calculateFromDiyaGl(book, lines, packageName, taxData, scenario, { attribution });
 
     // Fixture anchors (opening_debtors, closing_creditors, ...) are top-level
     // scenario tables, not [expected] keys, so checks that anchor against
@@ -156,6 +160,7 @@ async function main() {
       packageName,
       engine: "js",
       results,
+      attribution,
       productMod,
       scenario: mergedScenario,
       taxData,

package/dist/app/data/releases.json

@@ -1273,6 +1273,58 @@
           "scorecard": "101605 passed, 0 warnings, 0 failed"
         }
       }
+    },
+    {
+      "tag": "diya-gl-v1.2.40",
+      "date": "2026-09-30",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.40+57de8f55b",
+      "taxDataHash": "89424bd36c0d",
+      "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
+      "templates": {
+        "bst": {
+          "hash": "0d003e10e00c",
+          "scorecard": "812 passed, 0 warnings, 0 failed"
+        },
+        "taxi": {
+          "hash": "1ff69654d64d",
+          "scorecard": "700 passed, 0 warnings, 0 failed"
+        },
+        "se": {
+          "hash": "064605ae76ed",
+          "scorecard": "8014 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "5bb7be9b6d97",
+          "scorecard": "101605 passed, 0 warnings, 0 failed"
+        }
+      }
+    },
+    {
+      "tag": "diya-gl-v1.2.41",
+      "date": "2026-10-01",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.40+57de8f55b",
+      "taxDataHash": "89424bd36c0d",
+      "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
+      "templates": {
+        "bst": {
+          "hash": "0d003e10e00c",
+          "scorecard": "812 passed, 0 warnings, 0 failed"
+        },
+        "taxi": {
+          "hash": "1ff69654d64d",
+          "scorecard": "700 passed, 0 warnings, 0 failed"
+        },
+        "se": {
+          "hash": "064605ae76ed",
+          "scorecard": "8014 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "5bb7be9b6d97",
+          "scorecard": "101605 passed, 0 warnings, 0 failed"
+        }
+      }
     }
   ]
 }

package/dist/app/lib/book-checks/taxi.js

@@ -212,4 +212,10 @@ export const TAXI_BOOK_HELPERS = {
   },
 };
 
-export const TAXI_PRODUCT_RULES = { checks: [], warnings: TAXI_WARNINGS, sharedOffenders: {}, bookHelpers: TAXI_BOOK_HELPERS };
+export const TAXI_PRODUCT_RULES = {
+  checks: [],
+  warnings: TAXI_WARNINGS,
+  sharedOffenders: {},
+  omittedSharedWarnings: ["book-missing-document-reference"],
+  bookHelpers: TAXI_BOOK_HELPERS,
+};

package/dist/app/lib/book-checks.js

@@ -407,6 +407,26 @@ function emptyDetailWarning(ctx) {
   };
 }
 
+function missingDocumentReferenceWarning(ctx) {
+  const offenders = ctx.lines
+    .filter(function (line) {
+      return line.sourceJournalID === "sales" && (!line.documentReference || !String(line.documentReference).trim());
+    })
+    .sort(byEntryNumber);
+  const warn = offenders.length > 0;
+  return {
+    id: "book-missing-document-reference",
+    tier: "warning",
+    label: "Every sale names its invoice or receipt",
+    result: warn ? "warn" : "pass",
+    actual: offenders.length,
+    consequence: warn
+      ? "A sale with no invoice or receipt reference cannot be matched to its document when the books are reviewed later."
+      : null,
+    offenders: offenders.map(offenderOf),
+  };
+}
+
 function negativeAmountWarning(ctx) {
   const offenders = ctx.lines
     .filter(function (line) {
@@ -469,14 +489,20 @@ function runWarnings(ctx, taxData, results) {
     vatWarning(ctx, taxData),
     duplicateEntriesWarning(ctx),
     emptyDetailWarning(ctx),
+    missingDocumentReferenceWarning(ctx),
     negativeAmountWarning(ctx),
     emptyMonthWarning(ctx),
-  ].map(function (warning) {
-    // A product whose sheets measure a shared warning differently replaces
-    // the whole result, keeping its id; every other product keeps this one.
-    const readDifferently = (ctx.productRules.sharedWarnings || {})[warning.id];
-    return readDifferently ? readDifferently(ctx, taxData, warning) : warning;
-  });
+  ]
+    .filter(function (warning) {
+      // A product whose sales carry no document leaves that shared warning out.
+      return !(ctx.productRules.omittedSharedWarnings || []).includes(warning.id);
+    })
+    .map(function (warning) {
+      // A product whose sheets measure a shared warning differently replaces
+      // the whole result, keeping its id; every other product keeps this one.
+      const readDifferently = (ctx.productRules.sharedWarnings || {})[warning.id];
+      return readDifferently ? readDifferently(ctx, taxData, warning) : warning;
+    });
   return shared.concat(
     ctx.productRules.warnings.map(function (warning) {
       return warning(ctx, taxData, results);

package/dist/app/lib/calculators/bst.js

@@ -13,6 +13,7 @@ import { calculateIncomeTax } from "../tax/income-tax.js";
 import { calculateNIClass4 } from "../tax/national-insurance.js";
 import { calculateMileageAllowance, scenarioBusinessMiles } from "../tax/mileage.js";
 import { aggregateByCode } from "./shared.js";
+import { attributionWriter, entriesOf } from "../entry-attribution.js";
 
 const BST_MONTH_COLS = {
   apr: "D",
@@ -78,7 +79,15 @@ function outstandingTotal(transactions) {
   return (transactions || []).reduce((sum, tx) => (tx.payment || tx.mileage ? sum : sum + (tx.amount || 0)), 0);
 }
 
-export function calculateBstResults(book, lines, taxData, scenario) {
+/**
+ * @param {Object} book - parsed book.toml
+ * @param {Array} lines - parsed lines.jsonl entries
+ * @param {Object} taxData
+ * @param {Object} scenario
+ * @param {Object} [attribution] - filled in place with the entryNumbers behind each cell (entry-attribution.js)
+ * @returns {Object} { "SheetName": { "CellRef": value } }
+ */
+export function calculateBstResults(book, lines, taxData, scenario, attribution) {
   // A book's own declared chart can number its purchase accounts under a
   // scheme other than the Basic Sole Trader master's own (see
   // resolveBstPurchaseCodeMap in diya-gl-loader.js); this must resolve to
@@ -105,7 +114,8 @@ export function calculateBstResults(book, lines, taxData, scenario) {
   // nothing, and cellWrites gives the sheet its miles rather than its amount
   // so the sheet can price the claim at its own Admin rates.
   const cashPurchaseLines = purchaseLines.filter((l) => !carriesBusinessMiles(l));
-  const byCode = aggregateByCode(cashPurchaseLines, purchaseCodeMap);
+  const purchaseEntries = {};
+  const byCode = aggregateByCode(cashPurchaseLines, purchaseCodeMap, purchaseEntries);
 
   // The mileage claim the sheet makes of those miles. It reaches Motor
   // Expenses (verified against the template: PurchasesApr!G4 bands the running
@@ -377,5 +387,107 @@ export function calculateBstResults(book, lines, taxData, scenario) {
   results.PurchasesMar.C1 = businessMiles;
   results.PurchasesMar.A1 = Math.round(mileageAllowance * 100) / 100;
 
+  if (attribution) attributeBstResults(attribution, { results, scenario, salesLines, purchaseEntries, assetAdditions });
   return results;
 }
+
+// The scenario transactions a mileage figure is read from: every one that
+// records business miles, the same set scenarioBusinessMiles() sums.
+function mileageTransactions(scenario) {
+  const transactions = [];
+  for (const table of [scenario.sales, scenario.purchases]) {
+    for (const monthTransactions of Object.values(table || {})) {
+      for (const tx of monthTransactions) if (typeof tx.mileage === "number") transactions.push(tx);
+    }
+  }
+  return transactions;
+}
+
+// The entries behind each cell calculateBstResults() writes, cell for cell
+// beside the arithmetic above: a line-fed cell takes its own lines, and a
+// derived cell the union of the cells it is computed from.
+function attributeBstResults(attribution, { results, scenario, salesLines, purchaseEntries, assetAdditions }) {
+  const a = attributionWriter(attribution);
+  const PL = "Profit & Loss Acc";
+  const code = (letter) => purchaseEntries[letter];
+  const mileage = entriesOf(mileageTransactions(scenario));
+  const assets = entriesOf(assetAdditions);
+
+  for (const sheet of ["Admin", "Business Details", "PurchasesStock"]) {
+    for (const cell of Object.keys(results[sheet])) a.set(sheet, cell);
+  }
+
+  a.set(PL, "C4", salesLines);
+  for (const month of MONTH_ORDER) {
+    a.set(
+      PL,
+      `${BST_MONTH_COLS[month]}4`,
+      salesLines.filter((line) => getMonthKey(line.postingDate) === month),
+    );
+  }
+  a.set(PL, "C6", code("s"));
+  a.set(PL, "C7", code("d"));
+  a.set(PL, "C9", a.cells(PL, "C4", "C6", "C7"));
+  const expenseCells = { C11: "e", C12: "p", C13: "r", C14: "g", C16: "t", C17: "a", C18: "l", C19: "b", C20: "i", C21: "o" };
+  for (const [cell, letter] of Object.entries(expenseCells)) a.set(PL, cell, code(letter));
+  a.set(PL, "C15", code("m"), mileage);
+  a.set(PL, "C22", a.cells(PL, "C11", "C12", "C13", "C14", "C15", "C16", "C17", "C18", "C19", "C20", "C21"));
+  a.set(PL, "C24", a.cells(PL, "C9", "C22"));
+
+  for (const cell of Object.keys(results["Fixed Assets"])) a.set("Fixed Assets", cell, assets);
+  a.set("PurchasesMar", "X1", assets);
+  a.set("PurchasesMar", "C1", mileage);
+  a.set("PurchasesMar", "A1", mileage);
+
+  const SE = "SE Short";
+  for (const cell of ["D80", "O80", "D85", "O85"]) a.set(SE, cell, assets);
+  a.set(PL, "C26", assets);
+  a.set(PL, "C28", a.cells(PL, "C24", "C26"));
+  a.set(PL, "C30");
+
+  a.set(SE, "D38", a.get(PL, "C4"));
+  if (results[SE].D46 !== undefined) {
+    a.set(SE, "D46", a.cells(PL, "C6", "C7"));
+    a.set(SE, "D51", a.cells(PL, "C15", "C16"));
+    a.set(SE, "D55", a.get(PL, "C11"));
+    a.set(SE, "D60", a.get(PL, "C12"));
+    a.set(SE, "D64", a.get(PL, "C13"));
+  }
+  a.set(SE, "D71", a.cells(PL, "C4", "C6", "C7", "C22"));
+  a.set(SE, "O71", a.get(SE, "D71"));
+  a.set(SE, "D94");
+  a.set(SE, "O94");
+  a.set(SE, "D99", a.cells(SE, "D71", "O71", "D80", "D85", "O80", "O85"));
+  a.set(SE, "O99", a.get(PL, "C30"));
+  a.set(SE, "D106", a.cells(SE, "D99", "O99"));
+
+  const IT = "Income Tax";
+  const profit = a.get(SE, "D106");
+  for (const cell of ["E5", "E6", "E7", "E8", "E9", "E10", "E11", "E15", "E16"]) a.set(IT, cell, profit);
+  for (const cell of ["D8", "C9", "D9", "C10", "D10"]) a.set(IT, cell);
+  a.set(
+    IT,
+    "E12",
+    salesLines.filter((line) => line[CIS_DEDUCTION_FIELD]),
+  );
+  a.set(IT, "E18", a.cells(IT, "E11", "E12", "E15", "E16"));
+  a.set(PL, "C32", a.cells(IT, "E11", "E12"));
+  a.set(PL, "C33", a.cells(IT, "E15", "E16"));
+  a.set(PL, "C35", a.cells(PL, "C28", "C30", "C32", "C33"));
+
+  // Debtors & Creditors: each month row is the month's transactions with
+  // nothing recorded in the payment column, the same rows outstandingTotal()
+  // sums; the column totals add the opening figure the book states.
+  const outstanding = (transactions) => (transactions || []).filter((tx) => !(tx.payment || tx.mileage));
+  const DC = "Debtors & Creditors";
+  a.set(DC, "C3");
+  a.set(DC, "F3");
+  MONTH_ORDER.forEach((month, index) => {
+    const row = 5 + index * 2;
+    a.set(DC, `C${row}`, entriesOf(outstanding(scenario.sales?.[month])));
+    a.set(DC, `F${row}`, entriesOf(outstanding(scenario.purchases?.[month])));
+  });
+  const rows = MONTH_ORDER.map((_, index) => 5 + index * 2);
+  a.set(DC, "C29", a.cells(DC, "C3", ...rows.map((row) => `C${row}`)));
+  a.set(DC, "F29", a.cells(DC, "F3", ...rows.map((row) => `F${row}`)));
+}