@jjlmoya/utils-civic 1.6.0 → 1.7.0

package/src/tool/public-budget-analyzer/i18n/zh.ts

@@ -0,0 +1,115 @@
+import type { FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import { bibliography } from '../bibliography';
+import type { PublicBudgetLocaleContent } from '../entry';
+import type { PublicBudgetUI } from '../ui';
+
+const ui: PublicBudgetUI = {
+  uploadLabel: '将预算 CSV 或 JSON 文件拖到这里',
+  uploadHelp: '必填字段: 类别和金额。可选字段: 人口、期间、priorAmount、货币和父类别。',
+  loadExample: '加载示例预算',
+  supportedFormat: 'CSV 或 JSON，仅在此浏览器中处理',
+  tableHeading: '来源行和类别合计',
+  categoryLabel: '类别',
+  amountLabel: '金额',
+  populationLabel: '人口',
+  sourceRowsLabel: '来源行',
+  analyzeEmpty: '选择文件或加载示例来检查预算。',
+  resultHeading: '预算全景',
+  totalLabel: '总支出',
+  perCapitaLabel: '人均支出',
+  variationLabel: '与上一期间的变化',
+  topCategoryLabel: '最大类别',
+  shareLabel: '占总额比例',
+  sourceLabel: '来源行',
+  noData: '目前还没有有效的预算行。',
+  warningsHeading: '需要检查的警告',
+  errorsHeading: '未纳入的行',
+  methodHeading: '使用的方法',
+  methodText: '工具会验证必填字段，保留每一条来源行，合并相同的类别路径，并根据标准化金额计算合计。当总额为正时，类别占比等于类别金额除以总额。人均支出使用第一个一致的正人口值作为分母。期间变化等于当前金额减去上一金额，再除以上一金额的绝对值。',
+  limitsHeading: '这个工具不会做什么',
+  limitsText: '它不会证明预算完整、可比较、合法、高效、公平、无偏或分类正确。它不会审计来源，不会评价政策质量，不会换算货币，也不会判断某一行是拨款、债务、付款还是预测。',
+  edgeCasesHeading: '边界情况和数据警告',
+  edgeCasesText: '混合货币、变化的人口、重复类别、负数调整、父行和子行并存、本地数字格式以及上一期间金额为零，都需要人工复核。浏览器保留原始行号，因此每个合计都可以追溯到输入数据。',
+  downloadCsv: '下载已复核表格',
+  printAction: '打印分析',
+  rowsLabel: '有效行',
+  categoriesLabel: '类别',
+  positiveTotalLabel: '已可视化的正数金额',
+  previousTotalLabel: '上一期间合计',
+  invalidFile: '文件无法被解析为空非空的 CSV 或 JSON 表格。',
+  fileReadError: '此浏览器无法读取文件。',
+  exampleName: '社区预算示例',
+  noPreviousData: '没有提供可比较的上一期间金额。',
+};
+
+const softwareApplication: SoftwareApplication = {
+  '@type': 'SoftwareApplication',
+  name: '公共预算分析工具',
+  applicationCategory: 'EducationalApplication',
+  operatingSystem: 'Any',
+  description: '在本地查看公共支出、类别占比、人均金额以及期间变化。',
+  url: 'https://gamebob.dev/zh/gonggong-yusuan-zhichu-fenxi',
+  offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
+};
+
+const faqPage: FAQPage = {
+  '@type': 'FAQPage',
+  mainEntity: [
+    { '@type': 'Question', name: '分析需要哪些列?', acceptedAnswer: { '@type': 'Answer', text: '每一行都需要类别和数字金额。人口、期间、priorAmount、货币和父类别是可选的。' } },
+    { '@type': 'Question', name: '人均支出如何计算?', acceptedAnswer: { '@type': 'Answer', text: '总金额除以表格中第一个一致的正人口值。不同的分母会保留并产生警告。' } },
+    { '@type': 'Question', name: '重复类别会怎样?', acceptedAnswer: { '@type': 'Answer', text: '拥有相同类别路径的行会相加，同时保留来源行号，以便区分真实拆分和重复计算。' } },
+    { '@type': 'Question', name: '它能证明预算很好或公平吗?', acceptedAnswer: { '@type': 'Answer', text: '不能。它只描述提供的数字，不判断完整性、合法性、效率、公平性、分类或结果。' } },
+  ],
+};
+
+const howTo: HowTo = {
+  '@type': 'HowTo',
+  name: '分析公共预算表',
+  step: [
+    { '@type': 'HowToStep', name: '准备表格', text: '创建 CSV 或 JSON 表格，每行包含一个类别和金额。保持货币和会计口径一致。' },
+    { '@type': 'HowToStep', name: '补充背景字段', text: '只有在含义一致时，才添加人口、期间、priorAmount、货币或父类别。' },
+    { '@type': 'HowToStep', name: '加载文件', text: '将文件拖入工具，或加载示例来查看预期结构和本地验证结果。' },
+    { '@type': 'HowToStep', name: '阅读全景', text: '用比例条查看构成，用可访问表格查看准确金额、变化和来源行。' },
+    { '@type': 'HowToStep', name: '检查警告', text: '得出结论前，先处理混合货币、重复路径、负数调整、零分母和父行。' },
+  ],
+};
+
+export const content: PublicBudgetLocaleContent = {
+  slug: 'public-budget-analyzer',
+  title: '公共预算分析工具',
+  description: '在本地分析公共预算表，查看总支出、类别占比、人均支出、期间变化以及每个合计背后的来源行。',
+  ui,
+  seo: [
+    { type: 'title', text: '把公共预算表变成可核查的视图', level: 2 },
+    { type: 'paragraph', html: '公共预算文件经常把类别标签、会计期间、人口分母和调整金额混在一张难以快速阅读的表中。这个分析工具保留来源行，验证必填字段，并将同一份标准化数据转换为合计、类别比例、人均支出和期间变化。' },
+    { type: 'paragraph', html: '结果是对数字的描述，不是政策判断。一个较大的类别可能来自法定职责、一次性投资、转移支付或不同的会计边界。这个视图让这些模式可见，帮助你带着更具体的问题回到原始资料。' },
+    { type: 'title', text: '计算结果代表什么', level: 2 },
+    { type: 'paragraph', html: '总额是所有有效数字金额的总和，包括负数调整。当总额为正时，类别占比是类别合计除以总额。正数金额使用比例条表示，负数金额留在表格中，因为用正面积表示会改变它的含义。' },
+    { type: 'table', headers: ['结果', '计算', '核查问题'], rows: [['总支出', '标准化金额之和', '所有行是否使用相同的会计口径?'], ['类别占比', '类别金额除以正数总额', '类别是否互斥，父类别是否和子类别重叠?'], ['人均支出', '总额除以正人口分母', '人口是否对应同一个地点和期间?'], ['期间变化', '当前金额减去上一金额，再除以上一金额绝对值', '期间是否可比，是否避免了零基数?']] },
+    { type: 'title', text: '准备可比较的数据', level: 2 },
+    { type: 'paragraph', html: '每一行使用同一种货币，并明确金额的含义。预算授权、债务、付款和预测都可能是有效数字，却回答不同的问题。请在来源旁记录这种含义，因为工具无法从列名推断它。' },
+    { type: 'list', items: ['每个类别使用一行，或提供父类别来建立有意设计的层级。', '保持人口口径一致，不要混合居民、选民、家庭或服务使用者。', '只有上一期间使用相同类别和口径时，才加入 priorAmount。', '检查重复类别路径和父行，避免意外重复计算。', '将复核后的表格与原始来源和使用的假设一起保存。'] },
+    { type: 'tip', title: '比例不是优先级评分', html: '金额最大的类别不一定最重要、最浪费或最成功。用这个视图寻找规模和变化，然后阅读来源注释和服务结果。' },
+    { type: 'title', text: '得出结论前先阅读警告', level: 2 },
+    { type: 'paragraph', html: '重复路径会被合并，避免合计在没有提示的情况下偏低，但来源行列表可以帮助你确认这种合并是否有意。混合货币不会被换算。人口为零时不显示人均结果，上一金额为零时不显示变化百分比，因为除以零没有有意义的解释。' },
+    { type: 'paragraph', html: '嵌套类别尤其需要注意。如果表格同时把教育和教育 > 学校作为金额，直接相加可能把同一笔支出计算两次。工具会提示嵌套路径，但只有来源方法能够说明父行是小计还是独立项目。' },
+    { type: 'title', text: '第一次分析之后要做什么', level: 2 },
+    { type: 'paragraph', html: '使用行号回到官方文件，记录每一个修正或解释。比较含义相同的期间，保留负数调整，并在来源确认小计已经包含其中时删除小计后重新分析。' },
+    { type: 'tip', title: '保持数据边界清晰', html: '这是本地描述性分析。它不验证文件是否完整，不按官方标准进行支出分类，不协调货币，也不证明支出与结果之间存在因果关系。' },
+  ],
+  faq: [
+    { question: '分析需要哪些列?', answer: '每行需要类别和数字金额。人口、期间、priorAmount、货币和父类别是可选的。' },
+    { question: '人均支出如何计算?', answer: '总额除以第一个一致的正人口值。分母不一致时会产生警告。' },
+    { question: '重复类别会怎样?', answer: '相同类别路径会相加，同时显示来源行以便检查。' },
+    { question: '它能证明预算很好或公平吗?', answer: '不能。它描述提供的数字，不能判断完整性、合法性、效率、公平性或结果。' },
+  ],
+  bibliography,
+  howTo: [
+    { name: '准备表格', text: '创建每行包含类别和金额的 CSV 或 JSON，并使用相同货币和会计口径。' },
+    { name: '补充背景字段', text: '只有在含义一致时才加入人口、期间、priorAmount、货币或父类别。' },
+    { name: '加载文件', text: '拖入文件或加载示例来查看预期结构。' },
+    { name: '阅读全景', text: '用比例条查看构成，用表格查看数值、变化和来源行。' },
+    { name: '检查警告', text: '下结论前先处理混合货币、重复项、负数调整、零分母和父行。' },
+  ],
+  schemas: [softwareApplication, faqPage, howTo] as unknown as Record<string, unknown>[],
+};

package/src/tool/public-budget-analyzer/index.ts

@@ -0,0 +1,11 @@
+import type { ToolDefinition } from '../../types';
+import { publicBudgetAnalyzer } from './entry';
+
+export * from './entry';
+export * from './logic';
+export const PUBLIC_BUDGET_ANALYZER_TOOL: ToolDefinition = {
+  entry: publicBudgetAnalyzer,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/public-budget-analyzer/logic.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { analyzeBudgetRecords, parseBudgetText } from './logic';
+import { reviewedCsv } from './dom-views';
+
+describe('public budget analyzer logic', () => {
+  it('parses CSV with quoted special characters and decimal values', () => {
+    const parsed = parseBudgetText('category,amount\n"Parks, east","1.234,50"');
+    expect(parsed.errors).toEqual([]);
+    expect(parsed.records[0]?.category).toBe('Parks, east');
+    expect(parsed.records[0]?.amount).toBe('1.234,50');
+  });
+
+  it('parses JSON arrays and data envelopes', () => {
+    expect(parseBudgetText('[{"category":"Health","amount":10}]').records).toHaveLength(1);
+    expect(parseBudgetText('{"data":[{"category":"Health","amount":10}]}', 'json').records).toHaveLength(1);
+  });
+
+  it('reports empty and malformed inputs', () => {
+    expect(parseBudgetText('').errors).toContain('The file is empty.');
+    expect(parseBudgetText('category,amount\nParks', 'csv').errors).toEqual([]);
+    expect(parseBudgetText('category,amount\n"Parks,10', 'csv').errors).toContain('CSV contains an unclosed quoted field.');
+    expect(parseBudgetText('{bad', 'json').errors).toContain('JSON could not be parsed.');
+    expect(parseBudgetText('{"data":[1]}', 'json').errors).toContain('JSON must be an array of objects or an object with a data array.');
+  });
+
+  it('calculates totals, shares, per capita values, and period changes', () => {
+    const analysis = analyzeBudgetRecords([
+      { category: 'Education', amount: '1,000.50', population: 100, priorAmount: 800, currency: 'EUR', period: '2026' },
+      { category: 'Health', amount: 500, population: 100, priorAmount: 600, currency: 'EUR', period: '2026' },
+    ]);
+    expect(analysis.total).toBe(1500.5);
+    expect(analysis.perCapita).toBe(15.005);
+    expect(analysis.variation).toBeCloseTo(0.0717857);
+    expect(analysis.categories[0]?.share).toBeCloseTo(1000.5 / 1500.5);
+    expect(analysis.currency).toBe('EUR');
+    expect(analysis.period).toBe('2026');
+  });
+
+  it('groups duplicate paths, retains source rows, and handles hierarchy', () => {
+    const analysis = analyzeBudgetRecords([
+      { category: 'Education > Schools', amount: 50 },
+      { category: 'Schools', parentCategory: 'Education', amount: 25 },
+      { category: 'Housing', amount: 10 },
+    ]);
+    expect(analysis.categories[0]?.amount).toBe(75);
+    expect(analysis.categories[0]?.sourceRows).toEqual([2, 3]);
+    expect(analysis.warnings.some((warning) => warning.includes('Duplicate category paths'))).toBe(true);
+    expect(analysis.warnings.some((warning) => warning.includes('Nested paths'))).toBe(true);
+  });
+
+  it('keeps negative adjustments and warns about zero denominators and baselines', () => {
+    const analysis = analyzeBudgetRecords([
+      { category: 'Adjustment', amount: -20, population: 0, priorAmount: 0 },
+      { category: 'Services', amount: 20, population: 200, priorAmount: 100 },
+    ]);
+    expect(analysis.total).toBe(0);
+    expect(analysis.positiveTotal).toBe(20);
+    expect(analysis.perCapita).toBe(0);
+    expect(analysis.variation).toBe(-1);
+    expect(analysis.warnings.join(' ')).toContain('Negative amounts');
+    expect(analysis.warnings.join(' ')).toContain('Population contains a non-positive value');
+    expect(analysis.warnings.join(' ')).toContain('total is not positive');
+    expect(analysis.warnings.join(' ')).toContain('zero prior amount');
+  });
+
+  it('keeps valid rows while reporting missing categories and amounts', () => {
+    const analysis = analyzeBudgetRecords([
+      { category: 'Valid', amount: 12 },
+      { category: '', amount: 4 },
+      { category: 'Missing amount', amount: 'unknown' },
+      { category: 'Bad population', amount: 2, population: 'many' },
+    ]);
+    expect(analysis.rows).toHaveLength(1);
+    expect(analysis.errors).toHaveLength(3);
+  });
+
+  it('escapes reviewed CSV values', () => {
+    const analysis = analyzeBudgetRecords([{ category: 'Culture, "north"', amount: 12 }]);
+    expect(reviewedCsv(analysis)).toContain('"Culture, ""north"""');
+  });
+});

package/src/tool/public-budget-analyzer/logic.ts

@@ -0,0 +1,249 @@
+export interface RawBudgetRecord {
+  [key: string]: unknown;
+}
+
+export interface ParsedBudgetText {
+  format: 'csv' | 'json';
+  records: RawBudgetRecord[];
+  errors: string[];
+}
+
+export interface NormalizedBudgetRow {
+  category: string;
+  path: string[];
+  amount: number;
+  population?: number | undefined;
+  priorAmount?: number | undefined;
+  period?: string | undefined;
+  currency?: string | undefined;
+  sourceRow: number;
+}
+
+export interface BudgetCategorySummary {
+  category: string;
+  path: string[];
+  amount: number;
+  share?: number | undefined;
+  priorAmount?: number | undefined;
+  variation?: number | undefined;
+  sourceRows: number[];
+}
+
+export interface BudgetAnalysis {
+  rows: NormalizedBudgetRow[];
+  categories: BudgetCategorySummary[];
+  total: number;
+  positiveTotal: number;
+  previousTotal?: number | undefined;
+  population?: number | undefined;
+  perCapita?: number | undefined;
+  variation?: number | undefined;
+  currency?: string | undefined;
+  period?: string | undefined;
+  warnings: string[];
+  errors: string[];
+}
+
+const aliases = {
+  category: ['category', 'categoryname', 'name', 'label', 'programme', 'program', 'function'],
+  amount: ['amount', 'spending', 'expenditure', 'expense', 'value', 'total'],
+  population: ['population', 'inhabitants', 'residents'],
+  priorAmount: ['prioramount', 'previousamount', 'prior', 'previous', 'lastperiod'],
+  period: ['period', 'year', 'fiscalyear', 'date'],
+  currency: ['currency', 'currencycode', 'unit'],
+  parent: ['parentcategory', 'parent', 'group'],
+};
+
+function normalizeKey(value: string): string {
+  return value.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function findKey(record: RawBudgetRecord, names: string[]): string | undefined {
+  const keys = Object.keys(record);
+  const normalized = new Map(keys.map((key) => [normalizeKey(key), key]));
+  return names.map(normalizeKey).map((name) => normalized.get(name)).find(Boolean);
+}
+
+function readValue(record: RawBudgetRecord, names: string[]): unknown {
+  const key = findKey(record, names);
+  return key ? record[key] : undefined;
+}
+
+function parseNumber(value: unknown): number | undefined {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+  if (typeof value !== 'string' || !value.trim()) return undefined;
+  const compact = value.trim().replace(/\s/g, '').replace(/[^\d,.-]/g, '');
+  if (!compact) return undefined;
+  const comma = compact.lastIndexOf(',');
+  const dot = compact.lastIndexOf('.');
+  const normalized = comma > dot ? compact.replace(/\./g, '').replace(',', '.') : compact.replace(/,/g, '');
+  const result = Number(normalized);
+  return Number.isFinite(result) ? result : undefined;
+}
+
+function splitPath(value: string): string[] {
+  return value.split(/\s*(?:>|\/|\\|:)\s*/).map((part) => part.trim()).filter(Boolean);
+}
+
+function validateRow(record: RawBudgetRecord, category: string, amount: number | undefined, sourceRow: number): string | undefined {
+  if (!category) return `Row ${sourceRow}: category is empty.`;
+  if (amount === undefined) return `Row ${sourceRow}: amount is missing or not numeric.`;
+  if (hasInvalidOptional(record, aliases.population)) return `Row ${sourceRow}: population is not numeric.`;
+  if (hasInvalidOptional(record, aliases.priorAmount)) return `Row ${sourceRow}: priorAmount is not numeric.`;
+  return undefined;
+}
+
+function normalizeRow(record: RawBudgetRecord, sourceRow: number): { row?: NormalizedBudgetRow; error?: string } {
+  const categoryValue = readValue(record, aliases.category);
+  const amountValue = readValue(record, aliases.amount);
+  const category = typeof categoryValue === 'string' ? categoryValue.trim() : String(categoryValue ?? '').trim();
+  const amount = parseNumber(amountValue);
+  const error = validateRow(record, category, amount, sourceRow);
+  if (error) return { error };
+  if (amount === undefined) return { error: `Row ${sourceRow}: amount is missing or not numeric.` };
+  const parentValue = readValue(record, aliases.parent);
+  const parent = typeof parentValue === 'string' ? splitPath(parentValue) : [];
+  const path = [...parent, ...splitPath(category)];
+  const population = parseOptional(record, aliases.population);
+  const priorAmount = parseOptional(record, aliases.priorAmount);
+  const period = stringValue(readValue(record, aliases.period));
+  const currency = stringValue(readValue(record, aliases.currency));
+  return { row: { category: path[path.length - 1] || category, path, amount, population, priorAmount, period, currency, sourceRow } };
+}
+
+function parseOptional(record: RawBudgetRecord, names: string[]): number | undefined {
+  const value = readValue(record, names);
+  return value === undefined || value === null || value === '' ? undefined : parseNumber(value);
+}
+
+function hasInvalidOptional(record: RawBudgetRecord, names: string[]): boolean {
+  const value = readValue(record, names);
+  return value !== undefined && value !== null && value !== '' && parseNumber(value) === undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function parseCsvLine(line: string): string[] {
+  const row: string[] = [];
+  let cell = '';
+  let quoted = false;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    const next = line[index + 1];
+    if (char === '"' && quoted && next === '"') { cell += '"'; index += 1; continue; }
+    if (char === '"') { quoted = !quoted; continue; }
+    if (char === ',' && !quoted) { row.push(cell.trim()); cell = ''; continue; }
+    cell += char;
+  }
+  row.push(cell.trim());
+  return row;
+}
+
+function parseCsvRows(text: string): string[][] {
+  return text.split(/\r?\n/).map(parseCsvLine).filter((row) => row.some(Boolean));
+}
+
+function hasUnclosedQuotes(line: string): boolean {
+  return ((line.match(/"/g) || []).length % 2) === 1;
+}
+
+function recordsFromCsv(text: string): ParsedBudgetText {
+  if (text.split(/\r?\n/).some(hasUnclosedQuotes)) return { format: 'csv', records: [], errors: ['CSV contains an unclosed quoted field.'] };
+  const rows = parseCsvRows(text);
+  if (rows.length < 2) return { format: 'csv', records: [], errors: ['CSV needs a header row and at least one data row.'] };
+  const headers = rows[0] || [];
+  const records = rows.slice(1).map((values) => Object.fromEntries(headers.map((header, index) => [header, values[index] ?? ''])));
+  return { format: 'csv', records, errors: [] };
+}
+
+function recordsFromJson(text: string): ParsedBudgetText {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    const data = Array.isArray(parsed) ? parsed : objectValue(parsed)?.data;
+    if (!Array.isArray(data) || !data.every(isRecord)) return { format: 'json', records: [], errors: ['JSON must be an array of objects or an object with a data array.'] };
+    return { format: 'json', records: data, errors: [] };
+  } catch {
+    return { format: 'json', records: [], errors: ['JSON could not be parsed.'] };
+  }
+}
+
+function objectValue(value: unknown): RawBudgetRecord | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as RawBudgetRecord : undefined;
+}
+
+function isRecord(value: unknown): value is RawBudgetRecord {
+  return Boolean(objectValue(value));
+}
+
+export function parseBudgetText(text: string, format?: 'csv' | 'json'): ParsedBudgetText {
+  const clean = text.trim();
+  if (!clean) return { format: format ?? 'csv', records: [], errors: ['The file is empty.'] };
+  const inferred = format ?? (clean.startsWith('{') || clean.startsWith('[') ? 'json' : 'csv');
+  return inferred === 'json' ? recordsFromJson(clean) : recordsFromCsv(clean);
+}
+
+function uniqueNumbers(rows: NormalizedBudgetRow[], property: 'population' | 'priorAmount'): number[] {
+  return [...new Set(rows.map((row) => row[property]).filter((value): value is number => value !== undefined))];
+}
+
+function groupCategories(rows: NormalizedBudgetRow[], total: number): BudgetCategorySummary[] {
+  const grouped = new Map<string, BudgetCategorySummary>();
+  rows.forEach((row) => {
+    const key = row.path.join(' > ');
+    const current = grouped.get(key) ?? { category: row.category, path: row.path, amount: 0, sourceRows: [] };
+    current.amount += row.amount;
+    if (row.priorAmount !== undefined) current.priorAmount = (current.priorAmount ?? 0) + row.priorAmount;
+    current.sourceRows.push(row.sourceRow);
+    grouped.set(key, current);
+  });
+  return [...grouped.values()].map((category) => ({
+    ...category,
+    share: total > 0 ? category.amount / total : undefined,
+    variation: category.priorAmount !== undefined && category.priorAmount !== 0 ? (category.amount - category.priorAmount) / Math.abs(category.priorAmount) : undefined,
+  })).sort((left, right) => right.amount - left.amount);
+}
+
+function collectWarnings(rows: NormalizedBudgetRow[], categories: BudgetCategorySummary[], total: number): string[] {
+  const warnings: string[] = [];
+  const duplicate = categories.filter((category) => category.sourceRows.length > 1).map((category) => category.path.join(' > '));
+  if (duplicate.length) warnings.push(`Duplicate category paths were grouped: ${duplicate.join(', ')}.`);
+  const populations = uniqueNumbers(rows, 'population');
+  if (populations.length > 1) warnings.push('More than one population denominator was found. Per-capita spending uses the first value and needs review.');
+  if (populations.some((population) => population <= 0)) warnings.push('Population contains a non-positive value, so the denominator needs review.');
+  if (rows.some((row) => row.amount < 0)) warnings.push('Negative amounts are preserved as adjustments but are excluded from the positive visual composition.');
+  if (total <= 0) warnings.push('The total is not positive, so category shares are not shown.');
+  if (rows.some((row) => row.priorAmount === 0)) warnings.push('A zero prior amount has no percentage variation and is shown without a change rate.');
+  if (rows.some((row) => row.path.length > 1)) warnings.push('Nested paths are grouped by the exact path shown in the source data. Check that parent rows are not also counted as child totals.');
+  return warnings;
+}
+
+export function analyzeBudgetRecords(records: RawBudgetRecord[]): BudgetAnalysis {
+  const normalized = records.map((record, index) => normalizeRow(record, index + 2));
+  const errors = normalized.flatMap((result) => result.error ? [result.error] : []);
+  const rows = normalized.flatMap((result) => result.row ? [result.row] : []);
+  const total = rows.reduce((sum, row) => sum + row.amount, 0);
+  const positiveTotal = rows.reduce((sum, row) => sum + (row.amount > 0 ? row.amount : 0), 0);
+  const categories = groupCategories(rows, total);
+  const populations = uniqueNumbers(rows, 'population');
+  const validPopulation = populations.find((value) => value > 0);
+  const previousTotal = rows.some((row) => row.priorAmount !== undefined) ? rows.reduce((sum, row) => sum + (row.priorAmount ?? 0), 0) : undefined;
+  const currencies = [...new Set(rows.map((row) => row.currency).filter(Boolean))];
+  const periods = [...new Set(rows.map((row) => row.period).filter(Boolean))];
+  const warnings = collectWarnings(rows, categories, total);
+  if (currencies.length > 1) warnings.push('More than one currency label was found. Values have not been converted.');
+  if (currencies.some((currency) => !/^[A-Za-z]{3}$/.test(currency || ''))) warnings.push('At least one currency label is not a three-letter code. Values have not been converted.');
+  if (periods.length > 1) warnings.push('More than one period label was found. The first period is shown and the source periods need review.');
+  return { rows, categories, total, positiveTotal, previousTotal, population: validPopulation, perCapita: validPopulation ? total / validPopulation : undefined, variation: previousTotal !== undefined && previousTotal !== 0 ? (total - previousTotal) / Math.abs(previousTotal) : undefined, currency: currencies[0], period: periods[0], warnings, errors };
+}
+
+export function exampleBudgetRecords(): RawBudgetRecord[] {
+  return [
+    { category: 'Education > Schools', amount: 480000, population: 24000, period: '2026', priorAmount: 430000, currency: 'EUR' },
+    { category: 'Health > Clinics', amount: 310000, population: 24000, period: '2026', priorAmount: 290000, currency: 'EUR' },
+    { category: 'Housing', amount: 220000, population: 24000, period: '2026', priorAmount: 250000, currency: 'EUR' },
+    { category: 'Parks', amount: 145000, population: 24000, period: '2026', priorAmount: 130000, currency: 'EUR' },
+    { category: 'Culture', amount: 95000, population: 24000, period: '2026', priorAmount: 90000, currency: 'EUR' },
+  ];
+}