json-function-engine 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,509 @@
+# json-function-engine
+
+A standalone JavaScript/TypeScript library for executing logic defined in JSON configuration files. Define functions, conditions, and actions in JSON — execute them against source code, JSON data, or any input. Lightweight, embeddable, and extensible.
+
+## Features
+
+- **Define functions in JSON** - Express logic as conditions and actions in JSON
+- **Execute against source files** - Scan codebases with regex, file filtering, and more
+- **Extensible** - Register custom conditions, actions, and reporters
+- **Multiple output formats** - JSON, Text, HTML, SARIF
+- **Performance** - Regex caching, parallel execution, ReDoS protection
+- **Zero runtime dependencies** - Keep your bundle small
+
+## Installation
+
+```bash
+npm install json-function-engine
+# or
+pnpm add json-function-engine
+# or
+yarn add json-function-engine
+```
+
+## Quick Start
+
+```typescript
+import { Engine } from 'json-function-engine';
+
+const engine = new Engine();
+
+// Define functions inline
+const functions = {
+  version: "1.0",
+  functions: [
+    {
+      id: "NO_TODO",
+      name: "No TODO comments",
+      enabled: true,
+      priority: 1,
+      condition: {
+        type: "regex",
+        pattern: "TODO",
+        fileExtensions: [".ts", ".tsx"]
+      },
+      action: {
+        type: "flag",
+        severity: "info",
+        message: "TODO comment found"
+      }
+    }
+  ]
+};
+
+// Add functions to engine
+engine.addFunctions(functions.functions);
+
+// Execute against source files
+const findings = await engine.execute([
+  { path: "src/auth.ts", content: "const TODO = 'implement auth';" }
+], { cwd: process.cwd() });
+
+// Format output
+console.log(engine.format(findings, "json", { pretty: true }));
+```
+
+## Your First Function
+
+A 5-minute guide to creating and running your first function:
+
+### Step 1: Create a function definition file
+
+Create `my-functions.json`:
+
+```json
+{
+  "version": "1.0",
+  "functions": [
+    {
+      "id": "DETECT_SECRETS",
+      "name": "No hardcoded secrets",
+      "condition": {
+        "type": "regex",
+        "pattern": "(api_key|password|secret)\\s*[:=]\\s*['\"][^'\"]+['\"]",
+        "fileExtensions": [".ts", ".js", ".env"]
+      },
+      "action": {
+        "type": "flag",
+        "severity": "critical",
+        "message": "Potential hardcoded secret detected"
+      }
+    }
+  ]
+}
+```
+
+### Step 2: Load and execute
+
+```typescript
+import { Engine } from 'json-function-engine';
+
+const engine = new Engine();
+
+// Load functions from file
+const result = await engine.loadFunctions('./my-functions.json');
+console.log(`Loaded ${result.loaded} functions`);
+
+// Execute against your codebase
+const findings = await engine.execute([
+  { path: "src/config.ts", content: "const api_key = 'sk-1234567890';" }
+]);
+
+// See results
+console.log(engine.format(findings, 'text'));
+```
+
+### Step 3: Output in different formats
+
+```typescript
+// JSON for programmatic use
+const json = engine.format(findings, 'json');
+
+// SARIF for GitHub Security
+const sarif = engine.format(findings, 'sarif', { version: '2.1' });
+
+// HTML report
+const html = engine.format(findings, 'html', { theme: 'dark' });
+```
+
+## Usage with Attune
+
+```typescript
+import { Engine } from 'json-function-engine';
+
+const engine = new Engine();
+const result = await engine.loadFunctions('./functions/*.json');
+
+console.log(`Loaded ${result.loaded} functions (${result.errors.length} errors)`);
+
+const findings = await engine.execute([
+  { path: 'src/index.ts', content: '...' }
+], { framework: 'nextjs' });
+
+// Get SARIF output for GitHub Security
+const sarif = engine.format(findings, 'sarif', { version: '2.1' });
+```
+
+## JSON Schema
+
+Validate your function definitions using the JSON Schema:
+
+```json
+{
+  "$schema": "https://json-function-engine.dev/schema/v1/functions.json",
+  "version": "1.0",
+  "rules": [...]
+}
+```
+
+Download the schema from [`schema/v1/functions.json`](schema/v1/functions.json) or use with VS Code:
+
+```json
+{
+  "$schema": "./node_modules/json-function-engine/schema/v1/functions.json"
+}
+```
+
+## Function Schema
+
+```json
+{
+  "version": "1.0",
+  "functions": [
+    {
+      "id": "UNIQUE_FUNCTION_ID",
+      "name": "Human readable name",
+      "description": "What this function detects or does",
+      "enabled": true,
+      "priority": 1,
+      "frameworks": ["react", "vue"],
+      "condition": { ... },
+      "action": { ... }
+    }
+  ]
+}
+```
+
+## Condition Types
+
+| Type | Description |
+|------|-------------|
+| `regex` | Pattern matching |
+| `comparison` | Value comparison (==, !=, >, <, contains, etc.) |
+| `exists` | Field presence check |
+| `composite` | AND/OR/NOT logic |
+
+### Regex Condition
+
+```json
+{
+  "type": "regex",
+  "pattern": "TODO",
+  "matchAll": false,
+  "fileExtensions": [".ts", ".tsx"]
+}
+```
+
+### Comparison Condition
+
+```json
+{
+  "type": "comparison",
+  "operator": "==",
+  "field": "framework",
+  "value": "nextjs"
+}
+```
+
+### Exists Condition
+
+```json
+{
+  "type": "exists",
+  "field": "framework"
+}
+```
+
+### Composite Condition
+
+```json
+{
+  "type": "composite",
+  "operator": "AND",
+  "conditions": [
+    { "type": "regex", "pattern": "..." },
+    { "type": "exists", "field": "..." }
+  ]
+}
+```
+
+## Action Types
+
+| Type | Description |
+|------|-------------|
+| `flag` | Create a finding |
+| `block` | Stop execution |
+| `transform` | Modify a value |
+| `notify` | Send an alert |
+
+### Flag Action
+
+```json
+{
+  "type": "flag",
+  "severity": "high",
+  "message": "Issue description"
+}
+```
+
+### Block Action
+
+```json
+{
+  "type": "block",
+  "message": "Stopping execution",
+  "severity": "critical"
+}
+```
+
+## Reporters
+
+| Format | Description |
+|--------|-------------|
+| `json` | JSON output |
+| `text` | Human-readable text |
+| `html` | HTML report |
+| `sarif` | SARIF for CI integration |
+
+## Extending the Engine
+
+### Custom Conditions
+
+```typescript
+const engine = new Engine();
+engine.getRegistry().registerCondition('fileExists', {
+  name: 'fileExists',
+  evaluate: async (config, context, file) => {
+    return {
+      matched: fs.existsSync(path.join(context.cwd, config.path))
+    };
+  }
+});
+```
+
+### Custom Actions
+
+```typescript
+engine.getRegistry().registerAction('slackNotify', {
+  name: 'slackNotify',
+  execute: async (config, context, matches, file) => {
+    await slack.webhook.send({ channel: config.channel, text: ... });
+    return { success: true, notified: true };
+  }
+});
+```
+
+### Custom Reporters
+
+```typescript
+engine.getRegistry().registerReporter('junit', {
+  name: 'JUnit',
+  format: (findings) => {
+    return `<?xml version="1.0"?>
+<testsuite tests="${findings.length}">
+${findings.map(f => `  <testcase name="${f.message}"/>`).join('\n')}
+</testsuite>`;
+  }
+});
+```
+
+## API
+
+### Engine
+
+```typescript
+const engine = new Engine(options?: EngineOptions)
+
+// Load functions from file paths
+const result = await engine.loadFunctions(paths: string | string[], options?: EngineOptions)
+// Returns: { loaded: number, errors: Array<{ path: string, error: string }> }
+
+// Add functions programmatically
+engine.addFunctions(functions: Rule[])
+
+// Get loaded function count
+const count = engine.getFunctionCount()
+
+// Inspect loaded functions
+const functions = engine.getFunctions()
+
+// Clear all functions
+engine.clear()
+
+// Execute functions against files
+const findings = await engine.execute(files: FileInput[], context?: ExecutionContext)
+
+// Format findings
+const output = engine.format(findings: Finding[], format: ReporterFormat, options?: FormatOptions)
+
+// Convenience method
+const output = await engine.scan(files, format?, context?, formatOptions?)
+```
+
+### Options
+
+```typescript
+interface EngineOptions {
+  include?: string[];      // Only include functions matching patterns
+  exclude?: string[];      // Exclude functions matching patterns
+  timeout?: number;        // Timeout per function in ms (default: 5000)
+  parallel?: boolean;      // Execute functions in parallel (default: true)
+  strict?: boolean;        // Throw on errors instead of collecting them
+}
+```
+
+## Execution Context
+
+The execution context provides additional information during function execution:
+
+```typescript
+interface ExecutionContext {
+  cwd: string;             // Current working directory
+  framework?: string;       // Target framework (e.g., 'nextjs', 'react')
+  signal?: AbortSignal;    // Cancellation signal
+  [key: string]: unknown;  // Custom context values
+}
+```
+
+### Framework Filtering
+
+Functions can be targeted to specific frameworks:
+
+```json
+{
+  "id": "NEXTJS_ONLY",
+  "frameworks": ["nextjs"],
+  "condition": { "type": "regex", "pattern": "getServerSideProps" },
+  "action": { "type": "flag", "severity": "info", "message": "Server-side rendering detected" }
+}
+```
+
+When executing, specify the framework to run only matching functions:
+
+```typescript
+const findings = await engine.execute(files, {
+  cwd: '.',
+  framework: 'nextjs'  // Only runs functions that target nextjs or have no framework restriction
+});
+```
+
+### Cancellation
+
+Support cancellation via AbortSignal:
+
+```typescript
+const controller = new AbortController();
+
+const findings = await engine.execute(files, {
+  cwd: '.',
+  signal: controller.signal
+});
+
+// Cancel after timeout
+setTimeout(() => controller.abort(), 5000);
+```
+
+### Metrics
+
+Access execution metrics:
+
+```typescript
+await engine.execute(files, { cwd: '.' });
+const metrics = engine.getMetrics().getMetrics();
+
+console.log({
+  functionsExecuted: metrics.functionsExecuted,
+  filesProcessed: metrics.filesProcessed,
+  findingsCount: metrics.findingsCount,
+  errorsCount: metrics.errorsCount,
+  findingsBySeverity: metrics.findingsBySeverity
+});
+```
+
+### Error Aggregation
+
+Get execution errors:
+
+```typescript
+await engine.execute(files, { cwd: '.' });
+const errors = engine.getErrors();
+
+for (const error of errors) {
+  console.log(`Function ${error.functionId} on ${error.file}: ${error.error}`);
+}
+```
+
+## Error Handling
+
+### Invalid JSON Files
+
+If a JSON file is malformed, `loadFunctions()` will log a warning and continue:
+
+```typescript
+const result = await engine.loadFunctions('./functions/*.json');
+// If some files fail:
+// result.loaded = 5    // successfully loaded
+// result.errors = [{ path: './functions/bad.json', error: 'Unexpected token }' }]
+```
+
+### Invalid Regex Patterns
+
+Invalid regex patterns in conditions are logged as warnings. The function is skipped:
+
+```json
+{
+  "condition": {
+    "type": "regex",
+    "pattern": "[invalid("
+  }
+}
+// Warning: Invalid regex pattern in function INVALID_FUNC
+```
+
+### Duplicate Function IDs
+
+When the same function ID is defined multiple times, later definitions override earlier ones. A warning is logged.
+
+### Timeout Handling
+
+Each function has a configurable timeout (default: 5 seconds). If execution exceeds the timeout, it's terminated and a warning is logged:
+
+```typescript
+const engine = new Engine({ timeout: 1000 }); // 1 second timeout
+const findings = await engine.execute(files);
+// If a function takes >1s, it's terminated and execution continues
+```
+
+## Performance
+
+- **Bundle size**: < 15KB gzipped
+- **Regex caching**: Compiled patterns are cached
+- **ReDoS protection**: Configurable timeout per function (default: 5s)
+- **Parallel execution**: Functions can run concurrently
+
+## Use Cases
+
+| Use Case | Description |
+|----------|-------------|
+| Code scanning | Scan source for secrets, TODOs, patterns |
+| Data validation | Validate API responses against functions |
+| Config processing | Evaluate conditions in config files |
+| Simple workflows | Conditional data pipelines |
+
+## Interested in Consolidating?
+
+If you're a maintainer considering rolling similar functionality into your core package, I'm happy to point users your direction instead. Open an issue to discuss.
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_TIMEOUT_MS = 5000;
+export declare const MAX_REGEX_CACHE_SIZE = 1000;
+export declare const SEVERITY_WEIGHTS: {
+    readonly critical: 5;
+    readonly high: 4;
+    readonly medium: 3;
+    readonly low: 2;
+    readonly info: 1;
+};
+export declare const DEFAULT_PARALLEL = true;
+export declare const DEFAULT_INCLUDE_PATTERNS: string[];
+export declare const DEFAULT_EXCLUDE_PATTERNS: string[];
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAGvC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAGzC,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAGX,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAGrC,eAAO,MAAM,wBAAwB,EAAE,MAAM,EAAO,CAAC;AACrD,eAAO,MAAM,wBAAwB,EAAE,MAAM,EAAO,CAAC"}

