x-fidelity 3.0.4 → 3.1.1

package/.github/workflows/documentation.yml

@@ -0,0 +1,34 @@
+name: Documentation
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: yarn
+
+      - name: Install dependencies
+        run: |
+          cd website
+          yarn install --frozen-lockfile
+      
+      - name: Build website
+        run: |
+          cd website
+          yarn build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./website/build
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [3.1.1](https://github.com/zotoio/x-fidelity/compare/v3.1.0...v3.1.1) (2025-02-20)
+
+
+### Bug Fixes
+
+* add getting-started link to navbar with correct path ([48300a7](https://github.com/zotoio/x-fidelity/commit/48300a7e78f454fdc24d6d9013eff0bd22d9fc86))
+* docgen fix ([6e657fb](https://github.com/zotoio/x-fidelity/commit/6e657fbbb8b98013c1ce479c365ed7d205a88d57))
+* update broken documentation links and sidebar structure ([e8a83ae](https://github.com/zotoio/x-fidelity/commit/e8a83ae12ee17fa74533df254dcb6908c462c52b))
+* update navbar link to point to intro page instead of getting-started ([a0b997e](https://github.com/zotoio/x-fidelity/commit/a0b997ecce49d66a57860a9f081dd65d9bc91bfb))
+
+# [3.1.0](https://github.com/zotoio/x-fidelity/compare/v3.0.4...v3.1.0) (2025-02-20)
+
+
+### Bug Fixes
+
+* add missing typedoc dependency for documentation generation ([1152c4d](https://github.com/zotoio/x-fidelity/commit/1152c4d71829ea642dd68d671102433bc9e0ce03))
+* correct broken documentation links ([b48b474](https://github.com/zotoio/x-fidelity/commit/b48b47406fac82ac5f6f0775927b1b99cbdd5d5f))
+* correct broken documentation links in website files ([ed17172](https://github.com/zotoio/x-fidelity/commit/ed171720020e610e2c27b0a953adabcc43037511))
+* correct docId path in navbar configuration ([00985cc](https://github.com/zotoio/x-fidelity/commit/00985cc10cc42e0e016d4459ef3bf54931e10959))
+* **docs and minor fixes:** docusaurus site beta ([935dd1f](https://github.com/zotoio/x-fidelity/commit/935dd1f2a9125ef6c9e1bda86a6401a20e87d020))
+* handle null and undefined equality in customOperator ([9ed96e4](https://github.com/zotoio/x-fidelity/commit/9ed96e4ae46899943c9515e36622627f00aac32d))
+* update broken documentation links and references ([8de8ecc](https://github.com/zotoio/x-fidelity/commit/8de8ecc8aea5b5e5412a34daf72c281e5f9340b4))
+* update favicon path to use x-fi.png logo ([161c8f7](https://github.com/zotoio/x-fidelity/commit/161c8f786fd8139628f37165f96b7cff6b021db7))
+* update prism theme import syntax for compatibility ([e6b6380](https://github.com/zotoio/x-fidelity/commit/e6b638053d55272613f6f715d4c2e87dac535b62))
+* update relative paths in documentation links ([f3eca1f](https://github.com/zotoio/x-fidelity/commit/f3eca1fc1be53caeb5e506a4c8f42b372f81e1b2))
+* update TypeDoc plugin configuration and dependencies ([078a799](https://github.com/zotoio/x-fidelity/commit/078a799fe283666a4c6384199f8a1b2420621604))
+
+
+### Features
+
+* add homepage features component and styles ([8a7a601](https://github.com/zotoio/x-fidelity/commit/8a7a6017834c78f52079bd0f7d471047080c0f28))
+* add initial Docusaurus documentation setup ([3c553e1](https://github.com/zotoio/x-fidelity/commit/3c553e1f0b55601b5f1568bd707a621f509b9d41))
+* add initial Docusaurus website configuration files ([b6c8e02](https://github.com/zotoio/x-fidelity/commit/b6c8e02cac1465cb988f67e2bb2eba3e0cb04fb0))
+* add landing page with features overview and API reference link ([af8c760](https://github.com/zotoio/x-fidelity/commit/af8c760c7b04e454310cc3f43524c3987d3713b6))
+* add landing page with project description and API reference link ([08c6232](https://github.com/zotoio/x-fidelity/commit/08c6232a3a45448d9fe22aabb5f23764e81b53bd))
+* add Mermaid diagram support to documentation ([3894a43](https://github.com/zotoio/x-fidelity/commit/3894a438446d73d55b5d7efee2744d4452020f17))
+* enhance TypeDoc plugin configuration for complete API docs ([124b845](https://github.com/zotoio/x-fidelity/commit/124b84539dc31cb5c9a8ca9d12795434d98de8d2))
+* update logo display in navbar and homepage ([f880c1f](https://github.com/zotoio/x-fidelity/commit/f880c1fc3463221aa7670f110447a7391fd39a70))
+
 ## [3.0.4](https://github.com/zotoio/x-fidelity/compare/v3.0.3...v3.0.4) (2025-02-19)
 
 

package/README.md

@@ -436,6 +436,7 @@ Options:
   -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
+  -x, --examine                                  Validate archetype config only
   -v, --version                                  Output the version number of xfidelity
   -h, --help                                     Display help for command
 ```

package/dist/plugins/xfiPluginSimpleExample/facts/customFact.d.ts

@@ -1,2 +1,6 @@
 import { FactDefn } from '../../../types/typeDefs';
+/**
+ * Example custom fact that returns a simple data object
+ * Demonstrates basic fact implementation pattern
+ */
 export declare const customFact: FactDefn;

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

@@ -10,9 +10,21 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.customFact = void 0;
+const logger_1 = require("../../../utils/logger");
+/**
+ * Example custom fact that returns a simple data object
+ * Demonstrates basic fact implementation pattern
+ */
 exports.customFact = {
     name: 'customFact',
-    fn: () => __awaiter(void 0, void 0, void 0, function* () {
-        return { result: 'custom fact data' };
+    fn: (params) => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            logger_1.logger.debug('Executing customFact');
+            return { result: 'custom fact data' };
+        }
+        catch (error) {
+            logger_1.logger.error(`Error in customFact: ${error}`);
+            throw error;
+        }
     })
 };

package/dist/plugins/xfiPluginSimpleExample/operators/customOperator.d.ts

@@ -1,2 +1,6 @@
 import { OperatorDefn } from '../../../types/typeDefs';
+/**
+ * Example custom operator that performs simple equality comparison
+ * Demonstrates basic operator implementation pattern
+ */
 export declare const customOperator: OperatorDefn;

package/dist/plugins/xfiPluginSimpleExample/operators/customOperator.js

@@ -1,9 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.customOperator = void 0;
+const logger_1 = require("../../../utils/logger");
+/**
+ * Example custom operator that performs simple equality comparison
+ * Demonstrates basic operator implementation pattern
+ */
 exports.customOperator = {
     name: 'customOperator',
     fn: (factValue, expectedValue) => {
-        return factValue === expectedValue;
+        try {
+            logger_1.logger.debug('Executing customOperator', { factValue, expectedValue });
+            // Special case: if both values are null or both are undefined, they're equal
+            if ((factValue === null && expectedValue === null) ||
+                (factValue === undefined && expectedValue === undefined)) {
+                return true;
+            }
+            // If only one value is null/undefined but not both, they're not equal
+            if (factValue === undefined || factValue === null) {
+                logger_1.logger.warn('customOperator received undefined/null factValue');
+                return false;
+            }
+            return factValue === expectedValue;
+        }
+        catch (error) {
+            logger_1.logger.error(`Error in customOperator: ${error}`);
+            return false;
+        }
     }
 };

package/eslint.config.js

@@ -26,6 +26,6 @@ module.exports = [
     }
   },
   {
-    ignores: ["node_modules/", "dist/", "build/", "coverage/"],
+    ignores: ["node_modules/", "dist/", "build/", "coverage/", "website/"],
   }
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x-fidelity",
-  "version": "3.0.4",
+  "version": "3.1.1",
   "description": "cli for opinionated framework adherence checks",
   "main": "dist/index",
   "types": "dist/index.d.ts",

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

@@ -1,8 +1,19 @@
 import { FactDefn } from '../../../types/typeDefs';
+import { logger } from '../../../utils/logger';
 
+/**
+ * Example custom fact that returns a simple data object
+ * Demonstrates basic fact implementation pattern
+ */
 export const customFact: FactDefn = {
     name: 'customFact',
-    fn: async () => {
-        return { result: 'custom fact data' };
+    fn: async (params) => {
+        try {
+            logger.debug('Executing customFact');
+            return { result: 'custom fact data' };
+        } catch (error) {
+            logger.error(`Error in customFact: ${error}`);
+            throw error;
+        }
     }
 };

package/src/plugins/xfiPluginSimpleExample/operators/customOperator.ts

@@ -1,8 +1,32 @@
 import { OperatorDefn } from '../../../types/typeDefs';
+import { logger } from '../../../utils/logger';
 
+/**
+ * Example custom operator that performs simple equality comparison
+ * Demonstrates basic operator implementation pattern
+ */
 export const customOperator: OperatorDefn = {
     name: 'customOperator',
     fn: (factValue: any, expectedValue: any) => {
-        return factValue === expectedValue;
+        try {
+            logger.debug('Executing customOperator', { factValue, expectedValue });
+            
+            // Special case: if both values are null or both are undefined, they're equal
+            if ((factValue === null && expectedValue === null) || 
+                (factValue === undefined && expectedValue === undefined)) {
+                return true;
+            }
+
+            // If only one value is null/undefined but not both, they're not equal
+            if (factValue === undefined || factValue === null) {
+                logger.warn('customOperator received undefined/null factValue');
+                return false;
+            }
+
+            return factValue === expectedValue;
+        } catch (error) {
+            logger.error(`Error in customOperator: ${error}`);
+            return false;
+        }
     }
 };

package/website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

package/website/docs/archetypes.md

@@ -0,0 +1,150 @@
+---
+sidebar_position: 4
+---
+
+# Archetypes
+
+Archetypes are predefined configuration templates that define how x-fidelity should analyze different types of projects.
+
+## What is an Archetype?
+
+An archetype defines:
+- Rules to apply
+- Required directory structure
+- Minimum dependency versions
+- File patterns to analyze
+- Custom operators and facts to use
+
+## Archetype Structure
+
+```json
+{
+    "name": "node-fullstack",
+    "rules": [
+        "sensitiveLogging-iterative",
+        "outdatedFramework-global",
+        "noDatabases-iterative"
+    ],
+    "operators": [
+        "fileContains",
+        "outdatedFramework",
+        "nonStandardDirectoryStructure"
+    ],
+    "facts": [
+        "repoFilesystemFacts",
+        "repoDependencyFacts"
+    ],
+    "config": {
+        "minimumDependencyVersions": {
+            "react": ">=17.0.0",
+            "typescript": "^4.0.0"
+        },
+        "standardStructure": {
+            "src": {
+                "components": null,
+                "utils": null
+            }
+        },
+        "blacklistPatterns": [
+            ".*\\/\\..*",
+            ".*\\.(log|lock)$",
+            ".*\\/(dist|build|node_modules)(\\/.*|$)"
+        ],
+        "whitelistPatterns": [
+            ".*\\.(ts|tsx|js|jsx)$"
+        ]
+    }
+}
+```
+
+## Configuration Options
+
+### Rules
+
+The `rules` array lists all rules that should be applied to projects using this archetype. Rules can be:
+- **Global**: Applied once per repository (suffix `-global`)
+- **Iterative**: Applied to each matching file (suffix `-iterative`)
+
+### Operators
+
+The `operators` array defines which operators are available for use in rules. Common operators include:
+- `fileContains`: Check file contents for patterns
+- `outdatedFramework`: Check dependency versions
+- `nonStandardDirectoryStructure`: Validate directory structure
+
+### Facts
+
+The `facts` array specifies which fact providers to use. Built-in facts include:
+- `repoFilesystemFacts`: File system information
+- `repoDependencyFacts`: Dependency version data
+- `openaiAnalysisFacts`: AI-powered analysis results
+
+### Config Section
+
+#### minimumDependencyVersions
+
+Defines minimum required versions for dependencies using semver ranges:
+```json
+"minimumDependencyVersions": {
+    "react": ">=17.0.0",
+    "typescript": "^4.0.0"
+}
+```
+
+#### standardStructure
+
+Defines the expected directory structure:
+```json
+"standardStructure": {
+    "src": {
+        "components": null,
+        "utils": null
+    }
+}
+```
+- Use `null` for leaf directories
+- Nested objects for subdirectories
+
+#### blacklistPatterns
+
+Array of regex patterns for files to exclude:
+```json
+"blacklistPatterns": [
+    ".*\\/\\..*",  // Hidden files
+    ".*\\.(log|lock)$",  // Log and lock files
+    ".*\\/(dist|build|node_modules)(\\/.*|$)"  // Build directories
+]
+```
+
+#### whitelistPatterns
+
+Array of regex patterns for files to include:
+```json
+"whitelistPatterns": [
+    ".*\\.(ts|tsx|js|jsx)$"  // TypeScript and JavaScript files
+]
+```
+
+## Creating Custom Archetypes
+
+1. Create a new JSON file named `your-archetype.json`
+2. Define required sections: name, rules, operators, facts, and config
+3. Place in your local config directory or on your config server
+4. Use with the `-a` or `--archetype` option:
+```bash
+xfidelity . -a your-archetype
+```
+
+## Best Practices
+
+1. **Naming Convention**: Use descriptive names like `node-fullstack` or `java-microservice`
+2. **Rule Selection**: Include both global and iterative rules for comprehensive checks
+3. **Dependency Management**: Keep minimum versions up to date with security patches
+4. **File Patterns**: Be specific with whitelist/blacklist patterns
+5. **Directory Structure**: Define structures that match your organization's standards
+
+## Next Steps
+
+- Learn about [Rules](rules)
+- Explore [Operators](operators)
+- Understand [Facts](facts)

package/website/docs/ci-cd/github-actions.md

@@ -0,0 +1,156 @@
+---
+sidebar_position: 2
+---
+
+# GitHub Actions Integration
+
+This guide shows how to integrate x-fidelity into your GitHub Actions workflows.
+
+## Basic Workflow
+
+Create `.github/workflows/x-fidelity.yml`:
+
+```yaml
+name: x-fidelity
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Setup Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: '18'
+        cache: 'yarn'
+    
+    - name: Install x-fidelity
+      run: |
+        yarn global add x-fidelity
+        echo "$(yarn global bin)" >> $GITHUB_PATH
+    
+    - name: Run x-fidelity
+      env:
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        XFI_SHARED_SECRET: ${{ secrets.XFI_SHARED_SECRET }}
+      run: xfidelity . --configServer https://config-server.example.com
+```
+
+## Advanced Configuration
+
+### With OpenAI Integration
+
+```yaml
+- name: Run x-fidelity with OpenAI
+  env:
+    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+    OPENAI_MODEL: 'gpt-4'
+  run: xfidelity . -o true
+```
+
+### With Local Config
+
+```yaml
+- name: Run x-fidelity with local config
+  run: xfidelity . --localConfigPath ./config
+```
+
+### With Custom Archetype
+
+```yaml
+- name: Run x-fidelity with custom archetype
+  run: xfidelity . --archetype java-microservice
+```
+
+## GitHub Actions Specific Features
+
+### Caching Dependencies
+
+```yaml
+- uses: actions/cache@v3
+  with:
+    path: |
+      **/node_modules
+      $(yarn cache dir)
+    key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+    restore-keys: |
+      ${{ runner.os }}-yarn-
+```
+
+### Matrix Testing
+
+```yaml
+jobs:
+  check:
+    strategy:
+      matrix:
+        archetype: [node-fullstack, java-microservice]
+    
+    steps:
+    - name: Run x-fidelity
+      run: xfidelity . --archetype ${{ matrix.archetype }}
+```
+
+### Pull Request Comments
+
+```yaml
+- name: Comment PR
+  if: github.event_name == 'pull_request'
+  uses: actions/github-script@v6
+  with:
+    script: |
+      const fs = require('fs');
+      const results = JSON.parse(fs.readFileSync('results.json', 'utf8'));
+      github.rest.issues.createComment({
+        issue_number: context.issue.number,
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        body: `x-fidelity results:\n\`\`\`\n${JSON.stringify(results, null, 2)}\n\`\`\``
+      });
+```
+
+## Environment Variables
+
+Set these in your repository secrets:
+
+- `OPENAI_API_KEY`: For OpenAI integration
+- `XFI_SHARED_SECRET`: For config server authentication
+- `CONFIG_SERVER_URL`: Your config server URL
+
+## Best Practices
+
+1. **Secrets Management**: Use GitHub Secrets for sensitive data
+2. **Caching**: Implement proper caching strategy
+3. **Versioning**: Pin action and dependency versions
+4. **Error Handling**: Add proper error handling
+5. **Notifications**: Configure notifications for failures
+
+## Example Projects
+
+Check out these example repositories:
+- [x-fidelity-node-example](https://github.com/example/x-fidelity-node)
+- [x-fidelity-java-example](https://github.com/example/x-fidelity-java)
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Authentication Failures**:
+   - Check secret configuration
+   - Verify environment variables
+
+2. **Timeout Issues**:
+   - Increase GitHub Actions timeout
+   - Optimize analysis scope
+
+3. **Cache Problems**:
+   - Clear cache
+   - Update cache key

package/website/docs/ci-cd/gitlab-ci.md

@@ -0,0 +1,132 @@
+---
+sidebar_position: 3
+---
+
+# GitLab CI Integration
+
+This guide shows how to integrate x-fidelity into your GitLab CI/CD pipelines.
+
+## Basic Pipeline Configuration
+
+Create `.gitlab-ci.yml` in your repository:
+
+```yaml
+image: node:18
+
+stages:
+  - test
+
+x-fidelity:
+  stage: test
+  before_script:
+    - yarn global add x-fidelity
+    - export PATH="$PATH:$(yarn global bin)"
+  script:
+    - xfidelity . --configServer https://config-server.example.com
+  variables:
+    OPENAI_API_KEY: $OPENAI_API_KEY
+    XFI_SHARED_SECRET: $XFI_SHARED_SECRET
+```
+
+## Advanced Configuration
+
+### With OpenAI Integration
+
+```yaml
+x-fidelity:
+  script:
+    - xfidelity . -o true
+  variables:
+    OPENAI_API_KEY: $OPENAI_API_KEY
+    OPENAI_MODEL: 'gpt-4'
+```
+
+### With Local Config
+
+```yaml
+x-fidelity:
+  script:
+    - xfidelity . --localConfigPath ./config
+```
+
+### With Custom Archetype
+
+```yaml
+x-fidelity:
+  script:
+    - xfidelity . --archetype java-microservice
+```
+
+## GitLab CI Specific Features
+
+### Caching Dependencies
+
+```yaml
+x-fidelity:
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+      - .yarn
+```
+
+### Matrix Testing
+
+```yaml
+x-fidelity:
+  parallel:
+    matrix:
+      - ARCHETYPE: [node-fullstack, java-microservice]
+  script:
+    - xfidelity . --archetype $ARCHETYPE
+```
+
+### Pipeline Artifacts
+
+```yaml
+x-fidelity:
+  artifacts:
+    reports:
+      junit: results.xml
+    paths:
+      - results.json
+    expire_in: 1 week
+```
+
+## Environment Variables
+
+Set these in your GitLab CI/CD variables:
+
+- `OPENAI_API_KEY`: For OpenAI integration
+- `XFI_SHARED_SECRET`: For config server authentication
+- `CONFIG_SERVER_URL`: Your config server URL
+
+## Best Practices
+
+1. **Secrets Management**: Use GitLab CI/CD variables for sensitive data
+2. **Caching**: Implement proper caching strategy
+3. **Versioning**: Pin dependency versions
+4. **Error Handling**: Add proper error handling
+5. **Notifications**: Configure notifications for failures
+
+## Example Projects
+
+Check out these example repositories:
+- [x-fidelity-node-example](https://gitlab.com/example/x-fidelity-node)
+- [x-fidelity-java-example](https://gitlab.com/example/x-fidelity-java)
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Authentication Failures**:
+   - Check variable configuration
+   - Verify environment variables
+
+2. **Timeout Issues**:
+   - Increase job timeout
+   - Optimize analysis scope
+
+3. **Cache Problems**:
+   - Clear cache
+   - Update cache key