x-fidelity 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+# [1.4.0](https://github.com/zotoio/x-fidelity/compare/v1.3.0...v1.4.0) (2024-07-14)
+
+
+### Features
+
+* **rule:** report specific dependency issues ([2ccaf6c](https://github.com/zotoio/x-fidelity/commit/2ccaf6cfe9d6cf8a73de5413fffee40dbb0f236d))
+
+# [1.3.0](https://github.com/zotoio/x-fidelity/compare/v1.2.0...v1.3.0) (2024-07-11)
+
+
+### Bug Fixes
+
+* **ai:** fix ([8f94cee](https://github.com/zotoio/x-fidelity/commit/8f94cee6ef990a39db3bc4c61f16b3c56bdb10dd))
+* **ai:** fix ([f5ba9f5](https://github.com/zotoio/x-fidelity/commit/f5ba9f5319e02788f3c6a1f0b70b1fa2638e719d))
+* Initialized OpenAI client before using it to prevent "Cannot read properties of undefined (reading 'chat')" error ([a112b43](https://github.com/zotoio/x-fidelity/commit/a112b4372ff7eef5c00cb4c3fede13eeb932b2a2))
+* **refactor:** logic issues and async issue ([2ad8cdd](https://github.com/zotoio/x-fidelity/commit/2ad8cdd7becbd80217dd0115be266cdf753a8470))
+* **sec:** prevent error reflection ([93eca93](https://github.com/zotoio/x-fidelity/commit/93eca93e4737f01977f27dacf8cabbd5adf1ab2b))
+* **sec:** santize input ([6f78c39](https://github.com/zotoio/x-fidelity/commit/6f78c396a6d83189d3985a0c826f5967e1e6eee4))
+* **server:** fix ai error ([20341fa](https://github.com/zotoio/x-fidelity/commit/20341fa0df7a34791f2a4f34a89ee1cf7e5014ef))
+
+
+### Features
+
+* **server:** remote config server ([f027ed2](https://github.com/zotoio/x-fidelity/commit/f027ed200d94e0bc16c000a8a677da819a8695cf))
+
 # [1.2.0](https://github.com/zotoio/x-fidelity/compare/v1.1.0...v1.2.0) (2024-07-10)
 
 

package/README.md

@@ -26,287 +26,115 @@ x-fidelity is a CLI tool designed to enforce adherence to a set of opinionated f
 - Verifies that dependencies are up-to-date according to a specified minimum version.
 - Checks for the presence or absence of specific strings in files.
 - Configurable via a remote JSON configuration file.
+- Integrates with OpenAI for advanced code analysis.
 
 ## Installation
 
-Install x-fidelity with node 20+ and yarn:
+Install x-fidelity with Node.js 18+ and Yarn:
 
 ```sh
-corepack enable
 yarn global add x-fidelity
 export PATH="$PATH:$(yarn global bin)"
 ```
 
-You may want to add that path line to ~/.bashrc
+You may want to add the path line to your `~/.bashrc` or `~/.zshrc` file for persistence of the binary in your path.
 
 ## Usage
 
+### CLI
+
 To run x-fidelity, use the following command:
 
 ```sh
-xfidelity --dir <directory> [--configUrl <url>]
-```
-
-- `--dir <directory>`: The directory of the repository to analyze.
-- `--configUrl <url>`: (Optional) The URL to fetch the configuration from.
-
-Example:
+xfidelity
 
-```sh
-xfidelity --dir ./my-repo --configUrl https://example.com/config.json
+# you can use the following options for more advanced setups such as the remote config server
+xfidelity [-d --dir <directory>] [-c --configUrl <url>] [-a --archtype <archetype>]
 ```
 
-## Configuration
+- `-d --dir <directory>`: (Optional) The root directory of the local repo dir to analyze.  Default is current dir.
+- `-c --configUrl <url>`: (Optional) The URL to fetch the configuration from.
+- `-a --archetype <archetype>`: (Optional) The archetype to use for analysis. 'node-fullstack' is the default, or 'java-microservice' and these are extensible)
 
-The configuration file should be a JSON file containing the following structure:
+**Example for node-fullstack archetype in current dir with remove config server:**
 
-```json
-{
-  "minimumDependencyVersions": {
-    "commander": "^2.0.0",
-    "nodemon": "^3.9.0"
-  },
-  "standardStructure": {
-    "src": {
-      "core": null,
-      "utils": null,
-      "operators": null,
-      "rules": null,
-      "facts": null
-    }
-  }
-}
+```sh
+xfidelity --configUrl https://localhost:8888
 ```
 
-## OpenAI Integration
-
-x-fidelity can integrate with OpenAI to provide advanced code analysis. To enable OpenAI features, you need to set the `OPENAI_API_KEY` environment variable with your OpenAI API key.
-
-### Getting an OpenAI API Key
-
-1. Sign up for an account at [OpenAI](https://www.openai.com/).
-2. Navigate to the API section and generate a new API key.
-3. Set the `OPENAI_API_KEY` environment variable in your terminal or CI/CD pipeline.
+**Example for java-microservice archetype in parent dir with remote config server (in this example running locally on port 8888):**
 
 ```sh
-export OPENAI_API_KEY=your_openai_api_key
+xfidelity -d .. -a java-microservice --c https://localhost:8888
 ```
 
-### Disclaimer
+### Configuration Server
 
-Using OpenAI's API may incur costs. Please refer to OpenAI's pricing page for more details.
+x-fidelity includes an optional configuration server that can be used to serve configuration  per archetype.  This includes config for fact provders and custom operators, and also the rule json to use per archetype. 
 
-## Rules
+This is of most use when you need to be able to globally rollout config updates for minor/patch releases without relying cli users run to upgrade x-fidelity.
 
-### Sensitive Logging
+**To start the server:**
 
-This rule checks for the presence of sensitive data in the logs.
+1. Navigate to the x-fidelity directory.
+2. Run the following command:
 
-```json
-{
-  "name": "sensitiveLogging",
-  "conditions": {
-    "any": [
-      {
-        "fact": "fileData",
-        "path": "$.fileContent",
-        "operator": "fileContains",
-        "value": "token"
-      },
-      {
-        "fact": "fileData",
-        "path": "$.fileContent",
-        "operator": "fileContains",
-        "value": "secret"
-      },
-      {
-        "fact": "fileData",
-        "path": "$.fileContent",
-        "operator": "fileContains",
-        "value": "todo: expand with regex operator for more sensitive data patterns"
-      }
-    ]
-  },
-  "event": {
-    "type": "violation",
-    "params": {
-      "message": "Sensitive data must not be logged."
-    }
-  }
-}
+```sh
+yarn start-config-server
 ```
 
-### Outdated Framework
-
-This rule checks if any core framework dependencies are outdated.
-
-```json
-{
-  "name": "outdatedFramework",
-  "conditions": {
-    "all": [
-      {
-        "fact": "fileData",
-        "path": "$.fileName",
-        "operator": "outdatedFramework",
-        "value": {
-          "fact": "dependencyData"
-        }
-      }    
-    ]
-  },
-  "event": {
-    "type": "violation",
-    "params": {
-      "message": "Some core framework dependencies have expired!",
-      "filePath": {
-        "fact": "fileData",
-        "path": "$.filePath"
-      },
-      "minimumDependencyVersions": {
-        "fact": "dependencyData",
-        "path": "$.minimumDependencyVersions"
-      }
-    }
-  }
-}
+> **By default, the server will start on port 8888**. You can override this using the `XFI_SERVER_PORT` environment variable You can then use the server URL as the `--configUrl` parameter when running the CLI.
+```sh
+export XFI_SERVER_PORT=8888
 ```
 
-### No Databases
-
-This rule ensures that code does not directly call databases.
-
-```json
-{
-  "name": "noDatabases",
-  "conditions": {
-    "any": [
-      {
-        "fact": "fileData",
-        "path": "$.fileContent",
-        "operator": "fileContains",
-        "value": "oracle"
-      }
-    ]
-  },
-  "event": {
-    "type": "violation",
-    "params": {
-      "message": "Code must not directly call databases."
-    }
-  }
-}
-```
+## OpenAI Integration
 
-### Non-Standard Directory Structure
+To enable OpenAI features for experimental LLM-based codebase analysis:
 
-This rule checks if the directory structure matches the standard structure.
+1. Sign up for a developer account at [OpenAI](https://platform.openai.com).
+2. Navigate to the API section and generate a new API key.
+3. Set the `OPENAI_API_KEY` environment variable:
 
-```json
-{
-  "name": "nonStandardDirectoryStructure",
-  "conditions": {
-    "all": [
-      {
-        "fact": "fileData",
-        "path": "$.fileName",
-        "operator": "equal",
-        "value": "REPO_GLOBAL_CHECK"
-      },
-      {
-        "fact": "fileData",
-        "path": "$.filePath",
-        "operator": "nonStandardDirectoryStructure",
-        "value": {
-          "fact": "standardStructure"
-        }
-      }
-    ]
-  },
-  "event": {
-    "type": "violation",
-    "params": {
-      "message": "Directory structure does not match the standard.",
-      "details": {
-        "fact": "fileData",
-        "path": "$.filePath"
-      }
-    }
-  }
-}
+```sh
+export OPENAI_API_KEY=your_openai_api_key
+```
+4. Optionally set the OPENAI_MODEL environment var (default is gpt-4o):
+```sh
+export OPENAI_MODEL=gpt-4
 ```
+Note that not all models consistently return parseable JSON results, so some experimentation is required.
 
-### OpenAI Analysis
+> [!IMPORTANT]
+> Using OpenAI's API may incur costs. Please refer to OpenAI's pricing page for more details.
+> 
+>The 'collectOpenaiAnalysisFacts' function will concatenate all files that are not blacklisted but are included in the whitelist and send this to OpenAI.  Ensure you consider any sensitive data that may be sent, and the cost based on the token count this will be per rule check that is executed.
 
-This rule uses OpenAI to analyze the codebase for various issues.
+## Configuration
 
-#### Top 5 Issues
+The configuration file should be a JSON file containing rules, operators, facts, and other settings. You can find example configuration files in the `src/rules` directory of the repository.
 
-```json
-{
-  "name": "openaiAnalysisTop5Rule",
-  "conditions": {
-    "all": [
-      {
-        "fact": "fileData",
-        "path": "$.fileName",
-        "operator": "equal",
-        "value": "REPO_GLOBAL_CHECK"
-      },
-      {
-        "fact": "openaiAnalysis",
-        "params": {
-          "prompt": "What are the most important 5 things to fix?",
-          "resultFact": "openaiAnalysisTop5"
-        },
-        "operator": "openaiAnalysisHighSeverity",
-        "value": 8
-      }
-    ]
-  },
-  "event": {
-    "type": "violation",
-    "params": {
-      "message": "OpenAI analysis failed for the provided prompt.",
-      "results": {
-        "fact": "openaiAnalysisTop5"
-      }
-    }
-  }
-}
-```
+### Rule Structure
 
-#### Accessibility Issues
+Each rule is defined in a JSON file with the following structure:
 
 ```json
 {
-  "name": "openaiAnalysisA11yRule",
+  "name": "ruleName",
+  "description": "A brief description of the rule",
   "conditions": {
     "all": [
       {
-        "fact": "fileData",
-        "path": "$.fileName",
-        "operator": "equal",
-        "value": "REPO_GLOBAL_CHECK"
-      },
-      {
-        "fact": "openaiAnalysis",
-        "params": {
-          "prompt": "Identify any accessibility (a11y) issues in the codebase.",
-          "resultFact": "openaiAnalysisA11y"
-        },
-        "operator": "openaiAnalysisHighSeverity",
-        "value": 8
+        "fact": "factName",
+        "operator": "operatorName",
+        "value": "expectedValue"
       }
     ]
   },
   "event": {
-    "type": "violation",
+    "type": "ruleFailure",
     "params": {
-      "message": "OpenAI analysis detected accessibility (a11y) issues in the codebase.",
-      "results": {
-        "fact": "openaiAnalysisA11y"
-      }
+      "message": "Error message when the rule fails"
     }
   }
 }

package/dist/archetypes/index.js

@@ -12,22 +12,19 @@ exports.archetypes = {
                 nodemon: '^3.9.0'
             },
             standardStructure: {
-                src: {
-                    core: null,
-                    utils: null,
-                    operators: null,
-                    rules: null,
-                    facts: null
+                app: {
+                    frontend: null,
+                    common: null,
+                    server: null
                 }
             },
             blacklistPatterns: [
-                /.*\/\..*/, // dot files
-                /.*\.(log|lock)$/, // file extensions blacklisted
-                /.*\/(dist|coverage|build|node_modules)(\/.*|$)/ // directory names blacklisted
+                '.*\\/\\..*', // dot files
+                '.*\\.(log|lock)$', // file extensions blacklisted
+                '.*\\/(dist|coverage|build|node_modules)(\\/.*|$)' // directory names blacklisted
             ],
             whitelistPatterns: [
-                /.*\.(ts|tsx|js|jsx|md)$/,
-                /.*\/(package|tsconfig)\.json$/
+                '.*\\.(ts|tsx|js|jsx|md)$' // file extensions whitelisted
             ]
         }
     },
@@ -53,13 +50,13 @@ exports.archetypes = {
                 }
             },
             blacklistPatterns: [
-                /.*\/\..*/, // dot files
-                /.*\.(log|lock)$/, // file extensions blacklisted
-                /.*\/(target|build|out)(\/.*|$)/ // directory names blacklisted
+                '.*\\/\\..*', // dot files
+                '.*\\.(log|lock)$', // file extensions blacklisted
+                '.*\\/(target|build|out|dist|coverage|build|node_modules)(\\/.*|$)' // directory names blacklisted
             ],
             whitelistPatterns: [
-                /.*\.(java|xml|properties|yml)$/,
-                /.*\/pom\.xml$/
+                '.*\\.(java|xml|properties|yml)$',
+                '.*\\/pom\\.xml$'
             ]
         }
     }

package/dist/core/cli.js

@@ -19,8 +19,9 @@ ${new Date().toString()}`);
 console.log(banner);
 logger_1.logger.info([banner]);
 commander_1.program
-    .option("-d, --dir <directory>", "The checkout directory to analyse")
-    .option("-a, --archetype <archetype>", "The archetype to use for analysis", "node-fullstack");
+    .option("-d, --dir <directory>", "The checkout directory to analyse", ".")
+    .option("-a, --archetype <archetype>", "The archetype to use for analysis", "node-fullstack")
+    .option("-c, --configServer <configServer>", "The config server URL for fetching remote archetype configurations and rules");
 commander_1.program.parse();
 const options = commander_1.program.opts();
 exports.options = options;
@@ -30,7 +31,9 @@ if (commander_1.program.options.length === 0)
 if (!options.dir) {
     console.error("Checkout directory not provided. Defaulting to current directory.");
 }
-console.log(`Archetype ${options.archetype}: analysis of: ${process.env.PWD}/${options.dir}`);
-logger_1.logger.info(`Archetype ${options.archetype}: analysis of: ${process.env.PWD}/${options.dir}`);
-console.log('=====================================');
-logger_1.logger.info('=====================================');
+let msg = `Archetype ${options.archetype}: analysis of: ${process.env.PWD}/${options.dir}`;
+logger_1.logger.info(msg) && console.log(msg);
+msg = `configServer: ${options.configServer ? options.configServer : 'local'}`;
+logger_1.logger.info(msg) && console.log(msg);
+msg = '=====================================';
+logger_1.logger.info(msg) && console.log(msg);

package/dist/core/engine.js

@@ -8,9 +8,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.analyzeCodebase = analyzeCodebase;
 const logger_1 = require("../utils/logger");
@@ -18,29 +15,28 @@ const json_rules_engine_1 = require("json-rules-engine");
 const repoFilesystemFacts_1 = require("../facts/repoFilesystemFacts");
 const repoDependencyFacts_1 = require("../facts/repoDependencyFacts");
 const openaiAnalysisFacts_1 = require("../facts/openaiAnalysisFacts");
-const axios_1 = __importDefault(require("axios"));
-const archetypes_1 = require("../archetypes");
-const rules_1 = require("../rules");
 const operators_1 = require("../operators");
 const facts_1 = require("../facts");
+const rules_1 = require("../rules");
+const config_1 = require("../utils/config");
 function analyzeCodebase(repoPath_1) {
-    return __awaiter(this, arguments, void 0, function* (repoPath, archetype = 'node-fullstack') {
-        let archetypeConfig = archetypes_1.archetypes[archetype] || archetypes_1.archetypes['node-fullstack'];
-        if (archetypeConfig.configUrl) {
-            try {
-                const response = yield axios_1.default.get(archetypeConfig.configUrl);
-                archetypeConfig = Object.assign(Object.assign({}, archetypeConfig), { config: Object.assign(Object.assign({}, archetypeConfig.config), response.data) });
-            }
-            catch (error) {
-                logger_1.logger.error(`Error fetching remote config: ${error}`);
-            }
-        }
+    return __awaiter(this, arguments, void 0, function* (repoPath, archetype = 'node-fullstack', configServer = '') {
+        const configManager = config_1.ConfigManager.getInstance();
+        yield configManager.initialize(archetype, configServer);
+        const archetypeConfig = configManager.getConfig();
         const installedDependencyVersions = yield (0, repoDependencyFacts_1.getDependencyVersionFacts)(archetypeConfig);
         const fileData = yield (0, repoFilesystemFacts_1.collectRepoFileData)(repoPath, archetypeConfig);
+        // add REPO_GLOBAL_CHECK to fileData, which is the trigger for global checks
+        fileData.push({
+            fileName: config_1.REPO_GLOBAL_CHECK,
+            filePath: config_1.REPO_GLOBAL_CHECK,
+            fileContent: config_1.REPO_GLOBAL_CHECK
+        });
         const { minimumDependencyVersions, standardStructure } = archetypeConfig.config;
         const openaiSystemPrompt = yield (0, openaiAnalysisFacts_1.collectOpenaiAnalysisFacts)(fileData);
         const engine = new json_rules_engine_1.Engine([], { replaceFactsInEventParams: true, allowUndefinedFacts: true });
         // Add operators to engine
+        console.log(`### loading custom operators..`);
         const operators = yield (0, operators_1.loadOperators)(archetypeConfig.operators);
         operators.forEach((operator) => {
             var _a, _b;
@@ -50,39 +46,54 @@ function analyzeCodebase(repoPath_1) {
             }
         });
         // Add rules to engine
-        const rules = yield (0, rules_1.loadRules)(archetypeConfig.rules);
+        console.log(`### loading json rules..`);
+        const rules = yield (0, rules_1.loadRules)(archetype, archetypeConfig.rules, configManager.configServer);
+        logger_1.logger.debug(rules);
         rules.forEach((rule) => {
-            var _a, _b;
             try {
-                if (!((_a = rule === null || rule === void 0 ? void 0 : rule.name) === null || _a === void 0 ? void 0 : _a.includes('openai')) || (process.env.OPENAI_API_KEY && ((_b = rule === null || rule === void 0 ? void 0 : rule.name) === null || _b === void 0 ? void 0 : _b.includes('openai')))) {
-                    console.log(`adding rule: ${rule === null || rule === void 0 ? void 0 : rule.name}`);
-                    engine.addRule(rule);
-                }
+                console.log(`adding rule: ${rule === null || rule === void 0 ? void 0 : rule.name}`);
+                engine.addRule(rule);
             }
             catch (e) {
                 console.error(`Error loading rule: ${rule === null || rule === void 0 ? void 0 : rule.name}`);
                 logger_1.logger.error(e.message);
             }
         });
-        engine.on('success', ({ type, params }) => {
+        engine.on('success', (_a, almanac_1) => __awaiter(this, [_a, almanac_1], void 0, function* ({ type, params }, almanac) {
             if (type === 'violation') {
-                //console.log(params);
+                //console.log(await almanac.factValue('dependencyData'));
+                console.log(`Rule violation: ${JSON.stringify(params)}}`);
             }
-        });
+        }));
         // Add facts to engine
+        console.log(`### loading facts..`);
         const facts = yield (0, facts_1.loadFacts)(archetypeConfig.facts);
         facts.forEach((fact) => {
-            engine.addFact(fact.name, fact.fn);
+            var _a, _b;
+            if (!((_a = fact === null || fact === void 0 ? void 0 : fact.name) === null || _a === void 0 ? void 0 : _a.includes('openai')) || (process.env.OPENAI_API_KEY && ((_b = fact === null || fact === void 0 ? void 0 : fact.name) === null || _b === void 0 ? void 0 : _b.includes('openai')))) {
+                console.log(`adding fact: ${fact.name}`);
+                engine.addFact(fact.name, fact.fn);
+            }
         });
         if (process.env.OPENAI_API_KEY && archetypeConfig.facts.includes('openaiAnalysisFacts')) {
-            console.log(`adding openai facts to engine..`);
+            console.log(`adding additional openai facts to engine..`);
             engine.addFact('openaiAnalysis', openaiAnalysisFacts_1.openaiAnalysis);
             engine.addFact('openaiSystemPrompt', openaiSystemPrompt);
         }
-        // Run the engine for each file's data                                                                             
+        // add output facts
+        engine.addFact('repoDependencyAnalysis', repoDependencyFacts_1.repoDependencyAnalysis);
+        // Run the engine for each file's data    
+        console.log(`### Executing rules..`);
         let failures = [];
         for (const file of fileData) {
-            logger_1.logger.info(`running engine for ${file.filePath}`);
+            if (file.fileName === 'REPO_GLOBAL_CHECK') {
+                let msg = `\n==========================\nSTARTING GLOBAL REPO CHECKS..\n==========================`;
+                logger_1.logger.info(msg) && console.log(msg);
+            }
+            else {
+                let msg = `running engine for ${file.filePath}`;
+                logger_1.logger.info(msg) && console.log(msg);
+            }
             const facts = {
                 fileData: file,
                 dependencyData: {
@@ -92,7 +103,6 @@ function analyzeCodebase(repoPath_1) {
                 standardStructure
             };
             let fileFailures = [];
-            console.log(`running engine for ${file.filePath} ..`);
             yield engine.run(facts)
                 .then(({ results }) => {
                 //console.log(events);