@classytic/stage 0.2.0 → 0.4.0

package/dist/finance/accounting/types.d.mts

@@ -0,0 +1,649 @@
+//#region src/finance/accounting/types.d.ts
+type AccountCategory = 'Asset' | 'Liability' | 'Equity' | 'Income' | 'Expense';
+type PostingSide = 'debit' | 'credit';
+type AccountRole = 'cash' | 'bank' | 'capital' | 'drawings' | 'revenue' | 'expense' | 'inventory' | 'equipment' | 'loan' | 'receivable' | 'payable' | 'cost-of-sales';
+interface AccountDefinition {
+  id: string;
+  name: string;
+  category: AccountCategory;
+  role?: AccountRole;
+}
+interface JournalLine {
+  accountId: string;
+  side: PostingSide;
+  amount: number;
+}
+interface JournalEntry {
+  id: string;
+  narration: string;
+  lines: readonly JournalLine[];
+  date?: string;
+  source?: string;
+}
+interface AccountingPolicy {
+  decimalPlaces: number;
+}
+interface AccountingDiagnostic {
+  code: 'duplicate-account' | 'duplicate-entry' | 'unknown-account' | 'invalid-amount' | 'missing-debit' | 'missing-credit' | 'unbalanced-entry' | 'missing-role' | 'ambiguous-role' | 'invalid-adjustment' | 'invalid-analysis';
+  severity: 'error' | 'warning';
+  message: string;
+  entryId?: string;
+  accountId?: string;
+}
+interface ExplanationStep {
+  id: string;
+  kind: 'classify' | 'journalize' | 'validate' | 'post' | 'derive' | 'check';
+  rule: string;
+  working: string;
+  result: number | string | boolean;
+}
+interface LedgerPosting {
+  entryId: string;
+  contraAccountIds: readonly string[];
+  side: PostingSide;
+  amount: number;
+  narration: string;
+}
+interface LedgerAccount extends AccountDefinition {
+  postings: readonly LedgerPosting[];
+  debitTotal: number;
+  creditTotal: number;
+  balance: number;
+  balanceSide: PostingSide | 'zero';
+  normalBalance: number;
+}
+interface TrialBalanceLine {
+  accountId: string;
+  name: string;
+  debit: number;
+  credit: number;
+}
+interface TrialBalance {
+  lines: readonly TrialBalanceLine[];
+  debitTotal: number;
+  creditTotal: number;
+  balances: boolean;
+}
+interface AccountingEquation {
+  assets: number;
+  liabilities: number;
+  contributedEquity: number;
+  income: number;
+  expenses: number;
+  profit: number;
+  equity: number;
+  left: number;
+  right: number;
+  balances: boolean;
+}
+interface FinancialStatements {
+  incomeStatement: {
+    income: number;
+    expenses: number;
+    profit: number;
+  };
+  statementOfFinancialPosition: {
+    assets: number;
+    liabilities: number;
+    equity: number;
+    balances: boolean;
+  };
+}
+interface StatementLine {
+  id: string;
+  label: string;
+  amount: number;
+  kind: 'detail' | 'subtotal' | 'total';
+  treatment?: 'add' | 'subtract' | 'result';
+}
+interface StatementSection {
+  id: string;
+  title: string;
+  lines: readonly StatementLine[];
+}
+interface SoleTraderStatementFacts {
+  revenue: number;
+  costOfSales: number;
+  expenses: number;
+  otherIncome?: number;
+  nonCurrentAssets: number;
+  inventory: number;
+  cash: number;
+  otherCurrentAssets?: number;
+  openingCapital: number;
+  capitalIntroduced?: number;
+  drawings?: number;
+  loan: number;
+  currentLiabilities: number;
+}
+interface SoleTraderStatementResult {
+  incomeStatement: readonly StatementSection[];
+  statementOfFinancialPosition: readonly StatementSection[];
+  values: {
+    grossProfit: number;
+    netProfit: number;
+    closingCapital: number;
+    totalAssets: number;
+    totalLiabilities: number;
+    totalEquityAndLiabilities: number;
+    balanceDifference: number;
+    netMargin: number;
+  };
+  balances: boolean;
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+interface PartnershipAgreement {
+  profit: number;
+  interestOnCapitalPct: number;
+  interestOnDrawingsPct: number;
+}
+interface PartnerFacts {
+  id: string;
+  name: string;
+  capital: number;
+  drawings: number;
+  salary: number;
+  share: number;
+  openingCurrentBalance?: number;
+  openingCurrentSide?: PostingSide;
+}
+interface PartnerAppropriation {
+  id: string;
+  name: string;
+  interestOnCapital: number;
+  salary: number;
+  interestOnDrawings: number;
+  shareOfResidual: number;
+  totalAppropriation: number;
+  currentAccountMovements: readonly {
+    label: string;
+    side: PostingSide;
+    amount: number;
+  }[];
+  closingCurrentBalance: number;
+  closingCurrentSide: PostingSide | 'zero';
+}
+interface PartnershipResult {
+  totalInterestOnCapital: number;
+  totalSalaries: number;
+  totalInterestOnDrawings: number;
+  residualProfit: number;
+  partners: readonly PartnerAppropriation[];
+  spread: number;
+  appropriatesExactly: boolean;
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+interface LimitedCompanyStatementFacts {
+  revenue: number;
+  costOfSales: number;
+  operatingExpenses: number;
+  financeCosts: number;
+  taxExpense: number;
+  openingRetainedEarnings: number;
+  dividendsDeclared: number;
+  ordinaryShareCapital: number;
+  sharePremium?: number;
+  generalReserve?: number;
+  debentures: number;
+  currentLiabilities: number;
+  nonCurrentAssets: number;
+  currentAssets: number;
+}
+interface LimitedCompanyStatementResult {
+  incomeStatement: readonly StatementSection[];
+  statementOfChangesInEquity: readonly StatementSection[];
+  statementOfFinancialPosition: readonly StatementSection[];
+  values: {
+    grossProfit: number;
+    operatingProfit: number;
+    profitBeforeTax: number;
+    profitForYear: number;
+    closingRetainedEarnings: number;
+    totalEquity: number;
+    totalLiabilities: number;
+    totalAssets: number;
+    totalEquityAndLiabilities: number;
+    balanceDifference: number;
+  };
+  balances: boolean;
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+type ClubMemberState = 'paid' | 'arrearsSettled' | 'prepaidLastYear' | 'owesThisYear' | 'prepaidNextYear';
+interface ClubMember {
+  name: string;
+  state: ClubMemberState;
+}
+interface ClubMemberTiming {
+  belongsTo: -1 | 0 | 1;
+  arrived: -1 | 0 | 1 | null;
+}
+interface ClubSubscriptionResult {
+  members: number;
+  cashReceived: number;
+  subscriptionIncome: number;
+  gap: number;
+  accruedIncome: number;
+  prepaidIncome: number;
+  arrearsSettled: number;
+  broughtForwardPrepaid: number;
+  accountRows: readonly {
+    label: string;
+    debit?: number;
+    credit?: number;
+    from?: ClubMemberState;
+  }[];
+  accountDebitTotal: number;
+  accountCreditTotal: number;
+  accountBalances: boolean;
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+interface ClubStatementFacts {
+  openingAssets: number;
+  openingLiabilities: number;
+  subscriptionIncome: number;
+  otherIncome: number;
+  expenses: number;
+  closingAssets: number;
+  closingLiabilities: number;
+}
+interface ClubStatementResult {
+  openingAccumulatedFund: number;
+  surplus: number;
+  expectedClosingFund: number;
+  closingNetAssets: number;
+  difference: number;
+  reconciles: boolean;
+  incomeAndExpenditure: readonly StatementSection[];
+  statementOfFinancialPosition: readonly StatementSection[];
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+interface ManufacturingAccountFacts {
+  openingRawMaterials: number;
+  purchasesOfRawMaterials: number;
+  closingRawMaterials: number;
+  directLabour: number;
+  directExpenses: number;
+  factoryOverheads: number;
+  openingWorkInProgress: number;
+  closingWorkInProgress: number;
+}
+interface ManufacturingFlowStage {
+  key: 'materials' | 'labour' | 'direct-expenses' | 'overheads' | 'opening-wip' | 'closing-wip';
+  label: string;
+  amount: number;
+  direction: 'in' | 'out';
+  reaches?: 'prime-cost' | 'total-factory-cost' | 'cost-of-production';
+}
+interface ManufacturingAccountResult {
+  materialsConsumed: number;
+  primeCost: number;
+  totalFactoryCost: number;
+  costOfProduction: number;
+  invertedClosingWipResult: number;
+  inversionDifference: number;
+  stages: readonly ManufacturingFlowStage[];
+  statement: readonly StatementSection[];
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+interface ManufacturingTradingFacts extends ManufacturingAccountFacts {
+  openingFinishedGoods: number;
+  closingFinishedGoods: number;
+  revenue: number;
+}
+interface ManufacturingTradingResult {
+  manufacturing: ManufacturingAccountResult;
+  goodsAvailableForSale: number;
+  costOfSales: number;
+  grossProfit: number;
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+interface SoleTraderPeriodCase {
+  accounts: readonly AccountDefinition[];
+  unadjustedEntries: readonly JournalEntry[];
+  adjustments: readonly AdjustmentFact[];
+}
+interface SoleTraderPeriodResult {
+  unadjusted: AccountingSolution;
+  adjustmentResults: readonly AdjustmentResult[];
+  adjusted: AccountingSolution;
+  statements: SoleTraderStatementResult;
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+type FinancialRatioKey = 'current' | 'quick' | 'inventoryDependence' | 'grossMargin' | 'markup' | 'netMargin' | 'roce' | 'gearing' | 'inventoryTurnover' | 'inventoryDays' | 'receivablesDays' | 'payablesDays';
+type FinancialRatioFamily = 'liquidity' | 'profitability' | 'capital' | 'efficiency';
+interface FinancialAnalysisFacts {
+  currentAssets: number;
+  inventory: number;
+  currentLiabilities: number;
+  nonCurrentLiabilities: number;
+  equity: number;
+  revenue: number;
+  costOfSales: number;
+  expenses?: number;
+  grossProfit?: number;
+  netProfit?: number;
+  capitalEmployed?: number;
+  averageInventory?: number;
+  tradeReceivables?: number;
+  creditRevenue?: number;
+  tradePayables?: number;
+  creditPurchases?: number;
+  daysInPeriod?: number;
+}
+interface FinancialRatioMetric {
+  key: FinancialRatioKey;
+  label: string;
+  family: FinancialRatioFamily;
+  value: number | null;
+  unit: 'ratio' | 'percent' | 'times' | 'days';
+  numerator: number;
+  denominator: number;
+  formula: string;
+}
+interface FinancialAnalysisResult {
+  values: {
+    workingCapital: number;
+    grossProfit: number;
+    netProfit: number;
+    capitalEmployed: number;
+  };
+  metrics: readonly FinancialRatioMetric[];
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+interface FinancialAnalysisComparison {
+  current: FinancialAnalysisResult;
+  prior: FinancialAnalysisResult;
+  deltas: readonly {
+    key: FinancialRatioKey;
+    current: number | null;
+    prior: number | null;
+    absolute: number | null;
+  }[];
+}
+interface FinancialRatioBenchmark {
+  key: FinancialRatioKey;
+  minimum?: number;
+  maximum?: number;
+}
+interface FinancialRatioAssessment {
+  key: FinancialRatioKey;
+  value: number | null;
+  passes: boolean;
+  benchmark: FinancialRatioBenchmark;
+}
+interface AccountingSolution {
+  acceptedEntries: readonly JournalEntry[];
+  rejectedEntries: readonly JournalEntry[];
+  diagnostics: readonly AccountingDiagnostic[];
+  ledger: readonly LedgerAccount[];
+  trialBalance: TrialBalance;
+  equation: AccountingEquation;
+  statements: FinancialStatements;
+  trace: readonly ExplanationStep[];
+}
+interface AccountingExpectation {
+  acceptedEntries?: number;
+  rejectedEntries?: number;
+  trialBalanceTotal?: number;
+  profit?: number;
+  assets?: number;
+  liabilities?: number;
+  equity?: number;
+  diagnosticCodes?: readonly AccountingDiagnostic['code'][];
+}
+interface AccountingCase {
+  id: string;
+  title: string;
+  accounts: readonly AccountDefinition[];
+  events?: readonly BusinessEvent[];
+  entries?: readonly JournalEntry[];
+  policy?: AccountingPolicy;
+  expect: AccountingExpectation;
+}
+interface AccountingCheck {
+  name: string;
+  passed: boolean;
+  expected: number | string | readonly string[];
+  actual: number | string | readonly string[];
+}
+interface AccountingCaseResult {
+  caseId: string;
+  passed: boolean;
+  checks: readonly AccountingCheck[];
+  solution: AccountingSolution;
+}
+type AdjustmentFact = {
+  id: string;
+  type: 'expense-period-end';
+  expenseAccountId: string;
+  accrualAccountId: string;
+  prepaymentAccountId: string;
+  recognizedExpense: number;
+  recordedExpense: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'depreciation';
+  expenseAccountId: string;
+  accumulatedDepreciationAccountId: string;
+  method: 'straight-line';
+  cost: number;
+  residualValue: number;
+  usefulLifeYears: number;
+  periodFraction?: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'depreciation';
+  expenseAccountId: string;
+  accumulatedDepreciationAccountId: string;
+  method: 'reducing-balance';
+  openingBookValue: number;
+  rate: number;
+  periodFraction?: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'irrecoverable-debt';
+  expenseAccountId: string;
+  receivableAccountId: string;
+  amount: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'allowance-change';
+  expenseAccountId: string;
+  allowanceAccountId: string;
+  openingAllowance: number;
+  requiredAllowance: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'closing-inventory';
+  inventoryAccountId: string;
+  costOfSalesAccountId: string;
+  currentInventory: number;
+  requiredInventory: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'correct-entry';
+  wrongEntry: JournalEntry;
+  correctEntry: JournalEntry;
+  narration?: string;
+};
+interface AdjustmentResult {
+  factId: string;
+  entries: readonly JournalEntry[];
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+  values: Readonly<Record<string, number | string>>;
+}
+type BankReconciliationItem = {
+  id: string;
+  type: 'deposit-in-transit' | 'unpresented-cheque';
+  amount: number;
+  label?: string;
+} | {
+  id: string;
+  type: 'bank-credit' | 'bank-debit';
+  amount: number;
+  label?: string;
+} | {
+  id: string;
+  type: 'cashbook-correction';
+  amount: number;
+  direction: 'increase' | 'decrease';
+  label?: string;
+};
+interface BankReconciliationResult {
+  adjustedCashBookBalance: number;
+  reconciledBankStatementBalance: number;
+  difference: number;
+  reconciles: boolean;
+  cashBookAdjustments: readonly {
+    id: string;
+    label: string;
+    amount: number;
+  }[];
+  timingDifferences: readonly {
+    id: string;
+    label: string;
+    amount: number;
+  }[];
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+interface ControlAccountFacts {
+  kind: 'receivables' | 'payables';
+  openingBalance: number;
+  creditTransactions: number;
+  cashSettled: number;
+  returns: number;
+  discounts: number;
+  contra: number;
+  writeOffs?: number;
+  dishonouredPayments?: number;
+  otherCharges?: number;
+  expectedClosingBalance?: number;
+}
+interface ControlAccountResult {
+  closingBalance: number;
+  expectedClosingBalance?: number;
+  difference?: number;
+  agrees?: boolean;
+  movements: readonly {
+    label: string;
+    side: PostingSide;
+    amount: number;
+  }[];
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+type TrialBalanceErrorType = 'complete-omission' | 'commission' | 'principle' | 'original-entry' | 'complete-reversal' | 'compensating' | 'one-sided-entry' | 'unequal-entry' | 'casting-error' | 'balance-omitted';
+interface TrialBalanceErrorDiagnosis {
+  type: TrialBalanceErrorType;
+  affectsAgreement: boolean;
+  requiresSuspense: boolean;
+  reason: string;
+}
+interface SuspenseCorrectionFact {
+  id: string;
+  suspenseAccountId: string;
+  affectedAccountId: string;
+  missingSide: PostingSide;
+  amount: number;
+  narration?: string;
+}
+type SuspenseDiscoveredError = Omit<SuspenseCorrectionFact, 'suspenseAccountId'> & {
+  errorType: TrialBalanceErrorType;
+  label?: string;
+};
+interface SuspenseReconstructionFacts {
+  trialBalanceDebitTotal: number;
+  trialBalanceCreditTotal: number;
+  suspenseAccountId: string;
+  errors: readonly SuspenseDiscoveredError[];
+}
+interface SuspenseMovement {
+  id: string;
+  label: string;
+  side: PostingSide;
+  amount: number;
+}
+interface SuspenseReconstructionResult {
+  openingBalance: {
+    side: PostingSide | 'zero';
+    amount: number;
+  };
+  corrections: readonly JournalEntry[];
+  movements: readonly SuspenseMovement[];
+  closingBalance: {
+    side: PostingSide | 'zero';
+    amount: number;
+  };
+  clears: boolean;
+  diagnostics: readonly AccountingDiagnostic[];
+  trace: readonly ExplanationStep[];
+}
+type BusinessEvent = {
+  id: string;
+  type: 'owner-investment';
+  amount: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'borrow';
+  amount: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'buy-equipment';
+  amount: number;
+  settlement: 'cash' | 'credit';
+  narration?: string;
+} | {
+  id: string;
+  type: 'buy-inventory';
+  amount: number;
+  settlement: 'cash' | 'credit';
+  narration?: string;
+} | {
+  id: string;
+  type: 'sale';
+  amount: number;
+  settlement: 'cash' | 'credit';
+  cost?: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'pay-expense';
+  amount: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'owner-drawings';
+  amount: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'collect-receivable';
+  amount: number;
+  narration?: string;
+} | {
+  id: string;
+  type: 'pay-payable';
+  amount: number;
+  narration?: string;
+};
+//#endregion
+export { AccountCategory, AccountDefinition, AccountRole, AccountingCase, AccountingCaseResult, AccountingCheck, AccountingDiagnostic, AccountingEquation, AccountingExpectation, AccountingPolicy, AccountingSolution, AdjustmentFact, AdjustmentResult, BankReconciliationItem, BankReconciliationResult, BusinessEvent, ClubMember, ClubMemberState, ClubMemberTiming, ClubStatementFacts, ClubStatementResult, ClubSubscriptionResult, ControlAccountFacts, ControlAccountResult, ExplanationStep, FinancialAnalysisComparison, FinancialAnalysisFacts, FinancialAnalysisResult, FinancialRatioAssessment, FinancialRatioBenchmark, FinancialRatioFamily, FinancialRatioKey, FinancialRatioMetric, FinancialStatements, JournalEntry, JournalLine, LedgerAccount, LedgerPosting, LimitedCompanyStatementFacts, LimitedCompanyStatementResult, ManufacturingAccountFacts, ManufacturingAccountResult, ManufacturingFlowStage, ManufacturingTradingFacts, ManufacturingTradingResult, PartnerAppropriation, PartnerFacts, PartnershipAgreement, PartnershipResult, PostingSide, SoleTraderPeriodCase, SoleTraderPeriodResult, SoleTraderStatementFacts, SoleTraderStatementResult, StatementLine, StatementSection, SuspenseCorrectionFact, SuspenseDiscoveredError, SuspenseMovement, SuspenseReconstructionFacts, SuspenseReconstructionResult, TrialBalance, TrialBalanceErrorDiagnosis, TrialBalanceErrorType, TrialBalanceLine };

package/dist/finance/accounting/validate.d.mts

@@ -0,0 +1,7 @@
+import { AccountDefinition, AccountingDiagnostic, AccountingPolicy, JournalEntry } from "./types.mjs";
+
+//#region src/finance/accounting/validate.d.ts
+declare function validateChart(accounts: readonly AccountDefinition[]): AccountingDiagnostic[];
+declare function validateJournalEntry(entry: JournalEntry, accounts: readonly AccountDefinition[], policy: AccountingPolicy): AccountingDiagnostic[];
+//#endregion
+export { validateChart, validateJournalEntry };

package/dist/finance/accounting/validate.mjs

@@ -0,0 +1,67 @@
+import { toMinor } from "./precision.mjs";
+
+//#region src/finance/accounting/validate.ts
+function validateChart(accounts) {
+	const seen = /* @__PURE__ */ new Set();
+	const diagnostics = [];
+	for (const account of accounts) {
+		if (seen.has(account.id)) diagnostics.push({
+			code: "duplicate-account",
+			severity: "error",
+			accountId: account.id,
+			message: `Account ${account.id} is declared more than once.`
+		});
+		seen.add(account.id);
+	}
+	return diagnostics;
+}
+function validateJournalEntry(entry, accounts, policy) {
+	const known = new Set(accounts.map((account) => account.id));
+	const diagnostics = [];
+	let debits = 0, credits = 0, hasDebit = false, hasCredit = false;
+	for (const line of entry.lines) {
+		if (!known.has(line.accountId)) diagnostics.push({
+			code: "unknown-account",
+			severity: "error",
+			entryId: entry.id,
+			accountId: line.accountId,
+			message: `Entry ${entry.id} refers to unknown account ${line.accountId}.`
+		});
+		if (!Number.isFinite(line.amount) || line.amount <= 0) diagnostics.push({
+			code: "invalid-amount",
+			severity: "error",
+			entryId: entry.id,
+			accountId: line.accountId,
+			message: `Entry ${entry.id} has a non-positive or non-finite amount.`
+		});
+		if (line.side === "debit") {
+			hasDebit = true;
+			debits += toMinor(line.amount, policy);
+		} else {
+			hasCredit = true;
+			credits += toMinor(line.amount, policy);
+		}
+	}
+	if (!hasDebit) diagnostics.push({
+		code: "missing-debit",
+		severity: "error",
+		entryId: entry.id,
+		message: `Entry ${entry.id} has no debit line.`
+	});
+	if (!hasCredit) diagnostics.push({
+		code: "missing-credit",
+		severity: "error",
+		entryId: entry.id,
+		message: `Entry ${entry.id} has no credit line.`
+	});
+	if (debits !== credits) diagnostics.push({
+		code: "unbalanced-entry",
+		severity: "error",
+		entryId: entry.id,
+		message: `Entry ${entry.id} debits and credits differ.`
+	});
+	return diagnostics;
+}
+
+//#endregion
+export { validateChart, validateJournalEntry };