pompelmi 1.1.0 → 1.2.0

package/.claude/settings.local.json

@@ -39,7 +39,9 @@
       "Bash(node --test test/unit.test.js)",
       "Bash(echo \"exit:$?\")",
       "Read(//tmp/**)",
-      "Bash(tee /Users/tommy/pompelmi/pompelmi/test_out.txt)"
+      "Bash(tee /Users/tommy/pompelmi/pompelmi/test_out.txt)",
+      "Bash(npm install:*)",
+      "Bash(npm ls:*)"
     ]
   }
 }

package/README.md

@@ -15,7 +15,7 @@
 
 ---
 
-A minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that scans any file and returns a plain string: `"Clean"`, `"Malicious"`, or `"ScanError"`. No daemons. No cloud. No native bindings.
+A minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that scans any file and returns a typed `Verdict` Symbol: `Verdict.Clean`, `Verdict.Malicious`, or `Verdict.ScanError`. No daemons. No cloud. No native bindings. Zero runtime dependencies.
 
 ## Table of contents
 
@@ -43,12 +43,11 @@ npm install pompelmi
 ```
 
 ```js
-const pompelmi = require('pompelmi');
+const { scan, Verdict } = require('pompelmi');
 
-const result = await pompelmi.scan('/path/to/file.zip');
-// "Clean" | "Malicious" | "ScanError"
+const result = await scan('/path/to/file.zip');
 
