x-fidelity 2.17.2 → 3.0.1

package/CHANGELOG.md

@@ -1,3 +1,146 @@
+## [3.0.1](https://github.com/zotoio/x-fidelity/compare/v3.0.0...v3.0.1) (2025-02-15)
+
+
+### Bug Fixes
+
+* package.json & yarn.lock to reduce vulnerabilities ([5dd70a3](https://github.com/zotoio/x-fidelity/commit/5dd70a3363b212d85147dbd18f56e0eaefcc1897))
+
+# [3.0.0](https://github.com/zotoio/x-fidelity/compare/v2.17.2...v3.0.0) (2025-02-15)
+
+
+### Bug Fixes
+
+* add event listener cleanup in engine test files ([705a39c](https://github.com/zotoio/x-fidelity/commit/705a39c8357c74cc2f7935a44da1bdb27bcb9e31))
+* add interceptors mock to axios test client ([edb17b5](https://github.com/zotoio/x-fidelity/commit/edb17b54a45771c53eb44dd34763d93273d137bf))
+* add isPathInside imports and handle missing file paths ([42b0207](https://github.com/zotoio/x-fidelity/commit/42b0207276827cb05aa10d4b6c5c9247c33bbb6f))
+* add matchLength undefined checks in maskValue function ([2872ec5](https://github.com/zotoio/x-fidelity/commit/2872ec5323e4517f032f404cf6c50237af1d5e59))
+* add missing Engine interface methods in test mock ([fa523d2](https://github.com/zotoio/x-fidelity/commit/fa523d217839e997713aa8527d95bf1b968c1c0d))
+* add missing ErrorLevel type import in engineRunner ([bb8551c](https://github.com/zotoio/x-fidelity/commit/bb8551c9dbfc7282e39bf871f97696e2705d7686))
+* add missing imports for path and pluginRegistry ([d98192b](https://github.com/zotoio/x-fidelity/commit/d98192b4eb8b540975ab351efa5e24aaab5fabd7))
+* add missing interceptors to axios mock in test ([42a72eb](https://github.com/zotoio/x-fidelity/commit/42a72eb121fd28009ebdf91383e1a93d6cae7a4b))
+* add missing logger import in facts/index.ts ([46d09c7](https://github.com/zotoio/x-fidelity/commit/46d09c70120a935a15d5c5cf070b27bf3d2cf0fb))
+* add missing logger.info mock in test setup ([c1a3dba](https://github.com/zotoio/x-fidelity/commit/c1a3dbaa3bb4cf1d696244d274d8aed94ec897e1))
+* add missing OperatorDefn type import in pluginRegistry ([51fcf15](https://github.com/zotoio/x-fidelity/commit/51fcf159fa6bd93f0f5081aee5dd87dc0a85a10a))
+* add mock implementation for path.relative in tests ([f39ce89](https://github.com/zotoio/x-fidelity/commit/f39ce89f1db3ea0cfe6f222cf6cc7fcd78a94dca))
+* add mock implementation for path.resolve in tests ([edd3388](https://github.com/zotoio/x-fidelity/commit/edd33884f61ae2a8a457b15a32478f949b8d7d96))
+* add null check for childPath in isPathInside function ([c510bd4](https://github.com/zotoio/x-fidelity/commit/c510bd43fff43328ced1d5706f0969e630b4ed19))
+* add proper type annotations to express logger functions ([7146f70](https://github.com/zotoio/x-fidelity/commit/7146f70f954021708cc79924727a7cd306596ada))
+* add proper type annotations to express logger middleware ([c0868ce](https://github.com/zotoio/x-fidelity/commit/c0868ceb8f2aca2dcd91da06c3977154f4b12ef1))
+* add type annotation for operators object to fix string indexing ([aa3ced1](https://github.com/zotoio/x-fidelity/commit/aa3ced1b494aa3c453d3d7231ef9c99e0a2603fa))
+* add type annotation for rest parameter in mock implementation ([736fd36](https://github.com/zotoio/x-fidelity/commit/736fd36f4fbe9299cbc600f6700d1603d6337659))
+* add type assertion for errorSource in engineRunner ([f17df2a](https://github.com/zotoio/x-fidelity/commit/f17df2a6982c79a31520141324d64281321138a8))
+* add type cast for args spread in plugin function call ([f88f3f8](https://github.com/zotoio/x-fidelity/commit/f88f3f840318cc8eb1a404d6fe30efc58d178598))
+* add type cast for rule name property in validate command ([5b811ad](https://github.com/zotoio/x-fidelity/commit/5b811ad00bcf50b76a8b96999ae36a758f2a286d))
+* add type safety for engine removeAllListeners method in tests ([f1bd1c0](https://github.com/zotoio/x-fidelity/commit/f1bd1c056246918303d4b4fbda2702cc8f807e79))
+* avoid reassigning to constant error variable in error handling ([5f04405](https://github.com/zotoio/x-fidelity/commit/5f04405a02693c53dc048d2c63ac1cb9827c24a2))
+* cast event types to ErrorLevel enum for type safety ([f2cb3b5](https://github.com/zotoio/x-fidelity/commit/f2cb3b567d4061b57c5ca6c9b07cd628f9554c5c))
+* change logPrefix from const to let for mutability ([2ce6b56](https://github.com/zotoio/x-fidelity/commit/2ce6b5615a9be93230e5278dcf5b3308e4c2b5aa))
+* correct Engine type definition in engineRunner test ([e474084](https://github.com/zotoio/x-fidelity/commit/e474084ca0cc033a341cc983174b66161bdf0dbe))
+* correct function type signature in plugin registry ([f5001df](https://github.com/zotoio/x-fidelity/commit/f5001df187496074b7d2be517bdb714c31b495e5))
+* correct type casting for spread operator in plugin function call ([55e1894](https://github.com/zotoio/x-fidelity/commit/55e1894f099d3153699613e543d0163f9a0e00e5))
+* correct type signature for pino-http customLogLevel function ([8d6cb76](https://github.com/zotoio/x-fidelity/commit/8d6cb7696c32aa26fbf97bc9bf0637f1e1ae0089))
+* correct TypeScript errors in logger implementation ([8da1f9c](https://github.com/zotoio/x-fidelity/commit/8da1f9ca56cf054cd499df4d2da510ba6fdb8ab0))
+* correct TypeScript errors in operator and error handling ([d2a1927](https://github.com/zotoio/x-fidelity/commit/d2a19270e047a903d1ef0a526f2bd193dab5a39f))
+* declare handledError variable before usage in error handling ([34a95a9](https://github.com/zotoio/x-fidelity/commit/34a95a9ca2994db0bf8d03381e636b315e75ee37))
+* declare handledError with proper scope in engineRunner ([65fc6b9](https://github.com/zotoio/x-fidelity/commit/65fc6b905ead2756462ac81eb7085189d06833ec))
+* ensure error handling type safety and add onError schema ([b61c183](https://github.com/zotoio/x-fidelity/commit/b61c183565a15c18c665581df806a387792878a2))
+* ensure type safety in engine runner error handling ([32a3007](https://github.com/zotoio/x-fidelity/commit/32a30076a2673ecc9f32e42a3a7e876133ce8a64))
+* handle missing fs.promises.stat and fix directory structure check ([84ff132](https://github.com/zotoio/x-fidelity/commit/84ff132e63dfd88255a4e38b316399ff2c82abcd))
+* handle symlink errors and improve directory structure validation ([b2847c9](https://github.com/zotoio/x-fidelity/commit/b2847c96f85a04f68033371fc5235255971a5e0d))
+* handle undefined paths and use path.resolve for path normalization ([e814259](https://github.com/zotoio/x-fidelity/commit/e814259eef9372d3f79a890952a685d1086bd7a0))
+* improve error handling in dependency collection ([ee003d2](https://github.com/zotoio/x-fidelity/commit/ee003d23713b7fcc465ec042e605518c8fb1a34f))
+* improve event listener handling and type safety in tests ([32d6c3b](https://github.com/zotoio/x-fidelity/commit/32d6c3bdf2a4148a84969e8baa5ee647cfed57c6))
+* improve logger prefix handling and configuration inheritance ([42f6d8c](https://github.com/zotoio/x-fidelity/commit/42f6d8ccfdc437e51d58be690ca1cd39b023dade))
+* improve operator error detection in rule execution ([3590c50](https://github.com/zotoio/x-fidelity/commit/3590c5078bdefe90fefe98279eb52402446e8e4a))
+* improve plugin error handling and propagation ([82315c6](https://github.com/zotoio/x-fidelity/commit/82315c6d02c025a2a022d3b59cd61070479c954f))
+* improve TypeScript types for logger and pino middleware ([77bd9ac](https://github.com/zotoio/x-fidelity/commit/77bd9acf8a42dff164623f81fdac2b977cb9ff78))
+* initialize logger immediately and update test expectations ([adc8d76](https://github.com/zotoio/x-fidelity/commit/adc8d7641ba42ae4f8e56440f8bea417c2cb8568))
+* move operator loading inside function to capture latest plugins ([c1df0df](https://github.com/zotoio/x-fidelity/commit/c1df0dfe602adfea05b9db86a67c1e33f9915a96))
+* prevent masking of string values in maskSensitiveData util ([f9abb11](https://github.com/zotoio/x-fidelity/commit/f9abb11929aa90c619f522f985b91572e603e7e9))
+* remove duplicate export statements in types/index.ts ([b61504c](https://github.com/zotoio/x-fidelity/commit/b61504ce03f5cbd4d0ff4ba8dc99645e40be7310))
+* remove duplicate function declarations in logger.ts ([fe68714](https://github.com/zotoio/x-fidelity/commit/fe68714618067ee5600a5e00048632b1c265f6d2))
+* remove duplicate removeAllListeners property in mock Engine object ([f77bd1a](https://github.com/zotoio/x-fidelity/commit/f77bd1a05719c8c1598fec364febe5f835f24390))
+* remove duplicate setLogLevel function declaration ([a6f892a](https://github.com/zotoio/x-fidelity/commit/a6f892a0f0de31d7e564ab9984364f30b29c01ec))
+* remove unused plugin types import ([47e3bdc](https://github.com/zotoio/x-fidelity/commit/47e3bdcf8d3228ba90fc6c790bd67aa18497aff6))
+* rename errorSource to source in ErrorActionParams interface ([d7f2c04](https://github.com/zotoio/x-fidelity/commit/d7f2c048922bb9a285cbe73482b8a3b8d0ce4634))
+* rename reqCustomProps to customProps in express logger config ([22f380e](https://github.com/zotoio/x-fidelity/commit/22f380e4d80296b248ce472796af6890d1bd8639))
+* replace Function.apply with Function.call for better type safety ([f0e8e2d](https://github.com/zotoio/x-fidelity/commit/f0e8e2d2c1ef7eb0acece223474f33e08e7cd478))
+* resolve logger initialization circular dependency ([3d81e87](https://github.com/zotoio/x-fidelity/commit/3d81e87fc5cabd339c5173a92ec1b66d9377671a))
+* resolve TypeScript error by avoiding reassignment to constant error ([e16fbd6](https://github.com/zotoio/x-fidelity/commit/e16fbd6c57ce98a12fb1e868c0a86f2998774b34))
+* resolve TypeScript errors in engineRunner test file ([26cf0a5](https://github.com/zotoio/x-fidelity/commit/26cf0a5ad1e0fefe14c6e3697bebec2017a6cc72))
+* resolve TypeScript errors in logger implementation ([5025c92](https://github.com/zotoio/x-fidelity/commit/5025c92f75d9a754ef38194e4495ada9bb8b50d2))
+* resolve TypeScript interface inheritance for XFiLogger ([01c9069](https://github.com/zotoio/x-fidelity/commit/01c906978a2b9e034c953646489d28148a48598d))
+* **test:** delete invalid tests ([6a3e449](https://github.com/zotoio/x-fidelity/commit/6a3e449d0c8673a70efc801cefc3a565678e5ecf))
+* update axios client test module imports and error handling ([944d83c](https://github.com/zotoio/x-fidelity/commit/944d83c4d74a4aa6984351ad560737d00cee3f07))
+* update axios mock implementation for 429 retry test ([469881c](https://github.com/zotoio/x-fidelity/commit/469881cc17bae169115c29fcaf0d8d4949f85250))
+* update customContains operator to handle file analysis result object ([961a8cf](https://github.com/zotoio/x-fidelity/commit/961a8cf66384929b2af5e9fc8f647c22803d413f))
+* update docusaurus config to use correct API paths ([749b04f](https://github.com/zotoio/x-fidelity/commit/749b04f14475849294420145101445f325608e85))
+* update function type signatures for plugin facts ([7aaf633](https://github.com/zotoio/x-fidelity/commit/7aaf6335ec421d0f527eb3c9f65b7e4cc8cd104e))
+* update logger implementation to use Pino instead of Winston ([78fa960](https://github.com/zotoio/x-fidelity/commit/78fa960ec2e339bbe3b1bc54d3188ef313287ac0))
+* update logger types and fix pino-http integration ([6dbe72e](https://github.com/zotoio/x-fidelity/commit/6dbe72ef25df54d9faf8a6d41b7069a95a84c5b9))
+* update pino logger types and middleware configuration ([bf3f0bf](https://github.com/zotoio/x-fidelity/commit/bf3f0bf64d1150d5c7bba6cdf47028f20c8b6ce3))
+* update spread args type to tuple for TypeScript compatibility ([cf0579b](https://github.com/zotoio/x-fidelity/commit/cf0579bcdc38007e66d639f01e846fe3c35861b1))
+* use call() instead of apply() for proper argument handling ([eedc5bf](https://github.com/zotoio/x-fidelity/commit/eedc5bfe9497c67fddd051dd4b59c99e3baeedb8))
+
+
+### Features
+
+* add basic plugin example with custom operator and fact ([7af5f0f](https://github.com/zotoio/x-fidelity/commit/7af5f0fcf1cee2c02fb4c6c73999e99df0c01236))
+* add custom error handling and action execution for rules ([4eb80a3](https://github.com/zotoio/x-fidelity/commit/4eb80a3d7e293588ad57fc34c26c792874f4c43f))
+* add dynamic log level configuration and prefix management ([3bdf085](https://github.com/zotoio/x-fidelity/commit/3bdf08504e7b51c34d1eeef6860e7e88ce019663))
+* add dynamic log level control and improve environment variable handling ([138f6d0](https://github.com/zotoio/x-fidelity/commit/138f6d0efadf5f52c9df560777be84baf63b41d9))
+* add dynamic log level control and improve initialization logging ([0640350](https://github.com/zotoio/x-fidelity/commit/0640350dc947018b41028fd35453c2f1e5562bfa))
+* add environment variable control for log level ([95197a5](https://github.com/zotoio/x-fidelity/commit/95197a502422052d8337f7fe96dd0de3d3aa8fed))
+* add error behavior configuration for rule execution ([2380704](https://github.com/zotoio/x-fidelity/commit/2380704beb019ee72f4a054235ed6592e35f073e))
+* add error count tracking to codebase analysis results ([c8e5847](https://github.com/zotoio/x-fidelity/commit/c8e5847a6fb3285769e2c3c83705bb8ffb88bd0a))
+* add error demo plugin with comprehensive error handling ([336d24a](https://github.com/zotoio/x-fidelity/commit/336d24a3da91ba334951c7ced0271f19a3d6c637))
+* add error handling and export utility modules ([ea41b07](https://github.com/zotoio/x-fidelity/commit/ea41b07b8f4cec57117a339ce60b2e7c147b77d2))
+* add errorCount field to ResultMetadata interface ([24f8d84](https://github.com/zotoio/x-fidelity/commit/24f8d8472bcfccb69f9bcaab4e3d170c3b3e92ec))
+* add ErrorLevel type for rule failure levels ([1523f9f](https://github.com/zotoio/x-fidelity/commit/1523f9fd96a6cd4f3312c171772f97cc5149bdd9))
+* add explicit method signatures to XFiLogger interface ([af1684d](https://github.com/zotoio/x-fidelity/commit/af1684d1db71d0ccf2c047457239d5adba93ae12))
+* add extensions file option to CLI and banner display ([3512f4f](https://github.com/zotoio/x-fidelity/commit/3512f4ffa5cde82a4500f199b8632f9436e99680))
+* add external API integration with regex value extraction ([c019226](https://github.com/zotoio/x-fidelity/commit/c0192260a8ff0c6bc60afc28fc81f4ff48358c10))
+* add external sample rules loading for basic plugin ([b63fb0a](https://github.com/zotoio/x-fidelity/commit/b63fb0aadda2bf9af4018267a2c672fdfe01ec87))
+* add fallback to global modules for plugin loading ([52949fb](https://github.com/zotoio/x-fidelity/commit/52949fbc06d6dd9a1aefdfbf5e9086c2d83b6b5f))
+* add operation field to dependency error logging ([457050b](https://github.com/zotoio/x-fidelity/commit/457050b5cbda10bdfbc22230d29569902eb6444f))
+* add plugin error handling with result propagation ([8f0a78e](https://github.com/zotoio/x-fidelity/commit/8f0a78edba0b9352a7d485bc7ae87cd2b5064356))
+* add plugin loading support to CLI mode ([7c23f01](https://github.com/zotoio/x-fidelity/commit/7c23f01e5ce7307391b42ae5e0f755ee6ef91d3f))
+* add regex validator plugin with API validation support ([664cdb5](https://github.com/zotoio/x-fidelity/commit/664cdb595c925637042b4ce511681b012ba9ceec))
+* add regex validator plugin with validation endpoint support ([0cc8b55](https://github.com/zotoio/x-fidelity/commit/0cc8b55183727c5f68c7493fff50e698df16e951))
+* add routeBasePath to TypeDoc plugin for correct API docs routing ([255bbe5](https://github.com/zotoio/x-fidelity/commit/255bbe591d931b0c31877bbebaec7e32f9c4f175))
+* add sample rule using customFact and customOperator ([27f864f](https://github.com/zotoio/x-fidelity/commit/27f864f196e2e3dbe49b831e3c3e739cef708a20))
+* add sample rules loading to sample plugin ([c1ef6f4](https://github.com/zotoio/x-fidelity/commit/c1ef6f409a4e5e23f60c72c1e489c2f296664abe))
+* add sample rules support to plugin interface ([e263728](https://github.com/zotoio/x-fidelity/commit/e263728de96835ab27188cecbb7f6729ce0d859b))
+* add source map support and error location enhancement to logger ([f641a69](https://github.com/zotoio/x-fidelity/commit/f641a69f992100650ce32831cad9dd197f845914))
+* add src/plugins as first lookup path for plugin loading ([bd2e8b5](https://github.com/zotoio/x-fidelity/commit/bd2e8b586a0b2402910dd301ac706247a2bb7e48))
+* add subpath exports for logger and axios utilities ([21a9ff2](https://github.com/zotoio/x-fidelity/commit/21a9ff293cedfde5d9339516351f933b430d100b))
+* add support for loading external plugins via extensions ([d044e02](https://github.com/zotoio/x-fidelity/commit/d044e020f727aec554ee7dcc4acd3e8bcb6a854b))
+* add symlink support with cycle detection in file operations ([7862c52](https://github.com/zotoio/x-fidelity/commit/7862c526c9e5da4cba438e80d979b6a9c9b67a7b))
+* add test command as default CLI action ([40ad784](https://github.com/zotoio/x-fidelity/commit/40ad7840220e37a2b901037185f09c3ed32ec260))
+* add test server script for serving mock JSON responses ([e204196](https://github.com/zotoio/x-fidelity/commit/e2041960251b6f2c3e3089bc52e1b7673fd553ad))
+* add validate command for archetype configuration validation ([31d489a](https://github.com/zotoio/x-fidelity/commit/31d489a2b7af6d591e257604c11449b612e7716a))
+* enhance error handling with source classification and stack traces ([eaaf0e0](https://github.com/zotoio/x-fidelity/commit/eaaf0e0e3a4b85cd23a234bba12c9e3fefb48f15))
+* enhance Pino logger with multistream and improved serialization ([3956a0b](https://github.com/zotoio/x-fidelity/commit/3956a0b4ac8cfd0944cc4fd3f5681694a865ffd2))
+* enhance plugin loading logs with detailed facts and operators info ([96b49eb](https://github.com/zotoio/x-fidelity/commit/96b49eb69c046dfb7496bcf5d84112841a276d0c))
+* enhance plugin registration with validation and module format support ([785445b](https://github.com/zotoio/x-fidelity/commit/785445b84d62b6a313a09a10dbbab223739daae1))
+* enhance sensitive data protection in logging and env vars ([b7dc977](https://github.com/zotoio/x-fidelity/commit/b7dc977ebe059d760fccad9a66221042f5992a39))
+* expose TypeScript type definitions in package exports ([8c0dd86](https://github.com/zotoio/x-fidelity/commit/8c0dd86ed27d86df36da1db34359a8ea2d4d6549))
+* implement intermittent masking pattern for sensitive data ([18a5d84](https://github.com/zotoio/x-fidelity/commit/18a5d84ac6444897286dae472f66fadab8a766b5))
+* implement partial masking for sensitive data with string support ([d8dc195](https://github.com/zotoio/x-fidelity/commit/d8dc19590710e763e8eb1e7f8002a449d5af3346))
+* implement plugin system for custom facts and operators ([6a03a2c](https://github.com/zotoio/x-fidelity/commit/6a03a2c7a720ff98b85333be7c4073674b10133c))
+* improve sensitive data masking to maintain original length ([b47cbca](https://github.com/zotoio/x-fidelity/commit/b47cbca1ddb772da28b23e5d58123a18e6bac709))
+* integrate plugin facts into allFacts registry ([89504e4](https://github.com/zotoio/x-fidelity/commit/89504e43479af94c9121914e186d2db6e4a1d68a))
+* **plugin framework:** refactor and improve extensibility ([d999ebc](https://github.com/zotoio/x-fidelity/commit/d999ebcfbf482a41d77e96393188d02cc0b2b0e2))
+* support loading multiple npm modules as extensions directly ([e485c6b](https://github.com/zotoio/x-fidelity/commit/e485c6bf550547c43d5d2e9248477e16ff059d6b))
+* update basic plugin to support external API calls and regex extraction ([c23941c](https://github.com/zotoio/x-fidelity/commit/c23941cc7dac4a67ada075970859e395a4369aec))
+* update mask function to show 6 characters at each end ([9b8babe](https://github.com/zotoio/x-fidelity/commit/9b8babe6cfa4b41bcd3b70e476e4e23259d80a27))
+
+
+### BREAKING CHANGES
+
+* **plugin framework:** cli options extended to include -e loading plugins, and enhancements to AI
+integration options
+
 ## [2.17.2](https://github.com/zotoio/x-fidelity/compare/v2.17.1...v2.17.2) (2025-01-16)
 
 

package/CONTRIBUTING.md

@@ -14,6 +14,7 @@ We welcome contributions to x-fidelity! This document provides guidelines for co
 1. Make your changes in your feature branch.
 2. Add or update tests as necessary.
 3. Ensure all tests pass by running `yarn test`.
+4. When modifying documentation to cover new functionality (such as remote validation, GitHub webhook integration, enhanced telemetry, or new plugins), please update both the README and PLUGIN_GUIDANCE accordingly.
 4. Ensure the code lints properly by running `yarn lint`.
 
 ## Commit Messages

package/PLUGIN_GUIDANCE.md

@@ -0,0 +1,157 @@
+# Plugin Guidance
+
+This document provides detailed guidance on how to use, install, and create external plugin extensions for x‑fidelity. External plugins allow you to extend x‑fidelity’s core functionality without modifying the main codebase.
+
+## Introduction
+
+x‑fidelity supports plugins that conform to the `XFiPlugin` interface. Plugins can add custom facts, operators, and error handlers. They can be installed either globally or locally—and x‑fidelity will load them at runtime as specified with the `-e` or `--extensions` option.
+
+## Installation Options
+
+### Global Installation
+
+- To install an external plugin globally, run:
+  ```bash
+  yarn add <plugin-module-name>
+  ```
+- Global plugins are available system‑wide; ensure that your global node_modules directory is in your module resolution path.
+
+### Local Installation
+
+- To install an external plugin locally in your project, run:
+  ```bash
+  yarn add <plugin-module-name>
+  ```
+- Local plugins are stored in your project’s `node_modules` directory. x‑fidelity will check local installations first.
+
+## Using Plugins with x‑fidelity
+
+When running x‑fidelity you can specify one or more plugin names using the `-e` or `--extensions` option:
+```bash
+xfidelity /path/to/project -e xfi-basic-plugin xfi-another-plugin
+```
+Separate multiple plugin module names with spaces.
+
+## Creating Custom Plugins
+
+To create your own plugin, implement the `XFiPlugin` interface. At a minimum, export an object with the following properties:
+
+- **name**: A unique string identifier for your plugin.
+- **version**: The plugin version.
+- **facts**: (optional) An array of fact definitions.
+- **operators**: (optional) An array of operator definitions.
+- **onError**: (optional) A function to handle errors encountered in plugin processing.
+
+For example, the new Remote String Validation plugin (`xfiPluginRemoteStringValidator`) implements a fact (`remoteSubstringValidation`) and an operator (`invalidRemoteValidation`). See the sample rule `invalidSystemIdConfigured-iterative-rule.json` for usage details.
+
+Example:
+```javascript
+// my-plugin.js
+module.exports = {
+  name: 'my-plugin',
+  version: '1.0.0',
+  facts: [{
+    name: 'myCustomFact',
+    fn: async () => ({ result: 'custom fact data' })
+  }],
+  operators: [{
+    name: 'myCustomOperator',
+    fn: (factValue, expectedValue) => factValue === expectedValue
+  }],
+  onError: (error) => ({
+    message: `Plugin error: ${error.message}`,
+    level: 'warning',
+    details: error.stack
+  })
+};
+```
+After creating your plugin, install it (locally or globally) and reference it using the `-e` option when running x‑fidelity.
+
+## Troubleshooting and Tips
+
+- **Environment Variables**: Ensure your Node.js module resolution settings include global modules if using global installations.
+- **Debugging**: Enable verbose logging in x‑fidelity to troubleshoot plugin loading.
+- **Name Conflicts**: If multiple plugins expose facts or operators under the same name, loading order may affect which one is used.
+
+For any further questions, consult the x‑fidelity documentation or reach out to the maintainers.
+
+## Local Development and Testing
+
+### Testing Locally with Yarn Link
+
+To test your plugin locally without publishing it to an npm repo, you can use `yarn link`. In your plugin’s development directory, run:
+```bash
+yarn link
+```
+Then, in your x‑fidelity project directory, run:
+```bash
+yarn link <plugin-module-name>
+```
+Replace `<plugin-module-name>` with your plugin's package name. This will create a symlink so that any changes you make to your plugin are immediately available to x‑fidelity.
+
+### Important Imports for Plugin Integration
+
+For seamless integration with x‑fidelity, ensure your plugin imports the key types and utilities. For example:
+```javascript
+import { XFiPlugin } from 'x-fidelity/types/typeDefs';
+import { logger } from 'x-fidelity/utils/logger';
+import { safeClone, safeStringify } from 'x-fidelity/utils/utils';
+```
+These imports ensure that your plugin can interoperate correctly with x‑fidelity’s API, logging, and utility functions.
+
+## Sample Plugin Rules and Unit Tests
+
+In addition to creating your plugin, you can create sample rules that exercise your plugin's functionality. These sample rules serve both as documentation and as a basis for unit tests to ensure your plugin operates as expected.
+
+### Creating Sample Rules
+
+Optionally, include unit tests for your custom facts and operators, as shown in our sample tests.
+
+For example, if your plugin defines a fact named `customFact` and an operator named `customOperator`, you can create a sample rule JSON file:
+```json
+{
+  "name": "custom-plugin-rule",
+  "conditions": {
+    "all": [
+      {
+        "fact": "customFact",
+        "operator": "customOperator",
+        "value": "custom fact data"
+      }
+    ]
+  },
+  "event": {
+    "type": "warning",
+    "params": {
+      "message": "Plugin fact and operator validated successfully"
+    }
+  }
+}
+```
+Place this sample rule file in your local configuration rules directory (e.g., `rules/`), so that x‑fidelity can pick it up during analysis.
+
+### Writing Unit Tests
+
+Complement your sample rule with unit tests to validate your plugin behavior. For example, using Jest you might create a test file such as `custom-plugin-rule.test.ts` with the following content:
+```typescript
+import { customFact } from 'xfiPluginSimpleExample/facts/customFact';
+import { customOperator } from 'xfiPluginSimpleExample/operators/customOperator';
+
+describe('Custom Plugin Rule', () => {
+  it('should trigger when the custom fact produces expected data', async () => {
+    const factResult = await customFact.fn();
+    expect(factResult).toEqual({ result: 'custom fact data' });
+    
+    const operatorResult = customOperator.fn(factResult.result, 'custom fact data');
+    expect(operatorResult).toBe(true);
+  });
+});
+```
+Include these tests in your plugin’s test suite and run them via:
+```bash
+yarn test
+```
+
+### Final Notes
+
+These sample rules and unit tests not only serve as documentation for plugin usage but also help ensure that any future changes do not break your plugin's functionality.

package/README.md

@@ -42,6 +42,7 @@ x-fidelity is an advanced CLI tool and paired config server designed to perform
    - [Defining Archetypes](#defining-archetypes)
    - [Defining rules](#defining-rules)
    - [Included Operators](#included-operators)
+   - [External Plugin Extensions](#external-plugin-extensions)
 6. [Installation](#installation)
 7. [Usage](#usage)
    - [Basic Usage](#basic-usage)
@@ -52,6 +53,7 @@ x-fidelity is an advanced CLI tool and paired config server designed to perform
 8. [Hosting Config Servers](#hosting-config-servers)
    - [Docker Example](#docker-example)
 9. [Exemptions](#exemptions)
+10. [GitHub Webhook Endpoints](#github-webhook-endpoints)
 10. [CI Pipeline Integration](#ci-pipeline-integration)
 11. [OpenAI Integration](#openai-integration)
 12. [X-Fi Best Practices](#x-fi-best-practices)
@@ -82,7 +84,9 @@ The tool is designed to be highly customizable, allowing teams to define their o
 - **Content Analysis**: Search for specific patterns or strings within your codebase.
 - **Remote Configuration**: Fetch configurations from a remote server for centralized management.
 - **OpenAI Integration**: Leverage AI for advanced code analysis and suggestions.
-- **Extensible Architecture**: Easily add new operators, facts, and rules to suit your needs.
+- **Extensible Architecture**: Easily add new operators, facts, rules, and external plugin extensions to suit your needs.
+- **Enhanced Remote Validation:** Support for remote string validation via the `invalidRemoteValidation` operator. This operator allows x‑fidelity to send extracted string values to an external API (with interpolated parameters such as "#MATCH#") to validate them. (See the sample rule `invalidSystemIdConfigured-iterative-rule.json` in the demo config.)
+- **GitHub Webhook Integration:** The config server now exposes endpoints (e.g. `/github-config-update` and `/github-pull-request-check`) that let you trigger configuration reloads and validation checks automatically when a GitHub event (push or pull request) occurs.
 
 ## Components and entity names to understand
 
@@ -90,7 +94,7 @@ The tool is designed to be highly customizable, allowing teams to define their o
 
 - **Rule**: A set of conditions and corresponding actions that define a specific check or requirement for the codebase. Rules are used to identify warnings or fatal issues in the codebase.
 
-- **Exemption**: A time-limited waiver for a given git repo for a given rule until a configured expiry date.
+- **Exemption**: A time-limited waiver for a given git repo for a given rule until a configured expiry date. Exemptions can now be provided either as a single JSON file (e.g. `[archetype]-exemptions.json`) or by placing one or more JSON files in a directory named `[archetype]-exemptions`. Any file in that directory that matches the naming pattern will be merged into the effective exemptions.
 
 - **Operator**: A function that performs a specific comparison or check within a rule. Operators are used to evaluate conditions in rules.
 
@@ -160,7 +164,9 @@ This diagram shows the main components of x-fidelity and how they interact:
 - **Client Environments**: Where x-fidelity is used (CI systems or local development).
 - **x-fidelity Core**: The main components of the system, including the analysis engine, CLI interface, and configuration manager.
 - **x-fidelity Infrastructure**: Servers for configuration and telemetry.
-- **External Services**: GitHub for repository interaction and optional OpenAI integration.
+- **External Services**: GitHub for repository interaction and optional OpenAI integration. Includes GitHub Webhooks for triggering config refresh.
+- **Remote Validation**: Within the plugins outlined under “Extensions”.
+- **Enhanced Telemetry**: Flows from both client and server to the Telemetry Server.
 - **Data Sources**: The files and dependencies that x-fidelity analyzes.
 
 ## Configuring and Extending x-fidelity
@@ -376,6 +382,8 @@ Usage example in a rule:
     }
 }
 ```
+- **invalidRemoteValidation:** This operator is provided by the xfiPluginRemoteStringValidator plugin. It validates extracted string data by sending a request to a remote endpoint (using customizable HTTP method, headers, and a JSON body where “#MATCH#” is interpolated) and uses a JSONPath check on the response to decide if the value is valid.
+
 The 'openaiAnalysisHighSeverity' operator will be discussed in the section on the optional OpenAI integration feature.
 
 ## Installation
@@ -401,6 +409,12 @@ xfidelity
 
 ### Advanced Usage
 
+### Telemetry & Monitoring
+
+- Telemetry data is sent to a configurable endpoint via the `-t`/`--telemetryCollector` option.
+- Analysis start, analysis end (including error events) are issued via telemetry, with optional shared secret headers.
+- The CLI and config server now include built-in logging and telemetry support.
+
 Use command-line options for more control:
 
 ```sh
@@ -410,17 +424,18 @@ Arguments:
   directory                                      code directory to analyze
 
 Options:
-  -d, --dir <directory>                          code directory to analyze. if an arg was passed to command it
+  -d, --dir [directory]                          code directory to analyze. if an arg was passed to command it
                                                  will be treated as the dir (default: ".")
-  -a, --archetype <archetype>                    The archetype to use for analysis (default: "node-fullstack")
-  -c, --configServer <configServer>              The config server URL for fetching remote archetype
+  -a, --archetype [archetype]                    The archetype to use for analysis (default: "node-fullstack")
+  -c, --configServer [configServer]              The config server URL for fetching remote archetype
                                                  configurations and rules
-  -o, --openaiEnabled <boolean>                  Enable OpenAI analysis (default: false)
-  -t, --telemetryCollector <telemetryCollector>  The URL telemetry data will be sent to for usage analysis
-  -m, --mode <mode>                              Run mode: 'client' or 'server' (default: "client")
-  -p, --port <port>                              The port to run the server on (default: "8888")
-  -l, --localConfigPath <path>                   Path to local archetype config and rules
-  -j, --jsonTTL <minutes>                        Set the server json cache TTL in minutes (default: "10")
+  -o, --openaiEnabled [boolean]                 Enable OpenAI analysis (default: false)
+  -t, --telemetryCollector [<telemetryCollector]  The URL telemetry data will be sent to for usage analysis
+  -m, --mode [mode]                              Run mode: 'client' or 'server' (default: "client")
+  -p, --port [port]                              The port to run the server on (default: "8888")
+  -l, --localConfigPath [path]                   Path to local archetype config and rules
+  -j, --jsonTTL [minutes]                        Set the server JSON cache TTL in minutes (default: "10")
+  -e, --extensions <modules...>                  Space-separated list of npm module names to load as external plugin extensions
   -v, --version                                  Output the version number of xfidelity
   -h, --help                                     Display help for command
 ```
@@ -489,6 +504,13 @@ xfidelity -c https://config-server.example.com
 
 The remote server is also the xfidelity cli configured in server mode to serve archetype and rule configurations.
 
+## GitHub Webhook Endpoints
+
+The config server now supports GitHub webhook endpoints for real‑time updates:
+- **`/github-config-update`** – triggered on push events to clear the cache and refresh local configurations.
+- **`/github-pull-request-check`** – reserved for future pull-request–related validations.
+These endpoints require validation via secret headers and are configured via the `GITHUB_WEBHOOK_SECRET` environment variable.
+
 ## Hosting Config Servers
 
 x-fidelity allows for centrally managed, hot-updatable custom rulesets that can be executed within managed CI pipelines and locally, ensuring consistency of applied rules. Here's an overview of the setup required:
@@ -500,7 +522,7 @@ x-fidelity allows for centrally managed, hot-updatable custom rulesets that can
 5. Configure the CLI to:
    - Run on startup in server mode (`--mode server`)
    - Point to your rules directory cloned from GitHub (`--localConfigPath ../rule-repo/config`)
-   - Optionally set the port to listen on (`--port <port>`)
+   - Optionally set the port to listen on (`--port [port]`)
 6. Create a simple CI pipeline step 'framework fidelity' after git repo clone to workspace:
    - Install the x-fidelity CLI
    - Run the CLI on the checked-out repo, pointing to the server (`--configServer http://my-server:8888`)
@@ -509,7 +531,7 @@ x-fidelity allows for centrally managed, hot-updatable custom rulesets that can
 
 ### Docker Example
 
-x-fidelity server can run in Docker for easy deployment and configuration.  Here is a basic example for local testing.  A full repo example is available here: <todo>
+x-fidelity server can run in Docker for easy deployment and configuration.  Here is a basic example for local testing.  A full repo example is available here: todo
 
 #### Using Docker Compose
 
@@ -583,7 +605,7 @@ Exemptions in x-fidelity provide a way to temporarily waive specific rules for a
 
 1. **Definition**: An exemption is defined for a specific rule and repository URL, with an expiration date and a reason.
 
-2. **Storage**: Exemptions are stored in JSON files, typically named `<archetype>-exemptions.json` (e.g., `node-fullstack-exemptions.json`).  NEW a directory named <archetype>-exemptions can be created in the config dir and each json file matching `*-<archetype>-exemptions.json`will also be included.
+2. **Storage**: Exemptions are stored in JSON files, typically named `[archetype]-exemptions.json` (e.g., `node-fullstack-exemptions.json`).  NEW a directory named [archetype]-exemptions can be created in the config dir and each json file matching `*-[archetype]-exemptions.json`will also be included.
 
 3. **Structure**: Each exemption is an object with the following properties:
    - `repoUrl`: The URL of the repository where the exemption applies.
@@ -805,6 +827,78 @@ Example `.xfi-config.json`:
 
 Remember, while `.xfi-config.json` allows you to adjust x-fidelity's behavior in limited ways, it should be used judiciously to maintain the integrity of your code quality checks.
 
+### Using Extensions
+
+New extensions are available:
+- *Remote String Validation Plugin:* (module: `xfiPluginRemoteStringValidator`) adds remote validation functionality via the `remoteSubstringValidation` fact and the `invalidRemoteValidation` operator.
+- *Sample Custom Plugin:* (module: `xfiPluginSimpleExample`) shows how to add custom facts and operators.
+
+To load these plugins, pass their module names via the `-e` (or `--extensions`) CLI option.
+
+x-fidelity supports custom extensions through npm modules. To use extensions:
+
+1. Install the extension packages:
+```bash
+npm install xfi-basic-plugin xfi-another-plugin
+```
+
+2. Run x-fidelity with the extensions:
+```bash
+xfidelity -e xfi-basic-plugin xfi-another-plugin
+```
+
+Multiple extensions can be specified by separating them with spaces.
+
+### Creating Extensions
+
+You can create custom extensions by implementing the XFiPlugin interface:
+
+```typescript
+interface XFiPlugin {
+  name: string;
+  version: string;
+  facts?: {
+    name: string;
+    fn: Function;
+  }[];
+  operators?: OperatorDefn[];
+}
+```
+
+Example extension:
+```javascript
+module.exports = {
+  name: 'my-extension',
+  version: '1.0.0',
+  facts: [{
+    name: 'myCustomFact',
+    fn: async () => ({ result: 'custom data' })
+  }],
+  operators: [{
+    name: 'myCustomOperator',
+    fn: (factValue, expectedValue) => factValue === expectedValue
+  }]
+};
+```
+
+### External Plugin Extensions
+
+x-fidelity now supports external plugin extensions that allow you to extend its core functionality without modifying the main codebase. These plugins conform to the XFiPlugin interface and can be loaded at runtime.
+
+**How to use external plugin extensions:**
+1. Install the extension package(s) via npm. For example, run:
+   ```bash
+   npm install xfi-basic-plugin xfi-another-plugin
+   ```
+2. Start x-fidelity and pass the extension names using the `-e` or `--extensions` option:
+   ```bash
+   xfidelity /path/to/project -e xfi-basic-plugin xfi-another-plugin
+   ```
+   
+You can specify multiple plugins, separated by spaces.
+
+For more details on creating your own plugin extensions, please refer to the [PLUGIN_GUIDANCE.md](PLUGIN_GUIDANCE.md) file.
+
 ## Contributing
 
 Contributions to x-fidelity are welcome! Please refer to the `CONTRIBUTING.md` file for guidelines on how to contribute to this project.

package/dist/core/cli.d.ts

@@ -0,0 +1,3 @@
+export declare const DEMO_CONFIG_PATH: string;
+declare const options: import("commander").OptionValues;
+export { options };