x-fidelity 3.8.0 → 3.9.0

package/.xfi-config.json

@@ -1,5 +1,38 @@
 {
     "sensitiveFileFalsePositives": [
         "/src/facts/repoFilesystemFacts.ts"
-    ]
+    ],
+    "additionalRules": [
+        {
+            "name": "custom-rule",
+            "conditions": {
+                "all": [
+                    {
+                        "fact": "fileData",
+                        "path": "$.fileName",
+                        "operator": "equal",
+                        "value": "REPO_GLOBAL_CHECK"
+                    },
+                    {
+                        "fact": "customFact",
+                        "operator": "customOperator",
+                        "value": "custom fact data"
+                    }
+                ]
+            },
+            "event": {
+                "type": "warning",
+                "params": {
+                    "message": "Custom rule detected matching data",
+                    "details": {
+                        "fact": "customFact"
+                    }
+                }
+            }
+        }
+        
+    ],
+    "additionalFacts": ["customFact"],
+    "additionalOperators": ["customOperator"],
+    "additionalPlugins": ["xfiPluginSimpleExample"]
 }

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+# [3.9.0](https://github.com/zotoio/x-fidelity/compare/v3.8.1...v3.9.0) (2025-03-02)
+
+
+### Bug Fixes
+
+* add optional chaining for rule name access in analyzer ([d0c4b02](https://github.com/zotoio/x-fidelity/commit/d0c4b02c83bf77cade8e7310fe14ad0b10dd00c1))
+* add type assertion to resolve schema type compatibility issue ([76f7618](https://github.com/zotoio/x-fidelity/commit/76f761869a85d09eb18a047010e6409475c766fc))
+* **demo:** minor logic and test fix ([3b03804](https://github.com/zotoio/x-fidelity/commit/3b0380465dcc75355941f5e1818187f9b448ef6c))
+* register plugin facts and operators before loading custom rules ([5ab7667](https://github.com/zotoio/x-fidelity/commit/5ab76675c7387a78bb43cb8bd959362a89e16ae9))
+* resolve TypeScript error by casting rule to any type ([eba8fd1](https://github.com/zotoio/x-fidelity/commit/eba8fd1b968d64ec867ebeca76a92a2764321a08))
+* resolve TypeScript errors in schema validation and rule handling ([8f3dd6f](https://github.com/zotoio/x-fidelity/commit/8f3dd6ffca0956a30a4b17794e1b2e0cdee178c0))
+* update custom rule filename and enhance fact almanac handling ([8d11d55](https://github.com/zotoio/x-fidelity/commit/8d11d55c930e4389185905449dc6561958386317))
+
+
+### Features
+
+* Add custom rule configuration with example plugin and operators ([7e54510](https://github.com/zotoio/x-fidelity/commit/7e54510d9ef25249d70f3e4691f9aae203bf2489))
+* add support for custom rules and plugins in .xfi-config.json ([6206802](https://github.com/zotoio/x-fidelity/commit/62068028636b2da1a7f25df503be6bbb7c8dfdb3))
+
+## [3.8.1](https://github.com/zotoio/x-fidelity/compare/v3.8.0...v3.8.1) (2025-03-02)
+
+
+### Bug Fixes
+
+* **commitzen:** fix glob compatibilty issue ([73a7058](https://github.com/zotoio/x-fidelity/commit/73a7058e82d5853ceff3d3e5e3e48a03180f077d))
+
 # [3.8.0](https://github.com/zotoio/x-fidelity/compare/v3.7.1...v3.8.0) (2025-03-02)
 
 

package/README.md

@@ -802,9 +802,13 @@ The `.xfi-config.json` file allows you to configure x-fidelity behavior specific
 
 ### Configuration Options
 
-Currently, the `.xfi-config.json` file supports the following options:
+The `.xfi-config.json` file supports the following options:
 
 1. `sensitiveFileFalsePositives`: An array of file paths that should be excluded from sensitive data checks.
+2. `additionalPlugins`: An array of plugin module names to load for this repository.
+3. `additionalFacts`: An array of fact names to add to the archetype's facts.
+4. `additionalOperators`: An array of operator names to add to the archetype's operators.
+5. `additionalRules`: An array of custom rule definitions to add to the archetype's rules.
 
 Example `.xfi-config.json`:
 
@@ -813,6 +817,44 @@ Example `.xfi-config.json`:
   "sensitiveFileFalsePositives": [
     "path/to/exclude/file1.js",
     "path/to/exclude/file2.ts"
+  ],
+  "additionalPlugins": [
+    "xfiPluginSimpleExample"
+  ],
+  "additionalFacts": [
+    "customFact"
+  ],
+  "additionalOperators": [
+    "customOperator"
+  ],
+  "additionalRules": [
+    {
+      "name": "custom-rule",
+      "conditions": {
+        "all": [
+          {
+            "fact": "fileData",
+            "path": "$.fileName",
+            "operator": "equal",
+            "value": "REPO_GLOBAL_CHECK"
+          },
+          {
+            "fact": "customFact",
+            "operator": "customOperator",
+            "value": "custom fact data"
+          }
+        ]
+      },
+      "event": {
+        "type": "warning",
+        "params": {
+          "message": "Custom rule detected matching data",
+          "details": {
+            "fact": "customFact"
+          }
+        }
+      }
+    }
   ]
 }
 ```
@@ -822,16 +864,19 @@ Example `.xfi-config.json`:
 - When x-fidelity runs, it looks for the `.xfi-config.json` file in your project's root directory.
 - If found, it applies the configurations specified in this file.
 - For `sensitiveFileFalsePositives`, the specified files will be excluded from checks that look for sensitive data, such as API keys or passwords.
+- For `additionalPlugins`, the specified plugins will be loaded, making their facts and operators available.
+- For `additionalFacts` and `additionalOperators`, the specified facts and operators will be added to the archetype's facts and operators.
+- For `additionalRules`, the specified rules will be added to the archetype's rules.
 
 ### How to use it
 
 1. **Version Control**: Include `.xfi-config.json` in your version control system to ensure consistency across your team.
-2. **Documentation**: Add comments in the listed file explaining why it is a false positive.
-3. **Regular Review**: Periodically review your `.xfi-config.json` to ensure the exclusions are still necessary and valid.
-4. **Minimal Use**: Use exclusions sparingly. It's better to fix issues than to exclude them from checks.
-5. **Feedback**: If the rules being applied are resulting in too many false-postives, speak with the team that manages your central rule config.
+2. **Documentation**: Add comments in the listed file explaining why it is a false positive or why custom rules are needed.
+3. **Regular Review**: Periodically review your `.xfi-config.json` to ensure the configurations are still necessary and valid.
+4. **Minimal Use**: Use exclusions and custom rules sparingly. It's better to fix issues than to exclude them from checks.
+5. **Feedback**: If the rules being applied are resulting in too many false-positives, speak with the team that manages your central rule config.
 
-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.
+Remember, while `.xfi-config.json` allows you to adjust x-fidelity's behavior, it should be used judiciously to maintain the integrity of your code quality checks.
 
 ### Using Extensions
 

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 3.8.x   | :white_check_mark: |
+| 2.17.x  | :white_check_mark: |
+| < 2.17  | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability within x-fi, please submit a report via the GitHub's Private Vulnerability Reporting feature.
+
+All security vulnerabilities will be promptly addressed.

package/dist/core/engine/analyzer.js

@@ -22,6 +22,8 @@ const telemetryCollector_1 = require("./telemetryCollector");
 const engineSetup_1 = require("./engineSetup");
 const engineRunner_1 = require("./engineRunner");
 const utils_1 = require("../../utils/utils");
+const jsonSchemas_1 = require("../../utils/jsonSchemas");
+const pluginRegistry_1 = require("../pluginRegistry");
 const cli_1 = require("../cli");
 function analyzeCodebase(params) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -45,6 +47,25 @@ function analyzeCodebase(params) {
         const installedDependencyVersions = yield (0, repoDependencyFacts_1.getDependencyVersionFacts)(archetypeConfig);
         const fileData = yield (0, repoFilesystemFacts_1.collectRepoFileData)(repoPath, archetypeConfig);
         const repoXFIConfig = yield (0, repoXFIConfigLoader_1.loadRepoXFIConfig)(repoPath);
+        // Load additional plugins from repo config
+        if (repoXFIConfig.additionalPlugins && repoXFIConfig.additionalPlugins.length > 0) {
+            logger_1.logger.info(`Loading additional plugins from repo config: ${repoXFIConfig.additionalPlugins.join(', ')}`);
+            try {
+                yield configManager_1.ConfigManager.loadPlugins(repoXFIConfig.additionalPlugins);
+            }
+            catch (error) {
+                logger_1.logger.warn(`Error loading additional plugins from repo config: ${error}`);
+            }
+        }
+        // Merge additional components into archetype config
+        if (repoXFIConfig.additionalFacts) {
+            archetypeConfig.facts = [...new Set([...archetypeConfig.facts, ...repoXFIConfig.additionalFacts])];
+            logger_1.logger.info(`Added additional facts from repo config: ${repoXFIConfig.additionalFacts.join(', ')}`);
+        }
+        if (repoXFIConfig.additionalOperators) {
+            archetypeConfig.operators = [...new Set([...archetypeConfig.operators, ...repoXFIConfig.additionalOperators])];
+            logger_1.logger.info(`Added additional operators from repo config: ${repoXFIConfig.additionalOperators.join(', ')}`);
+        }
         // add REPO_GLOBAL_CHECK to fileData, which is the trigger for global checks
         fileData.push({
             fileName: configManager_1.REPO_GLOBAL_CHECK,
@@ -63,6 +84,44 @@ function analyzeCodebase(params) {
             localConfigPath,
             repoUrl
         });
+        // Add plugin facts and operators directly to the engine
+        if (repoXFIConfig.additionalFacts) {
+            const pluginFacts = pluginRegistry_1.pluginRegistry.getPluginFacts();
+            for (const factName of repoXFIConfig.additionalFacts) {
+                const fact = pluginFacts.find(f => f.name === factName);
+                if (fact) {
+                    logger_1.logger.info(`Adding custom fact to engine: ${fact.name}`);
+                    engine.addFact(fact.name, fact.fn, { priority: fact.priority || 1 });
+                }
+            }
+        }
+        if (repoXFIConfig.additionalOperators) {
+            const pluginOperators = pluginRegistry_1.pluginRegistry.getPluginOperators();
+            for (const operatorName of repoXFIConfig.additionalOperators) {
+                const operator = pluginOperators.find(o => o.name === operatorName);
+                if (operator) {
+                    logger_1.logger.info(`Adding custom operator to engine: ${operator.name}`);
+                    engine.addOperator(operator.name, operator.fn);
+                }
+            }
+        }
+        // Load additional rules from repo config
+        if (repoXFIConfig.additionalRules && repoXFIConfig.additionalRules.length > 0) {
+            logger_1.logger.info(`Loading additional rules from repo config: ${repoXFIConfig.additionalRules.length} rules`);
+            for (const rule of repoXFIConfig.additionalRules) {
+                if ((0, jsonSchemas_1.validateRule)(rule)) {
+                    logger_1.logger.info(`Adding custom rule from repo config: ${rule.name}`);
+                    // Convert RuleConfig to RuleProperties for Engine
+                    const ruleProperties = Object.assign(Object.assign({}, rule), { conditions: rule.conditions });
+                    engine.addRule(ruleProperties);
+                }
+                else {
+                    // Cast rule to any to safely access name property
+                    const ruleName = (rule === null || rule === void 0 ? void 0 : rule.name) || 'unnamed rule';
+                    logger_1.logger.warn(`Invalid custom rule in repo config: ${ruleName}`);
+                }
+            }
+        }
         if ((0, openaiUtils_1.isOpenAIEnabled)() && archetypeConfig.facts.includes('openaiAnalysisFacts')) {
             logger_1.logger.info(`adding additional openai facts to engine..`);
             engine.addFact('openaiAnalysis', openaiAnalysisFacts_1.openaiAnalysis);

package/dist/plugins/xfiPluginSimpleExample/facts/customFact.js

@@ -17,10 +17,15 @@ const logger_1 = require("../../../utils/logger");
  */
 exports.customFact = {
     name: 'customFact',
-    fn: (params) => __awaiter(void 0, void 0, void 0, function* () {
+    fn: (params, almanac) => __awaiter(void 0, void 0, void 0, function* () {
         try {
             logger_1.logger.debug('Executing customFact');
-            return { result: 'custom fact data' };
+            const result = 'custom fact data';
+            // Add the result to the almanac if resultFact is provided
+            if (params && params.resultFact) {
+                almanac.addRuntimeFact(params.resultFact, result);
+            }
+            return result;
         }
         catch (error) {
             logger_1.logger.error(`Error in customFact: ${error}`);

package/dist/plugins/xfiPluginSimpleExample/facts/customFact.test.js

@@ -16,6 +16,6 @@ describe('customFact', () => {
             factValue: jest.fn()
         };
         const result = yield customFact_1.customFact.fn({}, mockAlmanac);
-        expect(result).toEqual({ result: 'custom fact data' });
+        expect(result).toEqual('custom fact data');
     }));
 });

package/dist/types/typeDefs.d.ts

@@ -242,6 +242,10 @@ export interface ValidationResult {
 }
 export interface RepoXFIConfig {
     sensitiveFileFalsePositives?: string[];
+    additionalRules?: RuleConfig[];
+    additionalFacts?: string[];
+    additionalOperators?: string[];
+    additionalPlugins?: string[];
     [key: string]: any;
 }
 export type RepoXFIConfigSchema = JSONSchemaType<RepoXFIConfig>;

package/dist/utils/jsonSchemas.js

@@ -12,6 +12,7 @@ ajv.addFormat("semverPattern", {
     type: "string",
     validate: (x) => semver_1.default.valid(x) !== null && semver_1.default.validRange(x) !== null,
 });
+// Using a simpler schema definition to avoid TypeScript errors with complex Ajv types
 const repoXFIConfigSchema = {
     type: "object",
     properties: {
@@ -21,6 +22,30 @@ const repoXFIConfigSchema = {
             minItems: 0,
             nullable: true,
         },
+        additionalRules: {
+            type: "array",
+            items: { type: "object" },
+            minItems: 0,
+            nullable: true,
+        },
+        additionalFacts: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 0,
+            nullable: true,
+        },
+        additionalOperators: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 0,
+            nullable: true,
+        },
+        additionalPlugins: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 0,
+            nullable: true,
+        },
     },
     required: [],
     additionalProperties: true,

package/dist/utils/repoXFIConfigLoader.js

@@ -40,6 +40,16 @@ function loadRepoXFIConfig(repoPath) {
                         return filePath;
                     });
                 }
+                // Validate additional rules if present
+                if (parsedConfig.additionalRules && Array.isArray(parsedConfig.additionalRules)) {
+                    for (let i = 0; i < parsedConfig.additionalRules.length; i++) {
+                        if (!(0, jsonSchemas_1.validateRule)(parsedConfig.additionalRules[i])) {
+                            logger_1.logger.warn(`Invalid rule at index ${i} in .xfi-config.json, removing it`);
+                            parsedConfig.additionalRules.splice(i, 1);
+                            i--;
+                        }
+                    }
+                }
                 return parsedConfig;
             }
             else {

package/dist/utils/ruleUtils.d.ts

@@ -1,3 +1,4 @@
 import { LoadRulesParams, RuleConfig } from '../types/typeDefs';
 declare function loadRules(params: LoadRulesParams): Promise<RuleConfig[]>;
-export { loadRules };
+declare function validateCustomRules(rules: any[]): RuleConfig[];
+export { loadRules, validateCustomRules };

package/dist/utils/ruleUtils.js

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadRules = loadRules;
+exports.validateCustomRules = validateCustomRules;
 const logger_1 = require("./logger");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -92,3 +93,16 @@ function loadLocalConfigRule(params) {
         return result;
     });
 }
+// Function to validate custom rules
+function validateCustomRules(rules) {
+    const validRules = [];
+    for (const rule of rules) {
+        if ((0, jsonSchemas_1.validateRule)(rule)) {
+            validRules.push(rule);
+        }
+        else {
+            logger_1.logger.error(`Invalid custom rule: ${rule.name || 'unnamed'}`);
+        }
+    }
+    return validRules;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x-fidelity",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "cli for opinionated framework adherence checks",
   "main": "dist/index",
   "types": "dist/index.d.ts",
@@ -103,9 +103,6 @@
   "peerDependencies": {
     "artillery": "^2.0.22"
   },
-  "resolutions": {
-    "glob": "^10.0.0"
-  },
   "config": {
     "commitizen": {
       "path": "./node_modules/cz-conventional-changelog"

package/src/core/engine/analyzer.ts

@@ -11,6 +11,8 @@ import { collectTelemetryData } from './telemetryCollector';
 import { setupEngine } from './engineSetup';
 import { runEngineOnFiles } from './engineRunner';
 import { countRuleFailures, safeStringify } from '../../utils/utils';
+import { validateRule } from '../../utils/jsonSchemas';
+import { pluginRegistry } from '../pluginRegistry';
 
 import { AnalyzeCodebaseParams } from '../../types/typeDefs';
 import { options } from '../cli';
@@ -41,6 +43,27 @@ export async function analyzeCodebase(params: AnalyzeCodebaseParams): Promise<Re
     const installedDependencyVersions = await getDependencyVersionFacts(archetypeConfig);
     const fileData = await collectRepoFileData(repoPath, archetypeConfig);
     const repoXFIConfig = await loadRepoXFIConfig(repoPath);
+    
+    // Load additional plugins from repo config
+    if (repoXFIConfig.additionalPlugins && repoXFIConfig.additionalPlugins.length > 0) {
+        logger.info(`Loading additional plugins from repo config: ${repoXFIConfig.additionalPlugins.join(', ')}`);
+        try {
+            await ConfigManager.loadPlugins(repoXFIConfig.additionalPlugins);
+        } catch (error) {
+            logger.warn(`Error loading additional plugins from repo config: ${error}`);
+        }
+    }
+    
+    // Merge additional components into archetype config
+    if (repoXFIConfig.additionalFacts) {
+        archetypeConfig.facts = [...new Set([...archetypeConfig.facts, ...repoXFIConfig.additionalFacts])];
+        logger.info(`Added additional facts from repo config: ${repoXFIConfig.additionalFacts.join(', ')}`);
+    }
+    
+    if (repoXFIConfig.additionalOperators) {
+        archetypeConfig.operators = [...new Set([...archetypeConfig.operators, ...repoXFIConfig.additionalOperators])];
+        logger.info(`Added additional operators from repo config: ${repoXFIConfig.additionalOperators.join(', ')}`);
+    }
 
     // add REPO_GLOBAL_CHECK to fileData, which is the trigger for global checks
     fileData.push({
@@ -64,6 +87,49 @@ export async function analyzeCodebase(params: AnalyzeCodebaseParams): Promise<Re
         repoUrl
     });
 
+    // Add plugin facts and operators directly to the engine
+    if (repoXFIConfig.additionalFacts) {
+        const pluginFacts = pluginRegistry.getPluginFacts();
+        for (const factName of repoXFIConfig.additionalFacts) {
+            const fact = pluginFacts.find(f => f.name === factName);
+            if (fact) {
+                logger.info(`Adding custom fact to engine: ${fact.name}`);
+                engine.addFact(fact.name, fact.fn, { priority: fact.priority || 1 });
+            }
+        }
+    }
+
+    if (repoXFIConfig.additionalOperators) {
+        const pluginOperators = pluginRegistry.getPluginOperators();
+        for (const operatorName of repoXFIConfig.additionalOperators) {
+            const operator = pluginOperators.find(o => o.name === operatorName);
+            if (operator) {
+                logger.info(`Adding custom operator to engine: ${operator.name}`);
+                engine.addOperator(operator.name, operator.fn);
+            }
+        }
+    }
+
+    // Load additional rules from repo config
+    if (repoXFIConfig.additionalRules && repoXFIConfig.additionalRules.length > 0) {
+        logger.info(`Loading additional rules from repo config: ${repoXFIConfig.additionalRules.length} rules`);
+        for (const rule of repoXFIConfig.additionalRules) {
+            if (validateRule(rule)) {
+                logger.info(`Adding custom rule from repo config: ${rule.name}`);
+                // Convert RuleConfig to RuleProperties for Engine
+                const ruleProperties = {
+                    ...rule,
+                    conditions: rule.conditions as any
+                };
+                engine.addRule(ruleProperties);
+            } else {
+                // Cast rule to any to safely access name property
+                const ruleName = (rule as any)?.name || 'unnamed rule';
+                logger.warn(`Invalid custom rule in repo config: ${ruleName}`);
+            }
+        }
+    }
+
     if (isOpenAIEnabled() && archetypeConfig.facts.includes('openaiAnalysisFacts')) {
         logger.info(`adding additional openai facts to engine..`);
         engine.addFact('openaiAnalysis', openaiAnalysis);

package/src/plugins/xfiPluginSimpleExample/facts/customFact.test.ts

@@ -6,6 +6,6 @@ describe('customFact', () => {
             factValue: jest.fn()
         };
         const result = await customFact.fn({}, mockAlmanac);
-        expect(result).toEqual({ result: 'custom fact data' });
+        expect(result).toEqual('custom fact data');
     });
 });

package/src/plugins/xfiPluginSimpleExample/facts/customFact.ts

@@ -7,10 +7,17 @@ import { logger } from '../../../utils/logger';
  */
 export const customFact: FactDefn = {
     name: 'customFact',
-    fn: async (params) => {
+    fn: async (params, almanac) => {
         try {
             logger.debug('Executing customFact');
-            return { result: 'custom fact data' };
+            const result = 'custom fact data';
+            
+            // Add the result to the almanac if resultFact is provided
+            if (params && params.resultFact) {
+                almanac.addRuntimeFact(params.resultFact, result);
+            }
+            
+            return result;
         } catch (error) {
             logger.error(`Error in customFact: ${error}`);
             throw error;

package/src/types/typeDefs.ts

@@ -275,6 +275,10 @@ export interface ValidationResult {
 
 export interface RepoXFIConfig {
   sensitiveFileFalsePositives?: string[];
+  additionalRules?: RuleConfig[];
+  additionalFacts?: string[];
+  additionalOperators?: string[];
+  additionalPlugins?: string[];
   [key: string]: any;  // Allow for additional properties
 }
 

package/src/utils/jsonSchemas.ts

@@ -15,7 +15,8 @@ ajv.addFormat("semverPattern", {
     validate: (x) => semver.valid(x) !== null && semver.validRange(x) !== null,
 });
 
-const repoXFIConfigSchema: RepoXFIConfigSchema = {
+// Using a simpler schema definition to avoid TypeScript errors with complex Ajv types
+const repoXFIConfigSchema = {
     type: "object",
     properties: {
         sensitiveFileFalsePositives: {
@@ -24,10 +25,34 @@ const repoXFIConfigSchema: RepoXFIConfigSchema = {
             minItems: 0,
             nullable: true,
         },
+        additionalRules: {
+            type: "array",
+            items: { type: "object" },
+            minItems: 0,
+            nullable: true,
+        },
+        additionalFacts: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 0,
+            nullable: true,
+        },
+        additionalOperators: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 0,
+            nullable: true,
+        },
+        additionalPlugins: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 0,
+            nullable: true,
+        },
     },
     required: [],
     additionalProperties: true,
-};
+} as unknown as RepoXFIConfigSchema;
 
 const archetypeSchema: ArchetypeConfigSchema = {
     type: "object",

package/src/utils/repoXFIConfigLoader.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import { isPathInside } from './pathUtils';
 import { logger } from './logger';
 import { RepoXFIConfig } from '../types/typeDefs';
-import { validateXFIConfig } from './jsonSchemas';
+import { validateXFIConfig, validateRule } from './jsonSchemas';
 
 const defaultXFIConfig: RepoXFIConfig = {
   sensitiveFileFalsePositives: []};
@@ -29,6 +29,17 @@ export async function loadRepoXFIConfig(repoPath: string): Promise<RepoXFIConfig
         });
       }
 
+      // Validate additional rules if present
+      if (parsedConfig.additionalRules && Array.isArray(parsedConfig.additionalRules)) {
+        for (let i = 0; i < parsedConfig.additionalRules.length; i++) {
+          if (!validateRule(parsedConfig.additionalRules[i])) {
+            logger.warn(`Invalid rule at index ${i} in .xfi-config.json, removing it`);
+            parsedConfig.additionalRules.splice(i, 1);
+            i--;
+          }
+        }
+      }
+
       return parsedConfig;
     } else {
       logger.warn(`Ignoring invalid .xfi-config.json file, returing default config: ${JSON.stringify(defaultXFIConfig)}`);

package/src/utils/ruleUtils.ts

@@ -78,4 +78,19 @@ async function loadLocalConfigRule(params: LoadLocalConfigRuleParams): Promise<R
     return result;
 }
 
-export { loadRules };
+// Function to validate custom rules
+function validateCustomRules(rules: any[]): RuleConfig[] {
+  const validRules: RuleConfig[] = [];
+  
+  for (const rule of rules) {
+    if (validateRule(rule)) {
+      validRules.push(rule);
+    } else {
+      logger.error(`Invalid custom rule: ${rule.name || 'unnamed'}`);
+    }
+  }
+  
+  return validRules;
+}
+
+export { loadRules, validateCustomRules };

package/website/docs/xfi-config.md

@@ -11,6 +11,7 @@ The `.xfi-config.json` file allows you to configure x-fidelity behavior specific
 The `.xfi-config.json` file provides repository-specific configurations that override or supplement global settings. This is particularly useful for:
 - Excluding false positives
 - Customizing behavior for specific repositories
+- Adding custom rules, facts, operators, and plugins
 - Managing repository-specific exceptions
 
 ## Configuration File
@@ -22,7 +23,11 @@ Place `.xfi-config.json` in your repository's root directory:
   "sensitiveFileFalsePositives": [
     "path/to/exclude/file1.js",
     "path/to/exclude/file2.ts"
-  ]
+  ],
+  "additionalRules": [],
+  "additionalFacts": [],
+  "additionalOperators": [],
+  "additionalPlugins": []
 }
 ```
 
@@ -45,26 +50,254 @@ An array of file paths that should be excluded from sensitive data checks:
 - Supports glob patterns
 - Case-sensitive matching
 
-## Usage Examples
+### additionalPlugins
 
-### Excluding Test Files
+An array of plugin module names to load for this repository:
 
 ```json
 {
-  "sensitiveFileFalsePositives": [
-    "test/**/*.mock.ts",
-    "test/fixtures/*.json"
+  "additionalPlugins": [
+    "xfiPluginSimpleExample",
+    "xfiPluginRequiredFiles",
+    "xfiPluginRemoteStringValidator"
   ]
 }
 ```
 
-### Excluding Configuration Files
+- Plugin modules must be installed and accessible to x-fidelity
+- Plugins provide custom facts and operators that can be used in rules
+- Repository-specific plugins are loaded after archetype-specified plugins
+
+### additionalFacts
+
+An array of fact names to add to the archetype's facts:
+
+```json
+{
+  "additionalFacts": [
+    "customFact",
+    "missingRequiredFiles",
+    "remoteSubstringValidation"
+  ]
+}
+```
+
+- Facts must be provided by loaded plugins
+- Repository-specific facts are merged with archetype facts
+- Duplicate fact names are only loaded once
+
+### additionalOperators
+
+An array of operator names to add to the archetype's operators:
+
+```json
+{
+  "additionalOperators": [
+    "customOperator",
+    "missingRequiredFiles",
+    "invalidRemoteValidation"
+  ]
+}
+```
+
+- Operators must be provided by loaded plugins
+- Repository-specific operators are merged with archetype operators
+- Duplicate operator names are only loaded once
+
+### additionalRules
+
+An array of custom rule definitions to add to the archetype's rules:
+
+```json
+{
+  "additionalRules": [
+    {
+      "name": "custom-rule",
+      "conditions": {
+        "all": [
+          {
+            "fact": "fileData",
+            "path": "$.fileName",
+            "operator": "equal",
+            "value": "REPO_GLOBAL_CHECK"
+          },
+          {
+            "fact": "customFact",
+            "operator": "customOperator",
+            "value": "custom fact data"
+          }
+        ]
+      },
+      "event": {
+        "type": "warning",
+        "params": {
+          "message": "Custom rule detected matching data",
+          "details": {
+            "fact": "customFact"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+- Rules must follow the standard rule schema
+- Rules can use any facts and operators available (including custom ones)
+- Repository-specific rules are added to the archetype rules
+- Rules are validated before being added
+
+## Complete Example
+
+Here's a complete example of a `.xfi-config.json` file that uses all available options:
 
 ```json
 {
   "sensitiveFileFalsePositives": [
-    "config/*.example.js",
-    "src/defaults.ts"
+    "src/config/defaults.ts",
+    "test/fixtures/mockData.js"
+  ],
+  "additionalPlugins": [
+    "xfiPluginSimpleExample"
+  ],
+  "additionalFacts": [
+    "customFact"
+  ],
+  "additionalOperators": [
+    "customOperator"
+  ],
+  "additionalRules": [
+    {
+      "name": "custom-rule",
+      "conditions": {
+        "all": [
+          {
+            "fact": "fileData",
+            "path": "$.fileName",
+            "operator": "equal",
+            "value": "REPO_GLOBAL_CHECK"
+          },
+          {
+            "fact": "customFact",
+            "operator": "customOperator",
+            "value": "custom fact data"
+          }
+        ]
+      },
+      "event": {
+        "type": "warning",
+        "params": {
+          "message": "Custom rule detected matching data",
+          "details": {
+            "fact": "customFact"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+## Usage Examples
+
+### Adding Custom Validation with Remote API
+
+```json
+{
+  "additionalPlugins": ["xfiPluginRemoteStringValidator"],
+  "additionalFacts": ["remoteSubstringValidation"],
+  "additionalOperators": ["invalidRemoteValidation"],
+  "additionalRules": [
+    {
+      "name": "invalid-system-id",
+      "conditions": {
+        "all": [
+          {
+            "fact": "fileData",
+            "path": "$.fileName",
+            "operator": "equal",
+            "value": "config.json"
+          },
+          {
+            "fact": "remoteSubstringValidation",
+            "params": {
+              "pattern": "\"systemId\":[\\s]*\"([a-z]*)\"",
+              "flags": "gi",
+              "validationParams": {
+                "url": "http://validation-api/validate",
+                "method": "POST",
+                "headers": {
+                  "Content-Type": "application/json"
+                },
+                "body": {
+                  "systemId": "#MATCH#"
+                },
+                "checkJsonPath": "$.validSystems[?(@.id == '#MATCH#')]"
+              },
+              "resultFact": "systemIdValidationResult"
+            },
+            "operator": "invalidRemoteValidation",
+            "value": true
+          }
+        ]
+      },
+      "event": {
+        "type": "fatality",
+        "params": {
+          "message": "Invalid system ID detected in configuration",
+          "details": {
+            "fact": "systemIdValidationResult"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Enforcing Required Files
+
+```json
+{
+  "additionalPlugins": ["xfiPluginRequiredFiles"],
+  "additionalFacts": ["missingRequiredFiles"],
+  "additionalOperators": ["missingRequiredFiles"],
+  "additionalRules": [
+    {
+      "name": "required-files-check",
+      "conditions": {
+        "all": [
+          {
+            "fact": "fileData",
+            "path": "$.fileName",
+            "operator": "equal",
+            "value": "REPO_GLOBAL_CHECK"
+          },
+          {
+            "fact": "missingRequiredFiles",
+            "params": {
+              "requiredFiles": [
+                "/README.md",
+                "/CONTRIBUTING.md",
+                "/LICENSE"
+              ],
+              "resultFact": "missingRequiredFilesResult"
+            },
+            "operator": "missingRequiredFiles",
+            "value": true
+          }
+        ]
+      },
+      "event": {
+        "type": "warning",
+        "params": {
+          "message": "Required files are missing from the repository",
+          "details": {
+            "fact": "missingRequiredFilesResult"
+          }
+        }
+      }
+    }
   ]
 }
 ```
@@ -72,48 +305,33 @@ An array of file paths that should be excluded from sensitive data checks:
 ## Best Practices
 
 1. **Version Control**:
-   - Include `.xfi-config.json` in version control
-   - Document changes in commit messages
-   - Review changes during code review
+   - Include `.xfi-config.json` in your version control system to ensure consistency across your team.
+   - Document changes in commit messages.
+   - Review changes during code review.
 
 2. **Documentation**:
-   - Comment excluded files
-   - Explain exclusion reasons
-   - Keep documentation up-to-date
+   - Comment custom rules and their purpose.
+   - Explain why specific plugins are needed.
+   - Keep documentation up-to-date.
 
 3. **Regular Review**:
-   - Periodically review exclusions
-   - Remove unnecessary exclusions
-   - Update as codebase changes
+   - Periodically review your `.xfi-config.json` to ensure the configurations are still necessary and valid.
+   - Remove unnecessary rules or plugins.
+   - Update as codebase changes.
 
 4. **Minimal Use**:
-   - Use sparingly
-   - Fix issues when possible
-   - Don't use to bypass security checks
+   - Use custom rules sparingly.
+   - Consider adding important rules to the archetype configuration instead.
+   - Don't use to bypass security checks.
 
 5. **Team Communication**:
-   - Discuss exclusions with team
-   - Document decisions
-   - Consider alternatives
+   - Discuss custom rules with team.
+   - Document decisions.
+   - Consider alternatives.
 
 ## Validation
 
-x-fidelity validates `.xfi-config.json` using JSON Schema:
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "sensitiveFileFalsePositives": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    }
-  },
-  "additionalProperties": false
-}
-```
+x-fidelity validates `.xfi-config.json` using JSON Schema. Custom rules are also validated against the rule schema before being added to the engine.
 
 ## Error Handling
 
@@ -122,8 +340,14 @@ If `.xfi-config.json` is invalid:
 2. Default configuration used
 3. Analysis continues
 
+If individual custom rules are invalid:
+1. Warning message displayed
+2. Invalid rules are skipped
+3. Valid rules are still applied
+
 ## Next Steps
 
 - Configure [Local Rules](local-config)
 - Set up [Remote Configuration](remote-config)
 - Learn about [Exemptions](exemptions)
+- Explore [Creating Plugins](plugins/creating-plugins)