@actual-app/core 26.3.0

package/src/server/budget/template-notes.test.ts

@@ -0,0 +1,393 @@
+import type { Template } from '../../types/models/templates';
+import * as db from '../db';
+
+import { parse } from './goal-template.pegjs';
+import {
+  getActiveSchedules,
+  getCategoriesWithTemplateNotes,
+  resetCategoryGoalDefsWithNoTemplates,
+} from './statements';
+import type { CategoryWithTemplateNote } from './statements';
+import {
+  checkTemplateNotes,
+  storeNoteTemplates,
+  unparse,
+} from './template-notes';
+
+vi.mock('../db');
+vi.mock('./statements');
+
+function mockGetTemplateNotesForCategories(
+  templateNotes: CategoryWithTemplateNote[],
+) {
+  vi.mocked(getCategoriesWithTemplateNotes).mockResolvedValue(templateNotes);
+}
+
+function mockGetActiveSchedules(schedules: db.DbSchedule[]) {
+  vi.mocked(getActiveSchedules).mockResolvedValue(schedules);
+}
+
+function mockDbUpdate() {
+  vi.mocked(db.updateWithSchema).mockResolvedValue(undefined);
+}
+
+describe('storeNoteTemplates', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const testCases = [
+    {
+      description: 'Stores templates for categories with valid template notes',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#template 10',
+        },
+      ],
+      expectedTemplates: [
+        {
+          type: 'simple',
+          monthly: 10,
+          limit: null,
+          priority: 0,
+          directive: 'template',
+        },
+      ],
+    },
+    {
+      description:
+        'Stores negative templates for categories with valid template notes',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#template -103.23',
+        },
+      ],
+      expectedTemplates: [
+        {
+          type: 'simple',
+          monthly: -103.23,
+          limit: null,
+          priority: 0,
+          directive: 'template',
+        },
+      ],
+    },
+    {
+      description:
+        'Stores template when prefix is used with valid template notes',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: 'test: #template 12',
+        },
+      ],
+      expectedTemplates: [
+        {
+          type: 'simple',
+          monthly: 12,
+          limit: null,
+          priority: 0,
+          directive: 'template',
+        },
+      ],
+    },
+    {
+      description:
+        'Stores templates for categories with valid goal directive template notes',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#goal 10',
+        },
+      ],
+      expectedTemplates: [
+        {
+          type: 'goal',
+          amount: 10,
+          priority: null,
+          directive: 'goal',
+        },
+      ],
+    },
+    {
+      description: 'Does not store empty template notes',
+      mockTemplateNotes: [{ id: 'cat1', name: 'Category 1', note: '' }],
+      expectedTemplates: [],
+    },
+    {
+      description: 'Does not store non template notes',
+      mockTemplateNotes: [
+        { id: 'cat1', name: 'Category 1', note: 'Not a template note' },
+      ],
+      expectedTemplates: [],
+    },
+  ];
+
+  it.each(testCases)(
+    '$description',
+    async ({ mockTemplateNotes, expectedTemplates }) => {
+      // Given
+      mockGetTemplateNotesForCategories(mockTemplateNotes);
+      mockDbUpdate();
+
+      // When
+      await storeNoteTemplates();
+
+      // Then
+      if (expectedTemplates.length === 0) {
+        expect(db.updateWithSchema).not.toHaveBeenCalled();
+        expect(resetCategoryGoalDefsWithNoTemplates).toHaveBeenCalled();
+        return;
+      }
+
+      mockTemplateNotes.forEach(({ id }) => {
+        expect(db.updateWithSchema).toHaveBeenCalledWith('categories', {
+          id,
+          goal_def: JSON.stringify(expectedTemplates),
+          template_settings: { source: 'notes' },
+        });
+      });
+      expect(resetCategoryGoalDefsWithNoTemplates).toHaveBeenCalled();
+    },
+  );
+});
+
+describe('checkTemplates', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const testCases = [
+    {
+      description: 'Returns success message when templates pass',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#template 10',
+        },
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#template schedule Mock Schedule 1',
+        },
+      ],
+      mockSchedules: mockSchedules(),
+      expected: {
+        type: 'message',
+        message: 'All templates passed! 🎉',
+      },
+    },
+    {
+      description: 'Skips notes that are not templates',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: 'Not a template note',
+        },
+      ],
+      mockSchedules: mockSchedules(),
+      expected: {
+        type: 'message',
+        message: 'All templates passed! 🎉',
+      },
+    },
+    {
+      description: 'Returns errors for templates with parsing errors',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#template broken template',
+        },
+      ],
+      mockSchedules: mockSchedules(),
+      expected: {
+        sticky: true,
+        message: 'There were errors interpreting some templates:',
+        pre: 'Category 1: #template broken template',
+      },
+    },
+    {
+      description: 'Returns errors for non-existent schedules',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#template schedule Non-existent Schedule',
+        },
+      ],
+      mockSchedules: mockSchedules(),
+      expected: {
+        sticky: true,
+        message: 'There were errors interpreting some templates:',
+        pre: 'Category 1: Schedule "Non-existent Schedule" does not exist',
+      },
+    },
+    {
+      description: 'Returns errors for invalid increase schedule adjustments',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#template schedule Mock Schedule 1 [increase 1001%]',
+        },
+      ],
+      mockSchedules: mockSchedules(),
+      expected: {
+        sticky: true,
+        message: 'There were errors interpreting some templates:',
+        pre: 'Category 1: #template schedule Mock Schedule 1 [increase 1001%]\nError: Invalid adjustment percentage (1001%). Must be between -100% and 1000%',
+      },
+    },
+    {
+      description: 'Returns errors for invalid decrease schedule adjustments',
+      mockTemplateNotes: [
+        {
+          id: 'cat1',
+          name: 'Category 1',
+          note: '#template schedule Mock Schedule 1 [decrease 101%]',
+        },
+      ],
+      mockSchedules: mockSchedules(),
+      expected: {
+        sticky: true,
+        message: 'There were errors interpreting some templates:',
+        pre: 'Category 1: #template schedule Mock Schedule 1 [decrease 101%]\nError: Invalid adjustment percentage (-101%). Must be between -100% and 1000%',
+      },
+    },
+  ];
+
+  it.each(testCases)(
+    '$description',
+    async ({ mockTemplateNotes, mockSchedules, expected }) => {
+      // Given
+      mockGetTemplateNotesForCategories(mockTemplateNotes);
+      mockGetActiveSchedules(mockSchedules);
+
+      // When
+      const result = await checkTemplateNotes();
+
+      // Then
+      expect(result).toEqual(expected);
+    },
+  );
+});
+
+function mockSchedules(): db.DbSchedule[] {
+  return [
+    {
+      id: 'mock-schedule-1',
+      rule: 'mock-rule',
+      active: 1,
+      completed: 0,
+      posts_transaction: 0,
+      tombstone: 0,
+      name: 'Mock Schedule 1',
+    },
+    {
+      id: 'mock-schedule-2',
+      rule: 'mock-rule',
+      active: 1,
+      completed: 0,
+      posts_transaction: 0,
+      tombstone: 0,
+      name: 'Mock Schedule 2',
+    },
+  ];
+}
+
+describe('unparse/parse round-trip', () => {
+  const cases: string[] = [
+    // simple
+    '#template 10',
+    '#template up to 50',
+    '#template up to 25 per day hold',
+    '#template up to 100 per week starting 2025-01-01',
+    '#template-2 123.45',
+    // schedule
+    '#template schedule Rent',
+    '#template schedule full Mortgage',
+    '#template schedule Netflix [increase 10%]',
+    '#template schedule full Groceries [decrease 5%]',
+    // percentage
+    '#template 50% of Utilities',
+    '#template 75% of previous Dining Out',
+    // periodic
+    '#template 200 repeat every 2 months starting 2025-06-01',
+    '#template 300 repeat every week starting 2025-01-07',
+    '#template 400 repeat every year starting 2025-01-01 up to 50',
+    // by / spend
+    '#template 500 by 2025-12',
+    '#template 600 by 2025-11 repeat every month',
+    '#template 700 by 2025-10 repeat every 2 months',
+    '#template 800 by 2025-09 repeat every year',
+    '#template 900 by 2025-08 repeat every 3 years',
+    '#template 1000 by 2025-07 spend from 2025-01 repeat every month',
+    '#template 1100 by 2025-06 spend from 2025-02 repeat every 2 months',
+    // remainder
+    '#template remainder',
+    '#template remainder 2',
+    '#template remainder 3 up to 10',
+    // average
+    '#template average 6 months',
+    '#template-5 average 12 months',
+    // copy
+    '#template copy from 3 months ago',
+    '#template copy from 6 months ago',
+    // goal
+    '#goal 1234',
+  ];
+
+  it.each(cases)('round-trips: %s', async original => {
+    const parsed: Template = parse(original);
+    const serialized = await unparse([parsed]);
+    const reparsed: Template = parse(serialized);
+
+    expect(parsed).toEqual(reparsed);
+  });
+});
+
+describe('unparse limit templates', () => {
+  it('serializes refill limits to notes syntax', async () => {
+    const serialized = await unparse([
+      {
+        type: 'limit',
+        amount: 150,
+        hold: false,
+        period: 'monthly',
+        directive: 'template',
+        priority: null,
+      },
+      {
+        type: 'refill',
+        directive: 'template',
+        priority: 2,
+      },
+    ]);
+
+    expect(serialized).toBe('#template-2 up to 150');
+  });
+
+  it('serializes non-refill limits with a zero base amount', async () => {
+    const serialized = await unparse([
+      {
+        type: 'limit',
+        amount: 200,
+        hold: false,
+        period: 'monthly',
+        directive: 'template',
+        priority: null,
+      },
+    ]);
+
+    expect(serialized).toBe('#template 0 up to 200');
+  });
+});

