x-fidelity 1.4.1 → 1.5.1

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [1.5.1](https://github.com/zotoio/x-fidelity/compare/v1.5.0...v1.5.1) (2024-07-25)
+
+
+### Bug Fixes
+
+* **scope:** logging correlation ([ea1c497](https://github.com/zotoio/x-fidelity/commit/ea1c4977cac418c49cd9f6778e7f72458c2c2a61))
+
+# [1.5.0](https://github.com/zotoio/x-fidelity/compare/v1.4.1...v1.5.0) (2024-07-24)
+
+
+### Bug Fixes
+
+* **logger:** console transport ([69c62b1](https://github.com/zotoio/x-fidelity/commit/69c62b1b9859bc71801c576b969e9698ecc53a61))
+* **log:** remove console and add process exit codes ([3ec801f](https://github.com/zotoio/x-fidelity/commit/3ec801fe3f913452d1f6ef14723fd0f8cb3a8439))
+
+
+### Features
+
+* **telemetry:** basic start ([47faf3b](https://github.com/zotoio/x-fidelity/commit/47faf3b5f7a88afc07be1b256a611ce46ef64872))
+* **telemetry:** basics including tracing ([f07f6b4](https://github.com/zotoio/x-fidelity/commit/f07f6b4d7ad886008cd20d3ccfa80e0e980bfd34))
+* **telemetry:** request ids ([e19489e](https://github.com/zotoio/x-fidelity/commit/e19489eadd08b06119244a8e1798c2f22bac898b))
+
 ## [1.4.1](https://github.com/zotoio/x-fidelity/compare/v1.4.0...v1.4.1) (2024-07-14)
 
 

package/README.md

@@ -1,6 +1,24 @@
 # x-fidelity
 
-CLI for opinionated framework adherence checks
+x-fidelity is an advanced CLI tool designed to enforce opinionated framework adherence checks within a codebase. It provides a flexible and extensible way to ensure your projects follow specific standards and best practices.
+
+## Quick Start
+
+1. Install x-fidelity:
+   ```
+   yarn global add x-fidelity
+   export PATH="$PATH:$(yarn global bin)"
+   ```
+
+2. Run in your project directory:
+   ```
+   xfidelity
+   ```
+
+3. For more options:
+   ```
+   xfidelity --help
+   ```
 
 ```
 =====================================
@@ -16,107 +34,131 @@ CLI for opinionated framework adherence checks
 -------------------------------------
 ```
 
-## What is x-fidelity?
+## Table of Contents
+
+1. [Intent and Purpose](#intent-and-purpose)
+2. [Key Features](#key-features)
+3. [Installation](#installation)
+4. [Usage](#usage)
+5. [Configuration](#configuration)
+6. [Extending x-fidelity](#extending-x-fidelity)
+7. [OpenAI Integration](#openai-integration)
+8. [Hosting Config Servers](#hosting-config-servers)
+9. [Best Practices](#best-practices)
+10. [Contributing](#contributing)
+11. [License](#license)
 
-x-fidelity is a CLI tool designed to enforce adherence to a set of opinionated framework rules within a codebase. It checks for various conditions such as directory structure, dependency versions, and the presence of certain strings in files.
+## Intent and Purpose
 
-## Features
+x-fidelity aims to streamline the process of maintaining code quality and consistency across projects. By providing a flexible, rule-based system, it allows teams to:
 
-- Ensures the directory structure matches a predefined standard.
-- 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.
+- Enforce coding standards and best practices
+- Ensure consistent project structures
+- Maintain up-to-date dependencies
+- Catch potential issues early in the development process
+- Integrate advanced code analysis using AI (via OpenAI)
+
+The tool is designed to be highly customizable, allowing teams to define their own archetypes, rules, and checks tailored to their specific needs and tech stacks.
+
+## Key Features
+
+- **Flexible Archetype System**: Define custom project archetypes with specific rules and configurations.
+- **Customizable Rules**: Create and apply rules for various aspects of your codebase.
+- **Directory Structure Validation**: Ensure your project follows a predefined directory structure.
+- **Dependency Version Checking**: Verify that your project uses up-to-date dependencies.
+- **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.
 
 ## Installation
 
-Install x-fidelity with Node.js 18+ and Yarn:
+Install x-fidelity using Node.js 18+ and Yarn:
 
 ```sh
 yarn global add x-fidelity
 export PATH="$PATH:$(yarn global bin)"
 ```
 
-You may want to add the path line to your `~/.bashrc` or `~/.zshrc` file for persistence of the binary in your path.
+For persistent access, add the PATH line to your `~/.bashrc` or `~/.zshrc` file.
 
 ## Usage
 
-### CLI
+### Basic Usage
 
-To run x-fidelity, use the following command:
+Run x-fidelity in your project directory:
 
 ```sh
 xfidelity
-
-# 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>]
 ```
 
-- `-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)
+### Advanced Usage
 
-**Example for node-fullstack archetype in current dir with remove config server:**
+Use command-line options for more control:
 
 ```sh
-xfidelity --configUrl https://localhost:8888
+xfidelity [-d --dir <directory>] [-c --configServer <url>] [-a --archetype <archetype>] [-m --mode <mode>] [-p --port <port>] 
 ```
 
-**Example for java-microservice archetype in parent dir with remote config server (in this example running locally on port 8888):**
+- `-d --dir <directory>`: Specify the root directory to analyze (default: current directory)
+- `-c --configServer <url>`: URL to fetch the configuration from
+- `-a --archetype <archetype>`: Archetype to use for analysis (default: 'node-fullstack')
+- `-m --mode <mode>`: Run mode: 'cli' or 'server' (default: 'cli')
+- `-p --port <port>`: Port number for server mode (default: 8888)
+
+Examples:
 
 ```sh
-xfidelity -d .. -a java-microservice --c https://localhost:8888
-```
+# Use remote config server
+xfidelity --configServer https://localhost:8888
 
-### Configuration Server
+# Analyze parent directory with java-microservice archetype
+xfidelity -d .. -a java-microservice -c https://localhost:8888
 
-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. 
+# Run in server mode with custom port
+xfidelity --mode server --port 9999
 
-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.
+```
 
-**To start the server:**
+### Configuration Server
 
-1. Navigate to the x-fidelity directory.
-2. Run the following command:
+Start the built-in configuration server:
 
 ```sh
-yarn start-config-server
+yarn start-server
 ```
 
-> **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.
+Or use the CLI:
+
 ```sh
-export XFI_SERVER_PORT=8888
+xfidelity --mode server
 ```
 
-## OpenAI Integration
-
-To enable OpenAI features for experimental LLM-based codebase analysis:
-
-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:
+Set a custom port:
 
 ```sh
-export OPENAI_API_KEY=your_openai_api_key
+xfidelity --mode server --port 9999
 ```
-4. Optionally set the OPENAI_MODEL environment var (default is gpt-4o):
+
+You can also set the port using an environment variable:
+
 ```sh
-export OPENAI_MODEL=gpt-4
+export XFI_SERVER_PORT=8888
+xfidelity --mode server
 ```
-Note that not all models consistently return parseable JSON results, so some experimentation is required.
-
-> [!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.
 
 ## Configuration
 
-The configuration for x-fidelity is based on archetypes, which define the rules, operators, facts, and other settings for a specific type of project. You can find example configuration files in the `src/archetypes` directory of the repository.
+x-fidelity uses archetypes to define project-specific configurations. Archetypes specify:
 
-### Archetype Schema
+- Rules to apply
+- Operators to use
+- Facts to gather
+- Dependency version requirements
+- Standard directory structure
+- File patterns to include or exclude
 
-An archetype is defined with the following structure:
+Example archetype structure:
 
 ```typescript
 interface ArchetypeConfig {
@@ -132,54 +174,19 @@ interface ArchetypeConfig {
 }
 ```
 
-- `rules`: An array of rule names to be applied for this archetype.
-- `operators`: An array of operator names used in the rules.
-- `facts`: An array of fact provider names used to gather information about the codebase.
-- `config`: Additional configuration specific to the archetype:
-  - `minimumDependencyVersions`: Minimum required versions for dependencies.
-  - `standardStructure`: Expected directory structure for the project.
-  - `blacklistPatterns`: Patterns for files/directories to be ignored.
-  - `whitelistPatterns`: Patterns for files/directories to be included.
-
-### Rule Structure
-
-Each rule is defined in a JSON file with the following structure:
-
-```json
-{
-  "name": "ruleName",
-  "conditions": {
-    "all": [
-      {
-        "fact": "factName",
-        "operator": "operatorName",
-        "value": "expectedValue"
-      }
-    ]
-  },
-  "event": {
-    "type": "violation",
-    "params": {
-      "message": "Error message when the rule fails"
-    }
-  }
-}
-```
+## Extending x-fidelity
 
-## Creating New Archetypes
-
-To create a new archetype:
+x-fidelity is designed to be highly extensible:
 
-1. Create a new file in the `src/archetypes` directory, e.g., `myNewArchetype.ts`.
-2. Define the archetype configuration following the `ArchetypeConfig` interface.
-3. Add any necessary rules in the `src/rules` directory.
-4. If needed, create custom operators in the `src/operators` directory.
-5. If needed, create custom fact providers in the `src/facts` directory.
-6. Update the `src/archetypes/index.ts` file to include your new archetype.
+1. **Custom Rules**: Add new JSON rule files in `src/rules`.
+2. **Custom Operators**: Implement new operators in `src/operators` and add them to `src/operators/index.ts`.
+3. **Custom Facts**: Create new fact providers in `src/facts` and add them to `src/facts/index.ts`.
+4. **New Archetypes**: Define new archetypes in `src/archetypes` and include them in `src/archetypes/index.ts`.
 
-Example of a new archetype:
+Example of creating a new archetype:
 
 ```typescript
+// src/archetypes/myNewArchetype.ts
 export const myNewArchetype: ArchetypeConfig = {
     rules: ['myCustomRule', 'standardRule1', 'standardRule2'],
     operators: ['myCustomOperator', 'standardOperator1'],
@@ -201,41 +208,43 @@ export const myNewArchetype: ArchetypeConfig = {
 };
 ```
 
-## Extensibility
+## OpenAI Integration
 
-x-fidelity is designed to be highly extensible:
+To enable AI-powered code analysis:
+
+1. Sign up for an [OpenAI API key](https://platform.openai.com).
+2. Set environment variables:
+
+```sh
+export OPENAI_API_KEY=your_openai_api_key
+export OPENAI_MODEL=gpt-4  # Optional, default is gpt-4o
+```
 
-1. **Custom Rules**: Create new rules by adding JSON files in the `src/rules` directory.
-2. **Custom Operators**: Implement new operators in the `src/operators` directory and add them to `src/operators/index.ts`.
-3. **Custom Facts**: Create new fact providers in the `src/facts` directory and add them to `src/facts/index.ts`.
-4. **New Archetypes**: As described above, create new archetypes to support different project types or frameworks.
+> [!IMPORTANT]
+> Be aware of potential costs and data privacy concerns when using OpenAI's API.
 
 ## Hosting Config Servers
 
 To host a config server for x-fidelity:
 
-1. Set up a Node.js server environment (e.g., using Express.js).
-2. Implement endpoints that serve the archetype configurations and rules.
-3. Ensure the server is secure and can handle the expected load.
-4. Use HTTPS for secure communication.
-5. Implement caching mechanisms to improve performance.
-6. Consider using a CDN for global distribution and lower latency.
+1. Set up a Node.js server (e.g., Express.js)
+2. Implement endpoints for archetype configurations and rules
+3. Ensure security, scalability, and performance
+4. Use HTTPS and implement proper authentication
+5. Consider using a CDN for global distribution
 
-Example server setup (simplified):
+Example server setup:
 
 ```javascript
 const express = require('express');
 const app = express();
 
 app.get('/archetypes/:archetype', (req, res) => {
-    const archetype = req.params.archetype;
-    // Fetch and return the archetype configuration
+    // Fetch and return archetype configuration
 });
 
 app.get('/archetypes/:archetype/rules/:rule', (req, res) => {
-    const archetype = req.params.archetype;
-    const rule = req.params.rule;
-    // Fetch and return the specific rule for the archetype
+    // Fetch and return specific rule
 });
 
 app.listen(8888, () => {
@@ -243,15 +252,20 @@ app.listen(8888, () => {
 });
 ```
 
-Best practices for hosting:
+## Best Practices
+
+1. **Version Control**: Keep your x-fidelity configurations in version control.
+2. **Continuous Integration**: Integrate x-fidelity checks into your CI/CD pipeline.
+3. **Regular Updates**: Keep your archetypes, rules, and dependencies up to date.
+4. **Documentation**: Document custom rules, operators, and archetypes for your team.
+5. **Gradual Implementation**: When introducing x-fidelity to an existing project, start with basic checks and gradually increase strictness.
+6. **Team Alignment**: Ensure your team understands and agrees on the rules being enforced.
+7. **Performance**: Be mindful of the performance impact, especially for large codebases.
+
+## Contributing
 
-- Use environment variables for sensitive information.
-- Implement proper error handling and logging.
-- Set up monitoring and alerting for the server.
-- Regularly update and maintain the server and its dependencies.
-- Implement rate limiting to prevent abuse.
-- Consider using containerization (e.g., Docker) for easy deployment and scaling.
+Contributions to x-fidelity are welcome! Please refer to the `CONTRIBUTING.md` file for guidelines on how to contribute to this project.
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License. See the `LICENSE` file for details.

package/dist/archetypes/index.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.archetypes = void 0;
 exports.archetypes = {
     'node-fullstack': {
-        rules: ['sensitiveLogging', 'outdatedFramework', 'noDatabases', 'nonStandardDirectoryStructure', 'openaiAnalysisTop5', 'openaiAnalysisA11y'],
+        rules: ['sensitiveLogging-iterative', 'outdatedFramework-global', 'noDatabases-iterative', 'nonStandardDirectoryStructure-global', 'openaiAnalysisTop5-global', 'openaiAnalysisA11y-global', 'yarnLockfileCheck-global'],
         operators: ['fileContains', 'outdatedFramework', 'nonStandardDirectoryStructure', 'openaiAnalysisHighSeverity'],
         facts: ['repoFilesystemFacts', 'repoDependencyFacts', 'openaiAnalysisFacts'],
         config: {
@@ -14,7 +14,6 @@ exports.archetypes = {
             standardStructure: {
                 app: {
                     frontend: null,
-                    common: null,
                     server: null
                 }
             },
@@ -29,7 +28,7 @@ exports.archetypes = {
         }
     },
     'java-microservice': {
-        rules: ['sensitiveLogging', 'outdatedFramework', 'noDatabases', 'nonStandardDirectoryStructure'],
+        rules: ['sensitiveLogging-iterative', 'outdatedFramework-global', 'noDatabases-iterative', 'nonStandardDirectoryStructure-global'],
         operators: ['fileContains', 'outdatedFramework', 'nonStandardDirectoryStructure'],
         facts: ['repoFilesystemFacts', 'repoDependencyFacts'],
         config: {

package/dist/core/cli.js

@@ -3,6 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.options = void 0;
 const logger_1 = require("../utils/logger");
 const commander_1 = require("commander");
+// Ensure logger is initialized
+if (!logger_1.logger || typeof logger_1.logger.info !== 'function') {
+    console.error('Logger is not properly initialized');
+    process.exit(1);
+}
+commander_1.program
+    .option("-d, --dir <directory>", "The checkout directory to analyze (default: current directory)", ".")
+    .option("-a, --archetype <archetype>", "The archetype to use for analysis (default: node-fullstack)", "node-fullstack")
+    .option("-c, --configServer <configServer>", "The config server URL for fetching remote archetype configurations and rules")
+    .option("-m, --mode <mode>", "Run mode: 'cli' or 'server' (default: cli)", "cli")
+    .option("-p, --port <port>", "Port number for server mode (default: 8888)", "8888")
+    .option("-l, --local-config <path>", "Path to local archetype config and rules");
+commander_1.program.parse();
+const options = commander_1.program.opts();
+exports.options = options;
 const banner = (`
 =====================================
  __    __          ________  ______ 
@@ -14,26 +29,17 @@ const banner = (`
 | ##  | ##        | ##      |   ## \\
  \\##   \\##         \\##       \\######
                                
--------------------------------------
-${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("-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;
+--------------------
+${new Date().toString().slice(0, 24)}
+archetype: ${options.archetype}
+directory: ${process.env.PWD}/${options.dir}
+configServer: ${options.configServer ? options.configServer : 'none'}
+mode: ${options.mode}
+port: ${options.mode === 'server' ? options.port : 'N/A'}
+local-config: ${options.localConfig ? options.localConfig : 'none'}
+for available options run: xfidelity --help
+=====================================`);
+logger_1.logger.info(banner);
 // print help if no arguments are passed
 if (commander_1.program.options.length === 0)
     commander_1.program.help();
-if (!options.dir) {
-    console.error("Checkout directory not provided. Defaulting to current directory.");
-}
-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);