package/dist/constants.js

@@ -0,0 +1,18 @@
+// Default timeout for function execution in milliseconds
+export const DEFAULT_TIMEOUT_MS = 5000;
+// Regex cache limits
+export const MAX_REGEX_CACHE_SIZE = 1000;
+// Severity weights for sorting findings (higher = more severe)
+export const SEVERITY_WEIGHTS = {
+    critical: 5,
+    high: 4,
+    medium: 3,
+    low: 2,
+    info: 1
+};
+// Default parallel processing setting
+export const DEFAULT_PARALLEL = true;
+// File loading defaults
+export const DEFAULT_INCLUDE_PATTERNS = [];
+export const DEFAULT_EXCLUDE_PATTERNS = [];
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC,qBAAqB;AACrB,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;IACN,IAAI,EAAE,CAAC;CACC,CAAC;AAEX,sCAAsC;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,wBAAwB;AACxB,MAAM,CAAC,MAAM,wBAAwB,GAAa,EAAE,CAAC;AACrD,MAAM,CAAC,MAAM,wBAAwB,GAAa,EAAE,CAAC"}

package/dist/engine/Executor.d.ts

@@ -0,0 +1,92 @@
+import type { FunctionDefinition, FileInput, ExecutionContext, Finding, Logger } from '../types/index.js';
+import type { Registry } from './registry.js';
+import { Pipeline } from './Pipeline.js';
+import { type MetricsCollector } from '../utils/metrics.js';
+export interface ExecutorDependencies {
+    registry: Registry;
+    logger?: Logger;
+    metrics?: MetricsCollector;
+}
+export interface ExecutorOptions {
+    timeout?: number;
+    parallel?: boolean;
+}
+/**
+ * Classified error information
+ */
+export interface ClassifiedError {
+    functionId: string;
+    file: string;
+    error: string;
+    phase: 'condition' | 'action';
+    type: 'validation' | 'timeout' | 'runtime' | 'unknown';
+}
+export declare class Executor {
+    private registry;
+    private logger;
+    private options;
+    private pipeline;
+    private metrics;
+    private errors;
+    private cancelled;
+    constructor(dependencies: ExecutorDependencies, options?: ExecutorOptions);
+    /**
+     * Cancel the current execution
+     */
+    cancel(): void;
+    /**
+     * Check if execution was cancelled
+     */
+    isCancelled(): boolean;
+    /**
+     * Reset cancelled state for next execution
+     */
+    private resetCancellation;
+    /**
+     * Get the execution pipeline
+     */
+    getPipeline(): Pipeline;
+    /**
+     * Execute functions against files
+     */
+    execute(functions: FunctionDefinition[], files: FileInput[], context: ExecutionContext): Promise<Finding[]>;
+    /**
+     * Get execution errors with classification
+     */
+    getErrors(): ClassifiedError[];
+    /**
+     * Get the metrics collector
+     */
+    getMetrics(): MetricsCollector;
+    /**
+     * Classify an error based on its characteristics
+     */
+    private classifyError;
+    /**
+     * Process files sequentially
+     */
+    private sequentialProcess;
+    /**
+     * Process a single file through all enabled functions
+     */
+    processFile(file: FileInput & {
+        lines: string[];
+    }, fns: FunctionDefinition[], context: ExecutionContext): Promise<Finding[]>;
+    /**
+     * Evaluate a function against a file
+     */
+    evaluateFunction(fn: FunctionDefinition, file: FileInput, context: ExecutionContext): Promise<{
+        findings?: Finding[];
+        blocked?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Set the logger (acceptable to change at runtime)
+     */
+    setLogger(logger: Logger): void;
+    /**
+     * Update options
+     */
+    setOptions(options: Partial<ExecutorOptions>): void;
+}
+//# sourceMappingURL=Executor.d.ts.map

package/dist/engine/Executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Executor.d.ts","sourceRoot":"","sources":["../../src/engine/Executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAiC,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACzI,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAgB,MAAM,eAAe,CAAC;AAGvD,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAErF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC9B,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;CACxD;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAkB;gBAEvB,YAAY,EAAE,oBAAoB,EAAE,OAAO,GAAE,eAAoB;IAe7E;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,WAAW,IAAI,QAAQ;IAIvB;;OAEG;IACG,OAAO,CACX,SAAS,EAAE,kBAAkB,EAAE,EAC/B,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,OAAO,EAAE,CAAC;IAyDrB;;OAEG;IACH,SAAS,IAAI,eAAe,EAAE;IAI9B;;OAEG;IACH,UAAU,IAAI,gBAAgB;IAI9B;;OAEG;IACH,OAAO,CAAC,aAAa;IA8CrB;;OAEG;YACW,iBAAiB;IAmB/B;;OAEG;IACG,WAAW,CACf,IAAI,EAAE,SAAS,GAAG;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EACrC,GAAG,EAAE,kBAAkB,EAAE,EACzB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,OAAO,EAAE,CAAC;IAqDrB;;OAEG;IACG,gBAAgB,CACpB,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;QACT,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;QACrB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAoCF;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;CAGpD"}