hallucination-validator 1.0.0 → 1.1.0

package/README.md

@@ -1,23 +1,24 @@
 # hallucination-validator
 
-**AI Output Validator for Security and Fact-Checking**
+![NPM Version](https://img.shields.io/npm/v/hallucination-validator)
+![License](https://img.shields.io/npm/l/hallucination-validator)
+![TypeScript](https://img.shields.io/badge/types-included-blue)
 
-`hallucination-validator` is a Node.js library that validates the output of Large Language Models (LLMs) to catch "hallucinations" that are actually security risks. It checks for broken links, dangerous code patterns, and verifies that quotes actually exist in your source context.
+**AI Output Validator for Security & Fact-Checking**
 
-## Why use this?
-
-LLMs often:
-1.  Invent URLs that look real but are dead (or worse, hijacked).
-2.  Suggest "standard" but insecure code (like `eval()`).
-3.  Fabricate quotes from documents they are summarizing.
+`hallucination-validator` is a comprehensive library for validating Large Language Model (LLM) outputs. It prevents common AI risks such as link hallucination (linkrot/hijacking), dangerous code generation, and context fabrication.
 
-This package provides a programmatic way to flag these issues before showing the response to a user.
+## Why use this?
+LLMs are confident but often incorrect. Security risks arise when:
+1.  **Hallucinated URLs** point to non-existent domains that can be hijacked by attackers.
+2.  **Generated Code** contains dangerous patterns like `eval()` or `exec()`.
+3.  **Fabricated Quotes** mislead users by misrepresenting source material.
 
 ## Features
 
-*   **Link Validation**: Extracts URLs and pings them (HEAD request) to ensure they are 200 OK.
-*   **Code Safety Scanning**: Detects `eval()`, `child_process`, and other dangerous Node.js/JS patterns.
-*   **Quote Verification**: Fuzzy-matching to verify that a quoted string actually exists in the provided context source.
+*   **Link Integrity**: Extracts URLs and performs async HEAD requests to verify `200 OK` status.
+*   **Code Safety**: Scans generated code for unsafe Node.js patterns (`eval`, `child_process`, `document.write`).
+*   **Fuzzy Quote Verification**: Verifies if a quoted string exists in the source text, tolerant of minor AI alterations or typos.
 
 ## Installation
 
@@ -27,22 +28,22 @@ npm install hallucination-validator
 
 ## Usage
 
-```javascript
-const HallucinationValidator = require('hallucination-validator');
+```typescript
+import HallucinationValidator from 'hallucination-validator';
 
 const validator = new HallucinationValidator();
 
 // 1. Validate Links
 const text = "Check out valid.com and broken.link/404";
 validator.validateLinks(text).then(broken => {
-    console.log(broken); 
+    console.log('Broken Links:', broken); 
     // [{ url: 'http://broken.link/404', status: 404, ... }]
 });
 
 // 2. Scan Code
-const code = "function run() { eval(input); }";
-const risks = validator.scanCodeSafety(code);
-console.log(risks); 
+const script = "function run() { eval(input); }";
+const risks = validator.scanCodeSafety(script);
+console.log('Risks:', risks); 
 // ['eval()']
 
 // 3. Verify Quotes
@@ -50,15 +51,15 @@ const source = "The quick brown fox jumps over the lazy dog.";
 const aiQuote = "The quick brown fox jumped over a lazy cat.";
 
 const isValid = validator.verifyQuote(aiQuote, source);
-console.log(isValid); 
-// false (too different)
+console.log('Quote Valid:', isValid); 
+// false
 ```
 
 ## Dependencies
-
-*   `fast-levenshtein`: For robust string comparison.
-*   **Node 18+**: uses native `fetch`.
+*   `fast-levenshtein`: For robust string comparison algorithms.
+*   **Node.js 18+**: Requires native `fetch` API.
 
 ## License
 
-MIT
+MIT © Godfrey Lebo
+

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+declare class HallucinationValidator {
+    /**
+     * Scans text for URLs and verifies they are reachable (200 OK).
+     * @param {string} text
+     * @returns {Promise<Array<HallucinationValidator.BrokenLink>>} List of broken links
+     */
+    validateLinks(text: string): Promise<Array<HallucinationValidator.BrokenLink>>;
+    /**
+     * Scans code snippets for potentially dangerous patterns often hallucinated.
+     * @param {string} code
+     * @returns {Array<string>} List of found dangerous patterns
+     */
+    scanCodeSafety(code: string): Array<string>;
+    /**
+     * Verifies if a quote exists within a source context, allowing for typo tolerance.
+     * @param {string} quote
+     * @param {string} context
+     * @param {number} threshold - Allowed matching distance ratio (0.0 to 1.0)
+     * @returns {boolean}
+     */
+    verifyQuote(quote: string, context: string, threshold?: number): boolean;
+}
+declare namespace HallucinationValidator {
+    interface BrokenLink {
+        url: string;
+        status: number;
+        error?: string;
+    }
+}
+export = HallucinationValidator;

package/{index.js → dist/index.js}

@@ -1,40 +1,35 @@
-const levenshtein = require('fast-levenshtein');
-
+"use strict";
+const levenshtein = require("fast-levenshtein");
 class HallucinationValidator {
-
     /**
      * Scans text for URLs and verifies they are reachable (200 OK).
-     * @param {string} text 
-     * @returns {Promise<Array<{url: string, status: number, error: string}>>} List of broken links
+     * @param {string} text
+     * @returns {Promise<Array<HallucinationValidator.BrokenLink>>} List of broken links
      */
     async validateLinks(text) {
         const urlRegex = /https?:\/\/[^\s)]+/g;
         const matches = text.match(urlRegex) || [];
         const brokenLinks = [];
-
         // De-duplicate URLs
         const uniqueUrls = [...new Set(matches)];
-
         for (const url of uniqueUrls) {
             // Remove trailing punctuation often captured by regex
             const cleanUrl = url.replace(/[.,;]$/, '');
-
             try {
                 const response = await fetch(cleanUrl, { method: 'HEAD' });
                 if (!response.ok) {
                     brokenLinks.push({ url: cleanUrl, status: response.status, error: 'Non-200 status' });
                 }
-            } catch (err) {
+            }
+            catch (err) {
                 brokenLinks.push({ url: cleanUrl, status: 0, error: err.message });
             }
         }
-
         return brokenLinks;
     }
-
     /**
      * Scans code snippets for potentially dangerous patterns often hallucinated.
-     * @param {string} code 
+     * @param {string} code
      * @returns {Array<string>} List of found dangerous patterns
      */
     scanCodeSafety(code) {
@@ -46,7 +41,6 @@ class HallucinationValidator {
             { pattern: /innerHTML/g, name: 'innerHTML usage' },
             { pattern: /document\.write/g, name: 'document.write' }
         ];
-
         const findings = [];
         for (const { pattern, name } of dangerousPatterns) {
             if (pattern.test(code)) {
@@ -55,71 +49,43 @@ class HallucinationValidator {
         }
         return findings;
     }
-
     /**
      * Verifies if a quote exists within a source context, allowing for typo tolerance.
-     * @param {string} quote 
-     * @param {string} context 
+     * @param {string} quote
+     * @param {string} context
      * @param {number} threshold - Allowed matching distance ratio (0.0 to 1.0)
      * @returns {boolean}
      */
     verifyQuote(quote, context, threshold = 0.2) {
-        if (!quote || !context) return false;
-
+        if (!quote || !context)
+            return false;
         // 1. Direct inclusion check (fastest)
-        if (context.includes(quote)) return true;
-
+        if (context.includes(quote))
+            return true;
         // 2. Normalized inclusion check (ignore case/punctuation)
         const normalize = (s) => s.toLowerCase().replace(/[^\w\s]/g, '').replace(/\s+/g, ' ');
         const nQuote = normalize(quote);
         const nContext = normalize(context);
-
-        if (nContext.includes(nQuote)) return true;
-
+        if (nContext.includes(nQuote))
+            return true;
         // 3. Fuzzy match 
-        // We scan the context for a window of text similar in length to the quote
-        // and check Levenshtein distance. This is O(N*M) worst case but valid for verification.
         const qLen = nQuote.length;
         const cLen = nContext.length;
-
-        // Optimization: Don't scan if size diff is huge or context smaller logic
-        if (cLen < qLen * (1 - threshold)) return false;
-
-        // Sliding window scan
-        // To be performant, we only check windows starting at word boundaries
-        // or just brute force every N chars if high precision needed.
-        // For "Senior Dev" approach: Let's use a simplified heuristic. 
-        // If the context is massive, real fuzzy search is complex.
-        // We will do a character-by-character validation for small/medium texts.
-
-        // WindowStep: 1 char is safest.
-        // Limit: This is sync and blocking.
-        // If usage assumes short texts (like checking a paragraph), this is fine.
-
+        if (cLen < qLen * (1 - threshold))
+            return false;
         let minDistance = Infinity;
-
-        // Safety cap: if context > 10kb, maybe warn or skip fuzzy?
-        // Let's implement looking for the best window.
-
         for (let i = 0; i <= cLen - qLen; i++) {
-            // Heuristic: check first char matches to skip redundant calc
-            if (nContext[i] !== nQuote[0]) continue;
-
+            if (nContext[i] !== nQuote[0])
+                continue;
             const window = nContext.substring(i, i + qLen);
             const dist = levenshtein.get(nQuote, window);
             if (dist < minDistance) {
                 minDistance = dist;
             }
-            if (minDistance / qLen <= threshold) return true;
+            if (minDistance / qLen <= threshold)
+                return true;
         }
-
-        // Check allows for slightly larger or smaller windows?
-        // nQuote might be missing a word, so window size in context might vary.
-        // But `verifyQuote` usually implies checking if the STATED quote is in source.
-        // So checking strict length window is a fair approximation for "is this string present".
-
         return (minDistance / qLen) <= threshold;
     }
 }
-
 module.exports = HallucinationValidator;

package/package.json

@@ -1,10 +1,16 @@
 {
     "name": "hallucination-validator",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Validates AI outputs for linkrot, dangerous code, and hallucinations.",
-    "main": "index.js",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
     "scripts": {
-        "test": "node --test"
+        "build": "rimraf dist && tsc",
+        "prepublishOnly": "npm run build",
+        "test": "npm run build && node --test"
     },
     "keywords": [
         "ai",
@@ -16,10 +22,20 @@
     ],
     "author": "Godfrey Lebo <emorylebo@gmail.com>",
     "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/emorilebo/hallucination-validator.git"
+    },
     "dependencies": {
         "fast-levenshtein": "^3.0.0"
     },
     "engines": {
         "node": ">=18.0.0"
+    },
+    "devDependencies": {
+        "@types/fast-levenshtein": "^0.0.4",
+        "@types/node": "^25.0.3",
+        "rimraf": "^6.1.2",
+        "typescript": "^5.9.3"
     }
-}
+}

package/test/index.test.js

@@ -1,57 +0,0 @@
-const { test, mock } = require('node:test');
-const assert = require('node:assert');
-const HallucinationValidator = require('../index.js');
-
-test('validateLinks detects broken links', async (t) => {
-    // Mock global fetch
-    const originalFetch = global.fetch;
-
-    global.fetch = async (url) => {
-        if (url.includes('google.com')) {
-            return { ok: true, status: 200 };
-        }
-        if (url.includes('broken.link')) {
-            return { ok: false, status: 404 };
-        }
-        throw new Error('Network error');
-    };
-
-    const validator = new HallucinationValidator();
-    const text = "Check this out: https://google.com and https://broken.link/resource.";
-
-    const results = await validator.validateLinks(text);
-
-    assert.strictEqual(results.length, 1);
-    assert.strictEqual(results[0].url, 'https://broken.link/resource');
-    assert.strictEqual(results[0].status, 404);
-
-    // Restore fetch
-    global.fetch = originalFetch;
-});
-
-test('scanCodeSafety finds dangerous coding patterns', (t) => {
-    const validator = new HallucinationValidator();
-    const unsafeCode = `
-        function bad() {
-            eval("alert('hacked')");
-            const cp = require('child_process');
-        }
-    `;
-
-    const findings = validator.scanCodeSafety(unsafeCode);
-    assert.ok(findings.includes('eval()'));
-    assert.ok(findings.includes('child_process'));
-    assert.strictEqual(findings.length, 2);
-});
-
-test('verifyQuote confirms existence of fuzzy quote', (t) => {
-    const validator = new HallucinationValidator();
-    const context = "The quick brown fox jumps over the lazy dog.";
-    const exactQuote = "quick brown fox";
-    const fuzzyQuote = "quick brwn fox"; // typo
-    const wrongQuote = "lazy cat";
-
-    assert.strictEqual(validator.verifyQuote(exactQuote, context), true);
-    assert.strictEqual(validator.verifyQuote(fuzzyQuote, context, 0.3), true);
-    assert.strictEqual(validator.verifyQuote(wrongQuote, context), false);
-});