diff --git a/conservancy_beancount/plugin/meta_receivable_documentation.py b/conservancy_beancount/plugin/meta_receivable_documentation.py new file mode 100644 index 0000000000000000000000000000000000000000..e818ff8760d8f1958712ee5410c22880e61cc152 --- /dev/null +++ b/conservancy_beancount/plugin/meta_receivable_documentation.py @@ -0,0 +1,92 @@ +"""meta_receivable_documentation - Validate receivables have supporting docs""" +# Copyright © 2020 Brett Smith +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU Affero General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Affero General Public License for more details. +# +# You should have received a copy of the GNU Affero General Public License +# along with this program. If not, see . + +import re + +from . import core +from .. import config as configmod +from .. import data +from .. import errors as errormod +from ..beancount_types import ( + MetaKey, + Transaction, +) + +from typing import ( + Dict, + Optional, +) + +class MetaReceivableDocumentation(core._RequireLinksPostingMetadataHook): + HOOK_GROUPS = frozenset(['network', 'rt']) + SUPPORTING_METADATA = frozenset([ + 'approval', + 'contract', + 'purchase-order', + ]) + METADATA_KEY = '/'.join(sorted(SUPPORTING_METADATA)) + # Conservancy invoice filenames have followed two patterns. + # The pre-RT pattern: `YYYY-MM-DD_Entity_invoice-YYYYMMDDNN??_as-sent.pdf` + # The RT pattern: `ProjectInvoice-30NNNN??.pdf` + # This regexp matches both, with a little slack to try to reduce the false + # negative rate due to minor renames, etc. + ISSUED_INVOICE_RE = re.compile( + r'[Ii]nvoice[-_ ]*(?:2[0-9]{9,}|30[0-9]+)[A-Za-z]*[-_ .]', + ) + + def __init__(self, config: configmod.Config) -> None: + rt_wrapper = config.rt_wrapper() + # In principle, we could still check for non-RT invoices and enforce + # checks on them without an RT wrapper. In practice, that would + # provide so little utility today it's not worth bothering with. + if rt_wrapper is None: + raise errormod.ConfigurationError("can't log in to RT") + self.rt = rt_wrapper + + def _run_on_post(self, txn: Transaction, post: data.Posting) -> bool: + if not post.account.is_under('Accrued:AccountsReceivable'): + return False + + # Get the first invoice, or return False if it doesn't exist. + try: + invoice_link = post.meta.get_links('invoice')[0] + except (IndexError, TypeError): + return False + + # Get the filename, following an RT link if necessary. + rt_args = self.rt.parse(invoice_link) + if rt_args is not None: + ticket_id, attachment_id = rt_args + invoice_link = self.rt.url(ticket_id, attachment_id) or invoice_link + return self.ISSUED_INVOICE_RE.search(invoice_link) is not None + + def post_run(self, txn: Transaction, post: data.Posting) -> errormod.Iter: + errors: Dict[MetaKey, Optional[errormod.Error]] = { + key: None for key in self.SUPPORTING_METADATA + } + have_support = False + for key in errors: + try: + self._check_links(txn, post, key) + except errormod.Error as key_error: + errors[key] = key_error + else: + have_support = True + for key, error in errors.items(): + if error and not error.message.endswith(f" missing {key}"): + yield error + if not have_support: + yield errormod.InvalidMetadataError(txn, self.METADATA_KEY, None, post) diff --git a/tests/test_meta_receivable_documentation.py b/tests/test_meta_receivable_documentation.py new file mode 100644 index 0000000000000000000000000000000000000000..9dbf6de1cd8a069c1048ae8b0bc0b3ce08ff498d --- /dev/null +++ b/tests/test_meta_receivable_documentation.py @@ -0,0 +1,188 @@ +"""Test metadata for receivables includes supporting documentation""" +# Copyright © 2020 Brett Smith +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU Affero General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Affero General Public License for more details. +# +# You should have received a copy of the GNU Affero General Public License +# along with this program. If not, see . + +import random + +import pytest + +from . import testutil + +from conservancy_beancount import errors as errormod +from conservancy_beancount.plugin import meta_receivable_documentation + +TEST_ACCT = 'Accrued:AccountsReceivable' +OTHER_ACCT = 'Income:Donations' + +SUPPORTING_METADATA = [ + 'approval', + 'contract', + 'purchase-order', +] + +NON_SUPPORTING_METADATA = [ + 'check', + 'receipt', + 'statement', +] + +ISSUED_INVOICE_LINKS = [ + 'rt:1/6', + 'rt://ticket/2/attachments/10', + 'Financial/Invoices/Company_invoice-2020030405_as-sent.pdf', + 'Projects/Alpha/Invoices/ProjectInvoice-304567.pdf', +] + +RECEIVED_INVOICE_LINKS = [ + 'rt:1/4', + 'rt://ticket/2/attachments/14', + 'Financial/Invoices/Invoice-23456789.csv', + 'Projects/Bravo/Invoices/Statement304567.pdf', +] + +MISSING_MSG = f"{TEST_ACCT} missing approval/contract/purchase-order" + +# for supporting links, use the lists from testutil + +@pytest.fixture(scope='module') +def hook(): + config = testutil.TestConfig(rt_client=testutil.RTClient()) + return meta_receivable_documentation.MetaReceivableDocumentation(config) + +def seed_meta(invoice=ISSUED_INVOICE_LINKS[0], + support_values=testutil.NON_LINK_METADATA_STRINGS, + **kwargs, +): + meta = dict(testutil.combine_values( + SUPPORTING_METADATA, + support_values, + )) + meta.update(kwargs) + meta['invoice'] = invoice + return meta + +def wrong_type_message(key, wrong_value): + return "{} has wrong type of {}: expected str but is a {}".format( + TEST_ACCT, + key, + type(wrong_value).__name__, + ) + +def check(hook, expected, test_acct=TEST_ACCT, other_acct=OTHER_ACCT, *, + txn_meta={}, post_meta={}, min_amt=10): + amount = '{:.02f}'.format(min_amt + random.random() * 100) + txn = testutil.Transaction(**txn_meta, postings=[ + (test_acct, amount, post_meta), + (other_acct, f'-{amount}'), + ]) + actual = {error.message for error in hook.run(txn)} + if expected is None: + assert not actual + elif isinstance(expected, str): + assert expected in actual + else: + assert actual == expected + +@pytest.mark.parametrize('invoice,support_key,support_value', testutil.combine_values( + ISSUED_INVOICE_LINKS, + SUPPORTING_METADATA, + testutil.LINK_METADATA_STRINGS, +)) +def test_valid_docs_in_post(hook, invoice, support_key, support_value): + meta = seed_meta(invoice) + meta[support_key] = support_value + check(hook, None, post_meta=meta) + +@pytest.mark.parametrize('invoice,support_key,support_value', testutil.combine_values( + ISSUED_INVOICE_LINKS, + SUPPORTING_METADATA, + testutil.LINK_METADATA_STRINGS, +)) +def test_valid_docs_in_txn(hook, invoice, support_key, support_value): + meta = seed_meta(invoice) + meta[support_key] = support_value + check(hook, None, txn_meta=meta) + +@pytest.mark.parametrize('invoice,meta_type', testutil.combine_values( + ISSUED_INVOICE_LINKS, + ['post_meta', 'txn_meta'], +)) +def test_no_valid_docs(hook, invoice, meta_type): + meta = seed_meta(invoice) + meta.update((key, value) for key, value in testutil.combine_values( + NON_SUPPORTING_METADATA, + testutil.LINK_METADATA_STRINGS, + )) + check(hook, {MISSING_MSG}, **{meta_type: meta}) + +@pytest.mark.parametrize('invoice,meta_type', testutil.combine_values( + ISSUED_INVOICE_LINKS, + ['post_meta', 'txn_meta'], +)) +def test_docs_all_bad_type(hook, invoice, meta_type): + meta = seed_meta(invoice, testutil.NON_STRING_METADATA_VALUES) + expected = { + wrong_type_message(key, value) + for key, value in meta.items() + if key != 'invoice' + } + expected.add(MISSING_MSG) + check(hook, expected, **{meta_type: meta}) + +@pytest.mark.parametrize('invoice,support_key,support_value', testutil.combine_values( + ISSUED_INVOICE_LINKS, + SUPPORTING_METADATA, + testutil.LINK_METADATA_STRINGS, +)) +def test_type_errors_reported_with_valid_post_docs(hook, invoice, support_key, support_value): + meta = seed_meta(invoice, testutil.NON_STRING_METADATA_VALUES) + meta[support_key] = support_value + expected = { + wrong_type_message(key, value) + for key, value in meta.items() + if key != 'invoice' and key != support_key + } + check(hook, expected, post_meta=meta) + +@pytest.mark.parametrize('invoice,support_key,support_value', testutil.combine_values( + ISSUED_INVOICE_LINKS, + SUPPORTING_METADATA, + testutil.LINK_METADATA_STRINGS, +)) +def test_type_errors_reported_with_valid_txn_docs(hook, invoice, support_key, support_value): + meta = seed_meta(invoice, testutil.NON_STRING_METADATA_VALUES) + meta[support_key] = support_value + expected = { + wrong_type_message(key, value) + for key, value in meta.items() + if key != 'invoice' and key != support_key + } + check(hook, expected, txn_meta=meta) + +@pytest.mark.parametrize('invoice,meta_type', testutil.combine_values( + RECEIVED_INVOICE_LINKS, + ['post_meta', 'txn_meta'], +)) +def test_received_invoices_not_checked(hook, invoice, meta_type): + check(hook, None, **{meta_type: {'invoice': invoice}}) + +def test_does_not_apply_to_payables(hook): + meta = seed_meta() + check(hook, None, 'Accrued:AccountsPayable', 'Expenses:Other', post_meta=meta) + +def test_configuration_error_without_rt(): + config = testutil.TestConfig() + with pytest.raises(errormod.ConfigurationError): + meta_receivable_documentation.MetaReceivableDocumentation(config) diff --git a/tests/test_rtutil.py b/tests/test_rtutil.py index 0ca15fe9af646d972c5571275663395d9032adce..c57bf40e17fd93d920f425b756d38617cbd0b306 100644 --- a/tests/test_rtutil.py +++ b/tests/test_rtutil.py @@ -30,7 +30,7 @@ EXPECTED_URLS = [ (1, 4, 'Ticket/Attachment/1/4/Forwarded%20Message.eml'), (1, 99, None), (2, 1, None), - (2, 10, 'Ticket/Attachment/7/10/screenshot.png'), + (2, 10, 'Ticket/Attachment/7/10/Company_invoice-2020030405_as-sent.pdf'), (2, 13, 'Ticket/Display.html?id=2#txn-11'), (2, 14, 'Ticket/Display.html?id=2#txn-11'), # statement.txt (3, None, 'Ticket/Display.html?id=3'), diff --git a/tests/testutil.py b/tests/testutil.py index 4e06dc439452ad95c31884f00dd47a4da18ed6be..cb6fc1b384936b5a21b0f8cf93a12b1121935e15 100644 --- a/tests/testutil.py +++ b/tests/testutil.py @@ -179,9 +179,10 @@ class _TicketBuilder: MISC_ATTACHMENTS = [ ('Forwarded Message.eml', 'message/rfc822', '3.1k'), ('photo.jpg', 'image/jpeg', '65.2k'), - ('document.pdf', 'application/pdf', '326k'), - ('screenshot.png', 'image/png', '1.9m'), + ('ConservancyInvoice-301.pdf', 'application/pdf', '326k'), + ('Company_invoice-2020030405_as-sent.pdf', 'application/pdf', '50k'), ('statement.txt', 'text/plain', '652b'), + ('screenshot.png', 'image/png', '1.9m'), ] def __init__(self):