Contributing

Contributing

Contributions are welcome: fixtures, decoded codes, documentation, accessibility, CLI features and new providers. Start with CONTRIBUTING.md and the issues labelled good first issue.

Development

pnpm install
pnpm build:packages
pnpm test          # unit and property tests
pnpm typecheck
pnpm lint
pnpm build:pages && pnpm --filter @pandapaylens/pages run test:e2e

Pull requests run CI (tests, type checks, lint, formatting, builds and end-to-end tests) and CodeQL.

Ground rules

• Local-first. No network, storage, eval or dynamic code in the engine, adapters or rules.
• No invented data. Codes, statuses and formats come from official provider documentation, with the source linked. Unknown stays unknown.
• Honest capabilities. A capability is supported only when it is implemented and tested.
• Synthetic fixtures only. Identifiers contain PPLsynth. Never commit real card, customer or merchant data.
• No identifiers in finding texts. Refer to evidence by event id so masking works.
• Plain hyphens. Use "-" in text, not long dashes.

Adding a provider

1. Open a "New provider" issue with links to the provider's official developer documentation.
2. Write the research notes (sources, formats, codes, lifecycle, identifiers, limitations).
3. Implement the adapter in packages/adapters/<id> following add-provider.md and the adapter implementation rules.
4. Add synthetic fixtures and tests: success, decline, validation error, timeout or unknown outcome, notification, duplicate, missing fields, malformed input, unknown code, grouping, redaction, and no false detection on other providers' fixtures.
5. Register it in packages/providers and add one or two examples to fixtures/samples.json.

Improving an existing adapter

• Add a missing documented code to the adapter's catalog.ts, with its documentation link and a test.
• Add a fixture for a documented case that is not covered yet.
• If a provider page lists a limitation you can remove with documented information, that is a great contribution.

Reporting problems

• Wrong analysis: open a bug with the masked Markdown export, never the raw payload.
• Security issue: use private vulnerability reporting (see Privacy and Security).