package/src/server/budget/template-notes.ts

@@ -0,0 +1,323 @@
+import type { Template } from '../../types/models/templates';
+
+import { storeTemplates } from './goal-template';
+import { parse } from './goal-template.pegjs';
+import {
+  getActiveSchedules,
+  getCategoriesWithTemplateNotes,
+  resetCategoryGoalDefsWithNoTemplates,
+} from './statements';
+import type { CategoryWithTemplateNote } from './statements';
+
+type Notification = {
+  type?: 'message' | 'error' | 'warning' | undefined;
+  pre?: string | undefined;
+  message: string;
+  sticky?: boolean | undefined;
+};
+
+export const TEMPLATE_PREFIX = '#template';
+export const GOAL_PREFIX = '#goal';
+
+export async function storeNoteTemplates(): Promise<void> {
+  const categoriesWithTemplates = await getCategoriesWithTemplates();
+
+  await storeTemplates({ categoriesWithTemplates, source: 'notes' });
+
+  await resetCategoryGoalDefsWithNoTemplates();
+}
+
+type CategoryWithTemplateNotes = {
+  id: string;
+  name: string;
+  templates: Template[];
+};
+
+export async function checkTemplateNotes(): Promise<Notification> {
+  const categoryWithTemplates = await getCategoriesWithTemplates();
+  const schedules = await getActiveSchedules();
+  const scheduleNames = schedules.map(({ name }) => name);
+  const errors: string[] = [];
+
+  categoryWithTemplates.forEach(({ name, templates }) => {
+    templates.forEach(template => {
+      if (template.type === 'error') {
+        // Only show detailed error for adjustment-related errors
+        if (template.error && template.error.includes('adjustment')) {
+          errors.push(`${name}: ${template.line}\nError: ${template.error}`);
+        } else {
+          errors.push(`${name}: ${template.line}`);
+        }
+      } else if (
+        template.type === 'schedule' &&
+        !scheduleNames.includes(template.name)
+      ) {
+        errors.push(`${name}: Schedule "${template.name}" does not exist`);
+      }
+    });
+  });
+
+  if (errors.length) {
+    return {
+      sticky: true,
+      message: 'There were errors interpreting some templates:',
+      pre: errors.join('\n\n'),
+    };
+  }
+
+  return {
+    type: 'message',
+    message: 'All templates passed! 🎉',
+  };
+}
+
+async function getCategoriesWithTemplates(): Promise<
+  CategoryWithTemplateNotes[]
+> {
+  const templatesForCategory: CategoryWithTemplateNotes[] = [];
+  const templateNotes = await getCategoriesWithTemplateNotes();
+
+  templateNotes.forEach(({ id, name, note }: CategoryWithTemplateNote) => {
+    if (!note) {
+      return;
+    }
+
+    const parsedTemplates: Template[] = [];
+
+    note.split('\n').forEach(line => {
+      const trimmedLine = line.substring(line.indexOf('#')).trim();
+
+      if (
+        !trimmedLine.startsWith(TEMPLATE_PREFIX) &&
+        !trimmedLine.startsWith(GOAL_PREFIX)
+      ) {
+        return;
+      }
+
+      try {
+        const parsedTemplate: Template = parse(trimmedLine);
+
+        // Validate schedule adjustments
+        if (
+          (parsedTemplate.type === 'average' ||
+            parsedTemplate.type === 'schedule') &&
+          parsedTemplate.adjustment !== undefined
+        ) {
+          if (parsedTemplate.adjustmentType === 'percent') {
+            if (
+              parsedTemplate.adjustment <= -100 ||
+              parsedTemplate.adjustment > 1000
+            ) {
+              throw new Error(
+                `Invalid adjustment percentage (${parsedTemplate.adjustment}%). Must be between -100% and 1000%`,
+              );
+            }
+          } else if (parsedTemplate.adjustmentType === 'fixed') {
+            //placeholder for potential validation of amount/fixed adjustments
+          }
+        }
+
+        parsedTemplates.push(parsedTemplate);
+      } catch (e: unknown) {
+        parsedTemplates.push({
+          type: 'error',
+          directive: 'error',
+          line,
+          error: (e as Error).message,
+        });
+      }
+    });
+
+    if (!parsedTemplates.length) {
+      return;
+    }
+
+    templatesForCategory.push({
+      id,
+      name,
+      templates: parsedTemplates,
+    });
+  });
+
+  return templatesForCategory;
+}
+
+function prefixFromPriority(priority: number | null): string {
+  return priority === null ? TEMPLATE_PREFIX : `${TEMPLATE_PREFIX}-${priority}`;
+}
+
+export async function unparse(templates: Template[]): Promise<string> {
+  // Refill will be merged into the limit template if both exist
+  // Assumption: at most one limit and one refill template per category
+  const refill = templates.find(t => t.type === 'refill');
+  const withoutRefill = templates.filter(t => t.type !== 'refill');
+
+  return withoutRefill
+    .flatMap(template => {
+      if (template.type === 'error') {
+        return [];
+      }
+
+      if (template.type === 'goal') {
+        return `${GOAL_PREFIX} ${template.amount}`;
+      }
+
+      const prefix = prefixFromPriority(template.priority);
+
+      switch (template.type) {
+        case 'simple': {
+          // Simple template syntax: #template[-prio] simple [monthly N] [limit]
+          let result = prefix;
+          if (template.monthly != null) {
+            result += ` ${template.monthly}`;
+          }
+          if (template.limit) {
+            result += ` ${limitToString(template.limit)}`;
+          }
+          return result.trim();
+        }
+        case 'schedule': {
+          // schedule syntax: #template[-prio] schedule <name> [full] [ [increase/decrease N%] ]
+          let result = `${prefix} schedule`;
+          if (template.full) {
+            result += ' full';
+          }
+          result += ` ${template.name}`;
+          if (template.adjustment !== undefined) {
+            const adj = template.adjustment;
+            const op = adj >= 0 ? 'increase' : 'decrease';
+            const val = Math.abs(adj);
+            const type = template.adjustmentType === 'percent' ? '%' : '';
+            result += ` [${op} ${val}${type}]`;
+          }
+          return result;
+        }
+        case 'percentage': {
+          // #template[-prio] <percent>% of [previous ]<category>
+          const prev = template.previous ? 'previous ' : '';
+          return `${prefix} ${trimTrailingZeros(template.percent)}% of ${prev}${template.category}`.trim();
+        }
+        case 'periodic': {
+          // #template[-prio] <amount> repeat every <n> <period>(s) starting <date> [limit]
+          const periodPart = periodToString(template.period);
+          let result = `${prefix} ${template.amount} repeat every ${periodPart} starting ${template.starting}`;
+          if (template.limit) {
+            result += ` ${limitToString(template.limit)}`;
+          }
+          return result;
+        }
+        case 'by':
+        case 'spend': {
+          // #template[-prio] <amount> by <month> [spend from <month>] [repeat every <...>]
+          let result = `${prefix} ${template.amount} by ${template.month}`;
+          if (template.type === 'spend' && template.from) {
+            result += ` spend from ${template.from}`;
+          }
+          // repeat info
+          if (template.annual !== undefined) {
+            const repeatInfo = repeatToString(template.annual, template.repeat);
+            if (repeatInfo) {
+              result += ` repeat every ${repeatInfo}`;
+            }
+          }
+          return result;
+        }
+        case 'remainder': {
+          // #template remainder [weight] [limit]
+          let result = `${prefix} remainder`;
+          if (template.weight !== undefined && template.weight !== 1) {
+            result += ` ${template.weight}`;
+          }
+          if (template.limit) {
+            result += ` ${limitToString(template.limit)}`;
+          }
+          return result;
+        }
+        case 'average': {
+          let result = `${prefix} average ${template.numMonths} months`;
+
+          if (template.adjustment !== undefined) {
+            const adj = template.adjustment;
+            const op = adj >= 0 ? 'increase' : 'decrease';
+            const val = Math.abs(adj);
+            const type = template.adjustmentType === 'percent' ? '%' : '';
+            result += ` [${op} ${val}${type}]`;
+          }
+
+          // #template average <numMonths> months [increase/decrease {number|number%}]
+          return result;
+        }
+        case 'copy': {
+          // #template copy from <lookBack> months ago [limit]
+          const result = `${prefix} copy from ${template.lookBack} months ago`;
+          return result;
+        }
+        case 'limit': {
+          if (!refill) {
+            // #template 0 up to <limit>
+            return `${prefix} 0 ${limitToString(template)}`;
+          }
+          // #template up to <limit>
+          const mergedPrefix = prefixFromPriority(refill.priority);
+          return `${mergedPrefix} ${limitToString(template)}`;
+        }
+        // No 'refill' support since a refill requires a limit
+        default:
+          return [];
+      }
+    })
+    .join('\n');
+}
+
+function limitToString(limit: {
+  amount: number;
+  hold: boolean;
+  period?: 'daily' | 'weekly' | 'monthly';
+  start?: string | undefined;
+}): string {
+  switch (limit.period) {
+    case 'weekly': {
+      // Needs start date per grammar
+      const base = `up to ${limit.amount} per week starting ${limit.start}`;
+      return limit.hold ? `${base} hold` : base;
+    }
+    case 'daily': {
+      const base = `up to ${limit.amount} per day`;
+      return limit.hold ? `${base} hold` : base;
+    }
+    case 'monthly':
+    default: {
+      const base = `up to ${limit.amount}`;
+      return limit.hold ? `${base} hold` : base;
+    }
+  }
+}
+
+function periodToString(p: {
+  period: 'day' | 'week' | 'month' | 'year';
+  amount: number;
+}): string {
+  const { period, amount } = p;
+  if (amount === 1) {
+    return period; // singular
+  }
+  // pluralize simple
+  return `${amount} ${period}s`;
+}
+
+function repeatToString(annual?: boolean, repeat?: number): string | null {
+  if (annual === undefined) return null;
+  if (annual) {
+    if (!repeat || repeat === 1) return 'year';
+    return `${repeat} years`;
+  }
+  // monthly
+  if (!repeat || repeat === 1) return 'month';
+  return `${repeat} months`;
+}
+
+function trimTrailingZeros(n: number): string {
+  const s = n.toString();
+  if (!s.includes('.')) return s;
+  return s.replace(/\.0+$/, '').replace(/(\.[0-9]*[1-9])0+$/, '$1');
+}