-if (result === 'Malicious') {
+if (result === Verdict.Malicious) {
   throw new Error('File rejected: malware detected');
 }
 ```
@@ -66,21 +65,26 @@ No stdout parsing. No regex. No surprises.
 ### `pompelmi.scan(filePath, [options])`
 
 ```ts
-pompelmi.scan(filePath: string, options?: { host?: string; port?: number; timeout?: number }): Promise<"Clean" | "Malicious" | "ScanError">
+scan(filePath: string, options?: { host?: string; port?: number; timeout?: number }): Promise<symbol>
+// resolves to one of: Verdict.Clean | Verdict.Malicious | Verdict.ScanError
 ```
 
 | Parameter  | Type     | Description                             |
 |------------|----------|-----------------------------------------|
 | `filePath` | `string` | Absolute or relative path to the file. |
-| `options`  | `object` | Optional. Omit to use the local `clamscan` CLI. Pass `host` / `port` to scan via a clamd TCP socket instead. See [docs/api.md](./docs/api.md) for the full reference. |
+| `options`  | `object` | Optional. Omit to use the local `clamscan` CLI. Pass `host` / `port` to scan via a clamd TCP socket instead. See [docs/api.html](./docs/api.html) for the full reference. |
 
 **Resolves** to one of:
 
-| Result        | ClamAV exit code | Meaning                                                                                              |
-|---------------|:---:|------------------------------------------------------------------------------------------------------|
-| `"Clean"`     |  0  | No threats found.                                                                                    |
-| `"Malicious"` |  1  | A known virus or malware signature was matched.                                                      |
-| `"ScanError"` |  2  | The scan itself failed (I/O error, encrypted archive, permission denied). File status is unknown — treat as untrusted. |
+| Result             | ClamAV exit code | Meaning                                                                                              |
+|--------------------|:---:|------------------------------------------------------------------------------------------------------|
+| `Verdict.Clean`     |  0  | No threats found.                                                                                    |
+| `Verdict.Malicious` |  1  | A known virus or malware signature was matched.                                                      |
+| `Verdict.ScanError` |  2  | The scan itself failed (I/O error, encrypted archive, permission denied). File status is unknown — treat as untrusted. |
+
+> **Reading the verdict as a string** — each Verdict Symbol carries a `.description` property
+> (`Verdict.Clean.description === 'Clean'`) for logging or serialisation without comparing against
+> raw strings in application logic.
 
 **Rejects** with an `Error` in these cases:
 
@@ -95,20 +99,20 @@ pompelmi.scan(filePath: string, options?: { host?: string; port?: number; timeou
 **Example — full error handling:**
 
 ```js
-const pompelmi = require('pompelmi');
+const { scan, Verdict } = require('pompelmi');
 const path = require('path');
 
 async function safeScan(filePath) {
   try {
-    const result = await pompelmi.scan(path.resolve(filePath));
+    const result = await scan(path.resolve(filePath));
 
-    if (result === 'ScanError') {
+    if (result === Verdict.ScanError) {
       // The scan could not complete — treat the file as untrusted.
       console.warn('Scan incomplete, rejecting file as precaution.');
       return null;
     }
 
-    return result; // "Clean" or "Malicious"
+    return result; // Verdict.Clean or Verdict.Malicious
   } catch (err) {
     console.error('Scan failed:', err.message);
     return null;
@@ -200,7 +204,7 @@ npm test
 
 The test suite has two parts:
 
-- **Unit tests** (`test/unit.test.js`) — run with Node's built-in test runner. Mock `cross-spawn` and platform dependencies; no ClamAV installation required.
+- **Unit tests** (`test/unit.test.js`) — run with Node's built-in test runner. Mock `nativeSpawn` from `src/spawn.js` and platform dependencies via require-cache injection; no ClamAV installation required.
 - **Integration tests** (`test/scan.test.js`) — spawn real `clamscan` processes against EICAR test files. Skipped automatically if `clamscan` is not found in PATH.
 
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "ClamAV for humans — scan any file and get back Clean, Malicious, or ScanError. No daemons. No cloud. No native bindings.",
   "license": "ISC",
   "author": "pompelmi contributors",
@@ -27,9 +27,7 @@
     "test": "node --test test/unit.test.js && node test/scan.test.js",
     "lint": "eslint src/"
   },
-  "dependencies": {
-    "cross-spawn": "^7.0.6"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.2.0",

package/src/ClamAVDatabaseUpdater.js

@@ -1,4 +1,4 @@
-const spawn = require("cross-spawn");
+const { nativeSpawn: spawn } = require('./spawn.js');
 const fs = require("fs");
 const { getUpdaterCommand } = require('./InstallerCommand.js');
 const { PLATFORM } = require('./constants.js');

package/src/ClamAVInstaller.js

@@ -1,4 +1,4 @@
-const spawn = require("cross-spawn");
+const { nativeSpawn: spawn } = require('./spawn.js');
 const { execSync } = require("child_process");
 const { getInstallerCommand } = require('./InstallerCommand.js');
 const { PLATFORM } = require('./constants.js')

package/src/ClamAVScanner.js

@@ -1,4 +1,4 @@
-const spawn = require("cross-spawn");
+const { nativeSpawn: spawn } = require('./spawn.js');
 const fs = require("fs");
 const { SCAN_RESULTS } = require('./config.js');
 const { scanViaClamd } = require('./ClamdScanner.js');

package/src/ClamdScanner.js

@@ -1,7 +1,8 @@
 'use strict';
 
-const net = require('net');
-const fs  = require('fs');
+const net            = require('net');
+const fs             = require('fs');
+const { Verdict }    = require('./verdicts.js');
 
 // ClamAV INSTREAM protocol:
 //   1. Send "zINSTREAM\0"
@@ -13,9 +14,9 @@ const CHUNK_SIZE     = 64 * 1024;  // 64 KB — well within clamd's default Stre
 
 function parseClamdResponse(raw) {
     const text = raw.toString('utf8').trim();
-    if (text === 'stream: OK')      return 'Clean';
-    if (text.endsWith(' FOUND'))    return 'Malicious';
-    return 'ScanError';
+    if (text === 'stream: OK')    return Verdict.Clean;
+    if (text.endsWith(' FOUND'))  return Verdict.Malicious;
+    return Verdict.ScanError;
 }
 
 /**

package/src/config.js

@@ -1,3 +1,5 @@
+const { Verdict } = require('./verdicts.js');
+
 module.exports = Object.freeze({
     INSTALLER_COMMANDS: Object.freeze({
         win32:  ['choco',  ['install', 'clamav', '-y']],
@@ -15,8 +17,8 @@ module.exports = Object.freeze({
         win32:  'C:\\ProgramData\\ClamAV\\main.cvd',
     }),
     SCAN_RESULTS: Object.freeze({
-        0: 'Clean',
-        1: 'Malicious',
-        2: 'ScanError'
+        0: Verdict.Clean,
+        1: Verdict.Malicious,
+        2: Verdict.ScanError,
     }),
 });

package/src/index.js

@@ -1,5 +1,4 @@
-const { scan } = require('./ClamAVScanner.js');
+const { scan }    = require('./ClamAVScanner.js');
+const { Verdict } = require('./verdicts.js');
 
-const pompelmi = { scan };
-
-module.exports = pompelmi;
+module.exports = { scan, Verdict };

package/src/spawn.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { spawn } = require('child_process');
+
+/**
+ * A thin wrapper around Node's built-in child_process.spawn that handles the
+ * one meaningful cross-platform difference: on Windows, .cmd/.bat launchers
+ * (e.g. choco, npm) cannot be resolved without the shell, so shell:true is
+ * required.  On POSIX systems the shell is never involved.
+ *
+ * All callers in this codebase pass only hardcoded, trusted arguments, so
+ * enabling the shell on Windows introduces no injection risk.
+ *
+ * @param {string}   cmd
+ * @param {string[]} args
+ * @param {object}   [options] - Passed through to child_process.spawn.
+ *                               `shell` is always overridden by this wrapper.
+ * @returns {import('child_process').ChildProcess}
+ */
+function nativeSpawn(cmd, args, options) {
+    return spawn(cmd, args, {
+        ...options,
+        shell: process.platform === 'win32',
+    });
+}
+
+module.exports = { nativeSpawn };

package/src/verdicts.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * Opaque Symbol-based scan verdicts.
+ *
+ * Using Symbols instead of strings makes comparisons typo-proof: a misspelled
+ * string silently produces `false`; an unknown Symbol property is `undefined`
+ * and fails loudly at the point of use.
+ *
+ * Usage:
+ *   const { Verdict } = require('pompelmi');
+ *   const result = await pompelmi.scan(filePath);
+ *   if (result === Verdict.Clean)     { /* safe *\/ }
+ *   if (result === Verdict.Malicious) { /* quarantine or reject *\/ }
+ *   if (result === Verdict.ScanError) { /* clamscan returned exit code 2 *\/ }
+ */
+const Verdict = Object.freeze({
+    Clean:     Symbol('Clean'),
+    Malicious: Symbol('Malicious'),
+    ScanError: Symbol('ScanError'),
+});
+
+module.exports = { Verdict };