Report a bug

Use the GitHub issue tracker to report bugs or unexpected behaviour.

Before opening an issue

  1. Check that ClamAV is installed and clamscan --version works.
  2. Run freshclam to rule out stale definitions.
  3. Search existing issues for the same problem.

What to include in a bug report

  • Operating system and version (e.g. Ubuntu 22.04, macOS 14.4).
  • Node.js version: node --version
  • pompelmi version: npm list pompelmi
  • ClamAV version: clamscan --version
  • The exact error message or unexpected output.
  • A minimal code example that reproduces the problem.
Do not include real malicious files or samples in issue reports. If you need to demonstrate a malicious detection, use the EICAR test file.

Contributing

Contributions are welcome. The project is kept intentionally small. Please read the following before submitting a pull request.

Getting started

git clone https://github.com/pompelmi/pompelmi.git
cd pompelmi
npm install

Running tests

npm test

Unit tests run without ClamAV — they mock cross-spawn using Node's built-in node:test runner. Integration tests scan real EICAR files and are skipped automatically if clamscan is not found in PATH.

Linting

npm run lint

The project uses ESLint with the @eslint/js recommended ruleset. Fix all lint errors before submitting a PR.

What is in scope

  • Bug fixes in ClamAVScanner.js.
  • Improved error messages.
  • Test coverage improvements.
  • Documentation corrections.
  • TypeScript declaration file (.d.ts).

What is out of scope

  • Adding a clamd daemon connection. This would be a separate package.
  • Streaming / buffer scanning. Out of scope for v1.
  • Recursive directory scanning. Out of scope for v1.
  • Switching the dependency from cross-spawn to something else without a strong reason.

Pull request guidelines

  • One logical change per PR.
  • Include a test for any changed behaviour.
  • Do not bump package.json version in a PR; that is done at release time.
  • Describe what the PR does and why in the PR body.

License

pompelmi is released under the ISC License. 

ISC License

Copyright (c) 2024 pompelmi contributors

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.