fix: improve error message for wrongly formatted history files

[Bhavysinghal]

Fixes #1184

What this does

When a history file is formatted incorrectly (using {} object instead
of [] array), the engine previously threw a confusing error:
"serviceHistory(termsType) push is not a function"

This change adds a validation check that throws a clear, human-readable
error message instead, telling the contributor exactly what is wrong and
how to fix it.

Why

As reported in issue #1184, this confusing error message caused confusion
for contributors. A clear error message will help future contributors
immediately understand and fix their mistake.

[MattiSG]

Hi @Bhavysinghal and thank you for this contribution!
We will take the time to make a full review whenever possible. In the meantime, I have done a quick review and confirmed there is no risk in running tests. The automated tests will now run. In order to proceed with the content review, please make sure to address any issues spotted by our bots 🙂

[Bhavysinghal]

Hi @MattiSG! I've addressed the bot issues:

• Fixed the commit message to follow the project's commitlint rules (sentence-case, no type prefix, under 50 characters)
• Added an entry to CHANGELOG.md under the ## Unreleased section

The remaining test failures appear to be pre-existing CI infrastructure issues related to Puppeteer/Chrome not being available in the CI environment, and seem unrelated to this change. Please let me know if anything else needs to be addressed!

[Bhavysinghal]

Hi @MattiSG! I've addressed the bot issues:

• Fixed the commit message to follow the project's commitlint rules (sentence-case, no type prefix, under 50 characters)
• Added an entry to CHANGELOG.md under ## Unreleased [patch], including the required volunteer contribution notice as per CONTRIBUTING.md

The remaining test failures (Test, validate_declarations) appear to be pre-existing CI infrastructure issues related to Puppeteer/Chrome not being available in the CI environment, and seem unrelated to this change.

The latest commit also needs workflow approval to run — could you please approve it when you have a moment? Thanks again for your guidance! 🙂

[MattiSG]

Hey @Bhavysinghal, thank you for handling these! And thank you for having handled even the changelog. Don't sweat it if there are further problems on that part, we'll take care of the changelog bit 🙂

Sorry for not having re-run workflows, I thought once approved they'd run automatically again.

I agree with you that the errors outlining a missing browser are not related to your changes. We'll need to investigate that further.

@Ndpnt do you think the CI failures could be related to GitHub Actions safety for third party forks?

[Ndpnt]

@MattiSG Nope, these failures are not related to this PR. They’re directly tied to Puppeteer. Rebasing this branch onto the latest engine version (13.0.0) should fix the issue.

[MattiSG]

Thank you @Ndpnt for your quick reply!

@Bhavysinghal are you comfortable with a rebase, or would you need assistance for that?

[Bhavysinghal]

Hi @MattiSG! I've rebased the branch onto v13.0.0 as suggested by @Ndpnt.
Please let me know if anything else is needed!

[MattiSG]

Thank you @Bhavysinghal! You're all good on your side at this stage 🙂
We'll now proceed with testing functionality and will then review.

[MattiSG]

This works perfectly!

Tested locally, with:

1. No history file: no change.
2. Properly formatted history file: no change.
3. Improperly formatted history file: the error message changes, see below.

engine [main]
› npm run declarations:validate

> @opentermsarchive/engine@13.0.0 declarations:validate
> node bin/ota.js validate declarations


  1) Uncaught error outside test suite

  0 passing (1ms)
  1 failing

  1) Uncaught error outside test suite:
     Uncaught TypeError: serviceHistory[termsType].push is not a function

→

engine [pr]
› npm run declarations:validate

> @opentermsarchive/engine@13.0.0 declarations:validate
> node bin/ota.js validate declarations


  1) Uncaught error outside test suite

  0 passing (1ms)
  1 failing

  1) Uncaught error outside test suite:
     Uncaught Error: History file for "Terms of Service" is not properly formatted: expected an array but got an object. Please use [] instead of {}.

[MattiSG]

Thank you very much @Bhavysinghal for your contribution and your patience through this process! We are glad to see this improvement land in main, the history file is one of the harder aspects of working with Open Terms Archive and we regularly received questions regarding that error. This will hopefully ease the contribution process!

@all-contributors add @Bhavysinghal for code

[Bhavysinghal]

Thank you so much @MattiSG for your guidance throughout this process!
Really happy to see this land in main and be added as a contributor.
Looking forward to contributing more! 🙂