@diy-accounting-uk/diya-gl 1.2.44 → 1.2.46

package/README.md

@@ -67,9 +67,12 @@ Each subcommand is also its own command, if you only want one on your `PATH`:
   another site. The book stays in the browser (the part of the address after `#` is never sent
   anywhere). The server stays up until Ctrl-C. The workbook templates come from
   spreadsheets.diyaccounting.co.uk the first time a page action needs one.
-- **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.
+- **mcp** runs a stdio [MCP](https://modelcontextprotocol.io) server with eight tools:
+  `extract_book`, `report`, `edit_lines`, `save_workbook`, and four that read every detail of
+  the loaded book: `lines` (filter and group every transaction, e.g. best customer or spend on
+  fuel in June), `chart` (the accounts and the report rows each feeds), `book` (the business,
+  period, tax settings and registers) and `checks` (every book check with the entryNumbers
+  behind it). Point an MCP client at `diya-gl-mcp` (or `diya-gl mcp`) with no arguments.
 
 ## API
 

package/bin/diya-gl-mcp.js

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2006-2026 DIY Accounting Limited
 //
-// diya-gl-mcp.js — the stdio MCP server, four tools over a loaded diya-gl
-// book: extract_book, report, edit_lines, save_workbook. See
+// diya-gl-mcp.js — the stdio MCP server over a loaded diya-gl book:
+// extract_book, report, edit_lines, save_workbook, lines, chart, book and
+// checks. See
 // app/lib/mcp/server.js in the source repository for the method table.
 
 import { runDistBin } from "./run-dist-bin.js";

package/dist/app/bin/diya-gl-mcp.js

@@ -3,7 +3,8 @@
 // Copyright (C) 2006-2026 DIY Accounting Limited
 //
 // diya-gl-mcp.js — a stdio MCP server exposing the diya-gl pipeline as
-// four tools: extract_book, report, edit_lines, save_workbook, over any of
+// tools: extract_book, report, edit_lines, save_workbook, lines, chart,
+// book and checks, over any of
 // the four products (Basic Sole Trader, Taxi Driver, Self Employed, Company).
 //
 // Transport: hand-rolled newline-delimited JSON-RPC 2.0

package/dist/app/data/releases.json

@@ -1304,7 +1304,7 @@
       "tag": "diya-gl-v1.2.41",
       "date": "2026-10-01",
       "formatVersion": "diya-gl/1",
-      "engineVersion": "1.2.40+57de8f55b",
+      "engineVersion": "1.2.41+5b1fc93c5",
       "taxDataHash": "89424bd36c0d",
       "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
       "templates": {
@@ -1330,7 +1330,7 @@
       "tag": "diya-gl-v1.2.42",
       "date": "2026-10-03",
       "formatVersion": "diya-gl/1",
-      "engineVersion": "1.2.40+57de8f55b",
+      "engineVersion": "1.2.42+ed6c7809b",
       "taxDataHash": "89424bd36c0d",
       "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
       "templates": {
@@ -1356,7 +1356,59 @@
       "tag": "diya-gl-v1.2.43",
       "date": "2026-10-03",
       "formatVersion": "diya-gl/1",
-      "engineVersion": "1.2.40+57de8f55b",
+      "engineVersion": "1.2.43+971ca45ad",
+      "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.44",
+      "date": "2026-10-03",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.44+4b8f90020",
+      "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.45",
+      "date": "2026-10-04",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.45+3801b0c2",
       "taxDataHash": "89424bd36c0d",
       "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
       "templates": {

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

@@ -15,7 +15,7 @@
 
 import { changeLinePostingDate } from "../diya-gl-edits.js";
 import { LTD_PURCHASE_CODE_MAP, LTD_SALES_CODE_MAP } from "../scenario-extractor.js";
-import { BANK_ACCOUNT_FILES, BANK_TRANSFER_CODES, bankLayout } from "../ltd-layout.js";
+import { BANK_ACCOUNT_FILES, BANK_TRANSFER_CODES, ltdBankPlacement } from "../ltd-layout.js";
 
 // The bank account each transfer letter names: Currentaccount is BB, so a
 // BB-coded line on any other workbook is a transfer to or from the current
@@ -161,13 +161,11 @@ export const LTD_CHECK_SPECS = [
         const fileName = bankFileOf(line);
         if (!fileName) return true;
         if (line.debitCreditCode !== "D" && line.debitCreditCode !== "C") return false;
-        const layout = bankLayout(fileName);
-        const analysed = line.debitCreditCode === "D" ? layout.receiptCodes : layout.paymentCodes;
-        return !analysed.includes(line["diya-gl:bankCode"]);
+        return !ltdBankPlacement(fileName, line.debitCreditCode === "D", line["diya-gl:bankCode"], line.amount).analysed;
       });
     },
     consequence: function () {
-      return "Each bank workbook analyses its own list of codes, and the four workbooks do not share one list -- the cash book has no receipt column for RV, RC or X. An entry coded outside its workbook's list has no column to land in, and the package cannot be written at all.";
+      return "Each bank workbook analyses its own list of codes, and the four workbooks do not share one list -- the cash book has no receipt column for RV, RC or X. A refund coded DR on a payment or CR on a receipt lands in the opposite block as a negative entry under its own code. Any other entry coded outside its workbook's list has no column to land in, and the package cannot be written at all.";
     },
     buildHelper: null,
     apply: null,

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

@@ -684,9 +684,13 @@ function bankEntries(lines, bankCode, side) {
 // straddling invoice is returned on a VAT period outside that year and is
 // banked in a book this one does not hold, so it neither needs a settlement
 // of its own nor takes up a bank line another invoice is waiting for.
-function journalEntries(lines, journal) {
+// A credit note runs the other way from an invoice: its money goes back out
+// as a refund (DR on a payment, CR on a receipt), or it is offset or written
+// off and never reaches the bank. It neither wants a receipt or a payment
+// the way an invoice does nor takes up one an invoice is waiting for.
+function invoiceEntries(lines, journal) {
   return lines.filter(function (line) {
-    return line.sourceJournalID === journal && !isStraddlingLine(line);
+    return line.sourceJournalID === journal && line.documentType !== "credit-note" && !isStraddlingLine(line);
   });
 }
 
@@ -769,7 +773,7 @@ const SETTLEMENT_KINDS = [
     actionLabel: "Add the sale",
     what: "sale",
     sources: function (ctx) {
-      return unpaired(bankEntries(ctx.lines, RECEIPT_BANK_CODE, "D"), journalEntries(ctx.lines, "sales"));
+      return unpaired(bankEntries(ctx.lines, RECEIPT_BANK_CODE, "D"), invoiceEntries(ctx.lines, "sales"));
     },
     account: function (ctx) {
       return ctx.chart.sales[0] || null;
@@ -785,7 +789,7 @@ const SETTLEMENT_KINDS = [
     actionLabel: "Add the purchase",
     what: "purchase",
     sources: function (ctx) {
-      return unpaired(bankEntries(ctx.lines, PAYMENT_BANK_CODE, "C"), journalEntries(ctx.lines, "purchases"));
+      return unpaired(bankEntries(ctx.lines, PAYMENT_BANK_CODE, "C"), invoiceEntries(ctx.lines, "purchases"));
     },
     account: function (ctx) {
       return repostAccount(ctx, "purchases");
@@ -801,7 +805,7 @@ const SETTLEMENT_KINDS = [
     actionLabel: "Add the receipt",
     what: "receipt",
     sources: function (ctx) {
-      return unpaired(journalEntries(ctx.lines, "sales"), bankEntries(ctx.lines, RECEIPT_BANK_CODE, "D"));
+      return unpaired(invoiceEntries(ctx.lines, "sales"), bankEntries(ctx.lines, RECEIPT_BANK_CODE, "D"));
     },
     account: settlementBankAccount,
     build: function (ctx, source, account, entryNumber) {
@@ -815,7 +819,7 @@ const SETTLEMENT_KINDS = [
     actionLabel: "Add the payment",
     what: "payment",
     sources: function (ctx) {
-      return unpaired(journalEntries(ctx.lines, "purchases"), bankEntries(ctx.lines, PAYMENT_BANK_CODE, "C"));
+      return unpaired(invoiceEntries(ctx.lines, "purchases"), bankEntries(ctx.lines, PAYMENT_BANK_CODE, "C"));
     },
     account: settlementBankAccount,
     build: function (ctx, source, account, entryNumber) {

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

@@ -0,0 +1,297 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// book-queries.js — read-only questions over a diya-gl book: which lines
+// match a filter and what they add up to, the chart of accounts with the
+// report rows each account feeds, the book's own profile, and the book
+// checks with the entryNumbers behind each verdict. Pure functions over
+// (book, lines) and the documents the engine already builds, so the MCP
+// server and any other caller read the same answers.
+
+import { isStraddlingLine } from "./scenario-extractor.js";
+
+function isoDate(value) {
+  if (!value) return "";
+  if (value instanceof Date) return value.toISOString().slice(0, 10);
+  return String(value).slice(0, 10);
+}
+
+// A TOML date parses to a Date; JSON would print it with a midnight time the
+// book never stated, so a date-only value goes out as YYYY-MM-DD.
+function plainValue(value) {
+  if (value instanceof Date) {
+    const iso = value.toISOString();
+    return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso;
+  }
+  if (Array.isArray(value)) return value.map(plainValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, plainValue(inner)]));
+  }
+  return value;
+}
+
+function asSet(filter) {
+  if (filter === undefined || filter === null || filter === "") return null;
+  return new Set((Array.isArray(filter) ? filter : [filter]).map(String));
+}
+
+/**
+ * A line's amount in pence with the sign a total wants: a credit note
+ * reverses its sale or purchase, and a credit on the bank or the journal
+ * (debitCreditCode "C", money out of a bank account) is negative.
+ *
+ * A credit note on the bad debts account (4005) or the fixed asset sale
+ * account (4006) is negative here too. Both templates book a written-off
+ * debt as a negative sale: the Basic Sole Trader sales tabs have one gross
+ * column feeding turnover, and the Limited Company sales tabs' "Bad Debts
+ * written off" column T reaches the P&L negated (TrialBalance row 81 =
+ * -Sales!T1, MnthP&L B34), so only a negative entry raises the expense. A
+ * customer's total therefore falls by the debt written off against them.
+ * @param {Object} line
+ * @returns {number}
+ */
+export function signedPence(line) {
+  const reverses = (line.sourceJournalID === "sales" || line.sourceJournalID === "purchases") && line.documentType === "credit-note";
+  const pence = Math.round((Number(line.amount) || 0) * 100);
+  return reverses || line.debitCreditCode === "C" ? -pence : pence;
+}
+
+const GROUP_KEYS = {
+  detailComment: (line) => line.detailComment ?? "",
+  accountMainID: (line) => String(line.accountMainID ?? ""),
+  month: (line) => isoDate(line.postingDate).slice(0, 7),
+};
+
+/** The fields `lines` can group by. */
+export const LINE_GROUPINGS = Object.keys(GROUP_KEYS);
+
+function accountNames(book) {
+  const names = {};
+  for (const accounts of Object.values(book?.accounts || {})) {
+    for (const [id, account] of Object.entries(accounts || {})) names[id] = account?.accountMainDescription;
+  }
+  return names;
+}
+
+const byLargest = (a, b) => Math.abs(b.totalPence) - Math.abs(a.totalPence) || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+
+/**
+ * The lines matching every filter given, their count and signed total in
+ * pence, and either the lines themselves or their groups.
+ *
+ * Grouped by detailComment or accountMainID, groups come largest total
+ * first; by month, in date order. Ungrouped with `top`, lines come largest
+ * amount first; ungrouped without it, in book order.
+ * @param {Object} book
+ * @param {Array} lines
+ * @param {Object} [filters]
+ * @param {string|string[]} [filters.journal] - sourceJournalID
+ * @param {string|string[]} [filters.accountMainID]
+ * @param {string} [filters.from] - YYYY-MM-DD, inclusive
+ * @param {string} [filters.to] - YYYY-MM-DD, inclusive
+ * @param {string} [filters.text] - case-insensitive, in detailComment or lineItemComment
+ * @param {string} [filters.documentReference] - case-insensitive, in documentReference
+ * @param {string} [filters.groupBy] - one of LINE_GROUPINGS
+ * @param {number} [filters.top] - at most this many groups (or lines)
+ * @returns {Object}
+ */
+export function queryLines(book, lines, filters = {}) {
+  const { journal, accountMainID, from, to, text, documentReference, groupBy, top } = filters;
+  if (groupBy !== undefined && !GROUP_KEYS[groupBy]) {
+    throw new Error(`groupBy must be one of ${LINE_GROUPINGS.join(", ")}, got "${groupBy}"`);
+  }
+  if (top !== undefined && (!Number.isInteger(top) || top < 1)) throw new Error(`top must be a whole number above zero, got "${top}"`);
+  const journals = asSet(journal);
+  const accounts = asSet(accountMainID);
+  const needle = text ? String(text).toLowerCase() : null;
+  const reference = documentReference ? String(documentReference).toLowerCase() : null;
+
+  const matched = lines.filter((line) => {
+    if (journals && !journals.has(String(line.sourceJournalID))) return false;
+    if (accounts && !accounts.has(String(line.accountMainID))) return false;
+    const date = isoDate(line.postingDate);
+    if (from && date < from) return false;
+    if (to && date > to) return false;
+    if (needle && !`${line.detailComment ?? ""}\n${line.lineItemComment ?? ""}`.toLowerCase().includes(needle)) return false;
+    if (
+      reference &&
+      !String(line.documentReference ?? "")
+        .toLowerCase()
+        .includes(reference)
+    )
+      return false;
+    return true;
+  });
+
+  const answer = { count: matched.length, totalPence: matched.reduce((sum, line) => sum + signedPence(line), 0) };
+
+  if (!groupBy) {
+    const ordered = top
+      ? matched
+          .slice()
+          .sort((a, b) => Math.abs(signedPence(b)) - Math.abs(signedPence(a)))
+          .slice(0, top)
+      : matched;
+    return { ...answer, lines: ordered };
+  }
+
+  const keyOf = GROUP_KEYS[groupBy];
+  const groups = new Map();
+  for (const line of matched) {
+    const key = keyOf(line);
+    if (!groups.has(key)) groups.set(key, { key, count: 0, totalPence: 0, entryNumbers: [] });
+    const group = groups.get(key);
+    group.count += 1;
+    group.totalPence += signedPence(line);
+    group.entryNumbers.push(line.entryNumber);
+  }
+  const names = groupBy === "accountMainID" ? accountNames(book) : {};
+  let ordered = [...groups.values()].map((group) => (names[group.key] ? { ...group, name: names[group.key] } : group));
+  ordered.sort(groupBy === "month" ? (a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0) : byLargest);
+  if (top) ordered = ordered.slice(0, top);
+  return { ...answer, groupBy, groups: ordered };
+}
+
+// A reconciliation table, not a line of the accounts: its rows restate
+// journal totals the account rows already carry.
+const NOT_A_REPORT_ROW = "section/journal-category-vat-netting/";
+
+// The rows with the least else in them, among those a test admits.
+function smallestRows(rows, admits) {
+  let best = [];
+  let bestSize = Infinity;
+  for (const row of rows) {
+    if (!admits(row)) continue;
+    const size = row.entries.size;
+    if (size < bestSize) {
+      best = [row];
+      bestSize = size;
+    } else if (size === bestSize) {
+      best.push(row);
+    }
+  }
+  return best;
+}
+
+// The report rows an account feeds: of the rows built from whole accounts
+// (every year line of each account they touch, so a month's or a debtor's
+// slice of an account does not count), the smallest that holds every year
+// line of this one. An account the engine splits across rows (a bank
+// account whose opening line sits apart from its movements) feeds instead
+// the smallest of the rows holding the most of its lines. Read off the
+// engine's own attribution rather than restated here. A VAT-straddling line
+// belongs to a return outside the year and reaches no row of the year's
+// accounts.
+function rowsFed(account, rows, entriesOfAccount, accountOfEntry) {
+  const own = entriesOfAccount.get(account);
+  if (!own || own.size === 0) return [];
+  const holdsAll = (row) => [...own].every((entry) => row.entries.has(entry));
+  const wholeAccounts = (row) =>
+    [...row.entries].every((entry) => {
+      const other = entriesOfAccount.get(accountOfEntry.get(entry));
+      return !other || [...other].every((otherEntry) => row.entries.has(otherEntry));
+    });
+  let best = smallestRows(rows, (row) => holdsAll(row) && wholeAccounts(row));
+  if (best.length === 0) {
+    const held = (row) => [...own].filter((entry) => row.entries.has(entry)).length;
+    const most = Math.max(0, ...rows.map(held));
+    if (most > 0) best = smallestRows(rows, (row) => held(row) === most);
+  }
+  return best.map((row) => ({ key: row.key, label: row.label }));
+}
+
+/**
+ * The book's chart of accounts: each account's id, name, group (the
+ * book.toml table it sits in), its other declared fields, how many lines
+ * post to it and their signed total in pence, and the report rows it feeds.
+ * @param {Object} book
+ * @param {Array} lines
+ * @param {Object} attributedReport - R built with entryNumbers on every figure
+ * @returns {Array<Object>}
+ */
+export function chartOfAccounts(book, lines, attributedReport) {
+  const rows = attributedReport.values
+    .filter((entry) => entry.key.startsWith("section/") && !entry.key.startsWith(NOT_A_REPORT_ROW) && entry.entryNumbers?.length > 0)
+    .map((entry) => ({ key: entry.key, label: entry.label, entries: new Set(entry.entryNumbers) }));
+  const accountOfEntry = new Map();
+  const entriesOfAccount = new Map();
+  for (const line of lines) {
+    if (isStraddlingLine(line)) continue;
+    const account = String(line.accountMainID);
+    accountOfEntry.set(line.entryNumber, account);
+    if (!entriesOfAccount.has(account)) entriesOfAccount.set(account, new Set());
+    entriesOfAccount.get(account).add(line.entryNumber);
+  }
+  const chart = [];
+  for (const [group, accounts] of Object.entries(book?.accounts || {})) {
+    for (const [id, account] of Object.entries(accounts || {})) {
+      const { accountMainDescription, ...declared } = account || {};
+      const posted = lines.filter((line) => String(line.accountMainID) === id);
+      chart.push({
+        id,
+        name: accountMainDescription ?? null,
+        group,
+        ...plainValue(declared),
+        lineCount: posted.length,
+        totalPence: posted.reduce((sum, line) => sum + signedPence(line), 0),
+        feeds: rowsFed(id, rows, entriesOfAccount, accountOfEntry),
+      });
+    }
+  }
+  return chart;
+}
+
+/**
+ * The book's own profile: product, period, the business, its tax settings,
+ * its bank accounts, the journals its lines are posted on, and every other
+ * table book.toml carries (registers, opening balances, stock).
+ * @param {Object} book
+ * @param {Array} lines
+ * @param {string} product - bst, taxi, se or ltd
+ * @returns {Object}
+ */
+export function bookProfile(book, lines, product) {
+  const { documentInfo, entityInformation, tax, accounts, ...registers } = book || {};
+  const journals = new Map();
+  for (const line of lines) {
+    const id = line.sourceJournalID;
+    const date = isoDate(line.postingDate);
+    if (!journals.has(id)) journals.set(id, { journal: id, count: 0, firstDate: date, lastDate: date });
+    const entry = journals.get(id);
+    entry.count += 1;
+    if (date < entry.firstDate) entry.firstDate = date;
+    if (date > entry.lastDate) entry.lastDate = date;
+  }
+  return {
+    product,
+    period: { start: isoDate(documentInfo?.periodCoveredStart), end: isoDate(documentInfo?.periodCoveredEnd) },
+    documentInfo: plainValue(documentInfo ?? {}),
+    entity: plainValue(entityInformation ?? {}),
+    tax: plainValue(tax ?? {}),
+    bankAccounts: Object.entries(accounts?.bank || {}).map(([id, account]) => ({
+      id,
+      name: account?.accountMainDescription ?? null,
+      ...plainValue(Object.fromEntries(Object.entries(account || {}).filter(([key]) => key !== "accountMainDescription"))),
+    })),
+    journals: [...journals.values()].sort((a, b) => (a.journal < b.journal ? -1 : 1)),
+    ...plainValue(registers),
+  };
+}
+
+/**
+ * The book checks and warnings with each one's verdict and the entryNumbers
+ * of the lines that fail it.
+ * @param {{results: Array, summary: Object}} bookChecks - runBookChecks() output
+ * @returns {{summary: Object, checks: Array<Object>}}
+ */
+export function checksWithEntries(bookChecks) {
+  return {
+    summary: bookChecks.summary,
+    checks: bookChecks.results.map(({ result, offenders, ...rest }) => ({
+      ...rest,
+      verdict: result,
+      entryNumbers: (offenders || []).map((offender) => offender.entryNumber).filter((entry) => entry !== undefined),
+      offenders: offenders || [],
+    })),
+  };
+}