x-fidelity 1.0.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "x-fidelity",
+  "version": "1.0.0",
+  "description": "cli for opinionated framework adherence checks",
+  "main": "dist/xfidelity",
+  "bin": {
+    "xfidelity": "./dist/xfidelity"
+  },
+  "scripts": {
+    "build": "rimraf dist/ && tsc && yarn copy-files",
+    "copy-files": "cp src/rules/*.json dist/rules/ && cp dist/index.js dist/xfidelity",
+    "start": "jest --watch",
+    "test": "jest",
+    "commit": "git-cz",
+    "release": "semantic-release",
+    "test-bin-install": "yarn build && yarn global bin && yarn global add file:$PWD"
+  },
+  "repository": "git@github.com:zotoio/x-fidelity.git",
+  "author": "wyvern8 <io@zoto.io>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0",
+    "yarn": ">=1.22.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^10.0.6",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.0",
+    "@types/jest": "^29.5.12",
+    "@types/lodash": "^4.17.4",
+    "@types/node": "^20.14.2",
+    "@types/parse-json": "^4.0.2",
+    "@types/semver": "^7.5.8",
+    "@types/winston": "^2.4.4",
+    "commitizen": "^4.3.0",
+    "conventional-changelog-cli": "^5.0.0",
+    "conventional-recommended-bump": "^10.0.0",
+    "cz-conventional-changelog": "^3.3.0",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.7",
+    "semantic-release": "^24.0.0",
+    "ts-jest": "^29.1.4",
+    "ts-node": "^10.4.0",
+    "typescript": "^5.4.5"
+  },
+  "dependencies": {
+    "@yarnpkg/lockfile": "^1.1.0",
+    "axios": "^1.7.2",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "format-json": "^1.0.3",
+    "json-rules-engine": "^6.5.0",
+    "lodash": "^4.17.21",
+    "nodemon": "^3.0.2",
+    "semver": "^7.6.2",
+    "winston": "^3.13.0",
+    "yarn": "^1.22.21"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
+}

package/src/core/cli.ts

@@ -0,0 +1,42 @@
+import { logger } from '../utils/logger';
+import { program } from "commander";
+
+const banner = (`
+=====================================
+ __    __          ________  ______ 
+| ##  | ##        | ######## \\######
+ \\##\\/  ## ______ | ##__      | ##  
+  >##  ## |      \\| ##  \\     | ##  
+ /  ####\\  \\######| ######    | ##  
+|  ## \\##\\        | ##       _| ##_ 
+| ##  | ##        | ##      |   ## \\
+ \\##   \\##         \\##       \\######
+                               
+-------------------------------------
+${new Date().toString()}`);
+
+console.log(banner);
+logger.info([banner]);
+
+program
+    .option("-d, --dir <directory>", "The repo checkout directory")
+    .option("-c, --configUrl <url>", "The URL used to fetch config");
+
+program.parse();
+
+const options = program.opts();
+
+// print help if no arguments are passed
+if (program.options.length === 0) program.help();
+
+if (!options.dir) {
+    console.error("Repo directory is required. Please specify the directory using the -d or --dir option.");
+    process.exit(1);
+}
+
+console.log(`Analysis of: ${process.env.PWD}/${options.dir}`);
+logger.info(`Analysis of: ${process.env.PWD}/${options.dir}`);
+console.log('=====================================');
+logger.info('=====================================');
+
+export { options };

package/src/core/engine.test.ts

@@ -0,0 +1,82 @@
+import { analyzeCodebase } from './engine';
+import { Engine } from 'json-rules-engine';
+import { collectRepoFileData, collectStandardDirectoryStructure } from '../facts/repoFilesystemFacts';
+import { getDependencyVersionFacts, collectMinimumDependencyVersions } from '../facts/repoDependencyFacts';
+import { loadRules } from '../rules';
+import { operators } from '../operators';
+import { logger } from '../utils/logger';
+
+jest.mock('json-rules-engine');
+jest.mock('../facts/repoFilesystemFacts');
+jest.mock('../facts/repoDependencyFacts');
+jest.mock('../rules');
+jest.mock('../operators');
+jest.mock('../utils/logger');
+
+describe('analyzeCodebase', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should analyze the codebase and return results', async () => {
+        const mockFileData = [{ filePath: 'src/index.ts', fileContent: 'console.log("Hello, world!");' }];
+        const mockDependencyData = [{ dep: 'commander', ver: '2.0.0', min: '^2.0.0' }];
+        const mockStandardStructure = { src: { core: null, utils: null, operators: null, rules: null, facts: null } };
+        const mockRules = [{ name: 'mockRule', conditions: { all: [] }, event: { type: 'mockEvent' } }];
+
+        (collectRepoFileData as jest.Mock).mockResolvedValue(mockFileData);
+        (getDependencyVersionFacts as jest.Mock).mockResolvedValue(mockDependencyData);
+        (collectMinimumDependencyVersions as jest.Mock).mockResolvedValue({});
+        (collectStandardDirectoryStructure as jest.Mock).mockResolvedValue(mockStandardStructure);
+        (loadRules as jest.Mock).mockResolvedValue(mockRules);
+
+        const engineRunMock = jest.fn().mockResolvedValue({ failureResults: [] });
+        (Engine as jest.Mock).mockImplementation(() => ({
+            addOperator: jest.fn(),
+            addRule: jest.fn(),
+            on: jest.fn(),
+            run: engineRunMock
+        }));
+
+        const results = await analyzeCodebase('mockRepoPath');
+
+        expect(collectRepoFileData).toHaveBeenCalledWith('mockRepoPath');
+        expect(getDependencyVersionFacts).toHaveBeenCalled();
+        expect(collectMinimumDependencyVersions).toHaveBeenCalled();
+        expect(collectStandardDirectoryStructure).toHaveBeenCalled();
+        expect(loadRules).toHaveBeenCalled();
+        expect(engineRunMock).toHaveBeenCalledTimes(mockFileData.length);
+        expect(results).toEqual([]);
+    });
+
+    it('should handle errors during analysis', async () => {
+        const mockFileData = [{ filePath: 'src/index.ts', fileContent: 'console.log("Hello, world!");' }];
+        const mockDependencyData = [{ dep: 'commander', ver: '2.0.0', min: '^2.0.0' }];
+        const mockStandardStructure = { src: { core: null, utils: null, operators: null, rules: null, facts: null } };
+        const mockRules = [{ name: 'mockRule', conditions: { all: [] }, event: { type: 'mockEvent' } }];
+
+        (collectRepoFileData as jest.Mock).mockResolvedValue(mockFileData);
+        (getDependencyVersionFacts as jest.Mock).mockResolvedValue(mockDependencyData);
+        (collectMinimumDependencyVersions as jest.Mock).mockResolvedValue({});
+        (collectStandardDirectoryStructure as jest.Mock).mockResolvedValue(mockStandardStructure);
+        (loadRules as jest.Mock).mockResolvedValue(mockRules);
+
+        const engineRunMock = jest.fn().mockRejectedValue(new Error('mock error'));
+        (Engine as jest.Mock).mockImplementation(() => ({
+            addOperator: jest.fn(),
+            addRule: jest.fn(),
+            on: jest.fn(),
+            run: engineRunMock
+        }));
+
+        const results = await analyzeCodebase('mockRepoPath');
+
+        expect(collectRepoFileData).toHaveBeenCalledWith('mockRepoPath');
+        expect(getDependencyVersionFacts).toHaveBeenCalled();
+        expect(collectMinimumDependencyVersions).toHaveBeenCalled();
+        expect(collectStandardDirectoryStructure).toHaveBeenCalled();
+        expect(loadRules).toHaveBeenCalled();
+        expect(engineRunMock).toHaveBeenCalledTimes(mockFileData.length);
+        expect(results).toEqual([]);
+    });
+});

package/src/core/engine.ts

@@ -0,0 +1,68 @@
+import { logger } from '../utils/logger';
+import { Engine,RuleProperties } from 'json-rules-engine';
+import { FileData, collectRepoFileData, collectStandardDirectoryStructure } from '../facts/repoFilesystemFacts'; 
+import { loadRules } from '../rules';
+import { operators } from '../operators';
+import { ScanResult, RuleFailure } from '../typeDefs';
+import { getDependencyVersionFacts, collectMinimumDependencyVersions } from                    
+ '../facts/repoDependencyFacts';                                                                                        
+                                                                                                                        
+ async function analyzeCodebase(repoPath: string, configUrl?: string): Promise<any[]> {                                 
+     const installedDependencyVersions = await getDependencyVersionFacts();                                             
+     const fileData: FileData[] = await collectRepoFileData(repoPath);                                                  
+     const minimumDependencyVersions = await collectMinimumDependencyVersions(configUrl);                               
+     const standardStructure = await collectStandardDirectoryStructure(configUrl);                                                 
+                                                                                                                        
+     const engine = new Engine([], { replaceFactsInEventParams: true });                                                
+                                                                                                                        
+     // Add operators to engine                                                                                         
+     operators.map((operator) => engine.addOperator(operator.name, operator.fn));                                       
+                                                                                                                        
+     // Add rules to engine                                                                                             
+     const rules: RuleProperties[] = await loadRules();                                                                 
+                                                                                                                        
+     rules.map((rule) => {                                                                                              
+                                                                                                                        
+         try {                                                                                                          
+             engine.addRule(rule)                                                                                       
+         } catch (e: any) {                                                                                             
+             console.error(`Error loading rule: ${rule?.name}`);                                                        
+             console.error(e.message);                                                                                  
+         }                                                                                                              
+     });                                                                                                                
+                                                                                                                        
+     engine.on('failure', function(event, almanac, ruleResult) {                                                        
+         //console.log(event)                                                                                           
+     });                                                                                                                
+                                                                                                                        
+     // Run the engine for each file's data                                                                             
+     let results: ScanResult[] = [];                                                                                    
+     for (const file of fileData) {                                                                                     
+         logger.info(`running engine for ${file.filePath}`);                                                            
+                                                                                                                        
+         const facts = {fileData: file, dependencyData: {installedDependencyVersions, minimumDependencyVersions},       
+ standardStructure};                                                                                                    
+         let fileFailures: RuleFailure[] = [];                                                                          
+                                                                                                                        
+         await engine.run(facts)                                                                                        
+             .then(({failureResults}) => {                                                                              
+                 failureResults.map((result) => {                                                                       
+                     fileFailures.push({                                                                                
+                         ruleFailure: result?.name,                                                                     
+                         details: result?.event?.params                                                                 
+                     })                                                                                                 
+                 })                                                                                                     
+             }).catch(e => logger.error(e));                                                                             
+                                                                                                                        
+         if (fileFailures.length > 0) {                                                                                 
+             results.push({ filePath: file.filePath, errors: fileFailures});                                            
+         }                                                                                                              
+     }                                                                                                                  
+                                                                                                                        
+     logger.info(`${fileData.length} files analyzed. ${results.length} files with errors.`)                             
+                                                                                                                        
+     return results;                                                                                                    
+                                                                                                                        
+ }                                                                                                                      
+                                                                                                                        
+ export { analyzeCodebase }; 

package/src/facts/repoDependencyFacts.test.ts

@@ -0,0 +1,166 @@
+import { execSync } from 'child_process';
+import { collectMinimumDependencyVersions, collectLocalDependencies, getDependencyVersionFacts, findPropertiesInTree } from './repoDependencyFacts';
+import { logger } from '../utils/logger';
+import _ from 'lodash';
+
+jest.mock('child_process', () => ({
+    execSync: jest.fn(),
+}));
+
+jest.mock('../utils/logger', () => ({
+    logger: {
+        error: jest.fn(),
+        debug: jest.fn(),
+    },
+}));
+
+describe('collectMinimumDependencyVersions', () => {
+    it('should return the correct minimum dependency versions', async () => {
+        const result = await collectMinimumDependencyVersions();
+        expect(result).toEqual({
+            commander: '^2.0.0',
+            nodemon: '^3.9.0'
+        });
+    });
+});
+
+describe('collectLocalDependencies', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should return parsed JSON result when execSync succeeds', () => {
+        const mockResult = JSON.stringify({ dependencies: {} });
+        (execSync as jest.Mock).mockReturnValue(Buffer.from(mockResult));
+
+        const result = collectLocalDependencies();
+        expect(result).toEqual({ dependencies: {} });
+    });
+
+    it('should log error and return empty object when execSync fails', () => {
+        (execSync as jest.Mock).mockImplementation(() => {
+            throw new Error('mock error');
+        });
+
+        const result = collectLocalDependencies();
+        expect(logger.error).toHaveBeenCalledWith('exec error: Error: mock error');
+        //expect(console.error).toHaveBeenCalledWith('exec error: Error: mock error');
+        expect(result).toEqual({});
+    });
+
+    it('should handle non-JSON response gracefully', () => {
+        (execSync as jest.Mock).mockReturnValue(Buffer.from('invalid json'));
+
+        const result = collectLocalDependencies();
+        expect(result).toEqual({});
+    });
+});
+
+describe('getDependencyVersionFacts', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should return installed dependency versions correctly', async () => {
+        const mockLocalDependencies = { dependencies: { commander: { version: '2.0.0' }, nodemon: { version: '3.9.0' } } };
+        const mockMinimumVersions = { commander: '^2.0.0', nodemon: '^3.9.0' };
+        
+        (execSync as jest.Mock).mockReturnValue(Buffer.from(JSON.stringify(mockLocalDependencies)));
+        
+        const result = await getDependencyVersionFacts();
+        expect(result).toEqual([
+            { dep: 'commander', ver: '2.0.0', min: '^2.0.0' },
+            { dep: 'nodemon', ver: '3.9.0', min: '^3.9.0' }
+        ]);
+    });
+
+    it('should return an empty array if no dependencies match minimum versions', async () => {
+        const mockLocalDependencies = { dependencies: { someOtherDep: { version: '1.0.0' } } };
+        const mockMinimumVersions = { commander: '^2.0.0', nodemon: '^3.9.0' };
+
+        (execSync as jest.Mock).mockReturnValue(Buffer.from(JSON.stringify(mockLocalDependencies)));
+        
+        const result = await getDependencyVersionFacts();
+        expect(result).toEqual([]);
+    });
+});
+
+describe('findPropertiesInTree', () => {
+    it('should find properties in the tree correctly', () => {
+        const depGraph = {
+            commander: { version: '2.0.0' },
+            nodemon: { version: '3.9.0' }
+        };
+        const minVersions = { commander: '^2.0.0', nodemon: '^3.9.0' };
+
+        const result = findPropertiesInTree(depGraph, minVersions);
+        expect(result).toEqual([
+            { dep: 'commander', ver: '2.0.0', min: '^2.0.0' },
+            { dep: 'nodemon', ver: '3.9.0', min: '^3.9.0' }
+        ]);
+    });
+
+    it('should return an empty array if no properties match', () => {
+        const depGraph = {
+            someOtherDep: { version: '1.0.0' }
+        };
+        const minVersions = { commander: '^2.0.0', nodemon: '^3.9.0' };
+
+        const result = findPropertiesInTree(depGraph, minVersions);
+        expect(result).toEqual([]);
+    });
+
+    it('should handle nested dependencies correctly', () => {
+        const depGraph = {
+                commander: { version: '2.0.0',
+                dependencies: {
+                    nodemon: { version: '3.9.0' }
+                }
+                }    
+        };
+        const minVersions = { commander: '^2.0.0', nodemon: '^3.9.0' };
+
+        const result = findPropertiesInTree(depGraph, minVersions);
+        expect(result).toEqual([
+            { dep: 'commander', ver: '2.0.0', min: '^2.0.0' },
+            { dep: 'nodemon', ver: '3.9.0', min: '^3.9.0' }
+        ]);
+    });
+
+    it('should not add non-matching dependencies to results', () => {
+        const depGraph = {
+            someOtherDep: { version: '1.0.0' }
+        };
+        const minVersions = { commander: '^2.0.0', nodemon: '^3.9.0' };
+
+        const result = findPropertiesInTree(depGraph, minVersions);
+        expect(result).toEqual([]);
+    });
+
+    it('should handle complex mixed structures', () => {
+        const depGraph = {
+            commander: { 
+                version: '2.0.0',
+                dependencies: {
+                    nodemon: {
+                        version: '3.9.0',
+                        dependencies: {
+                            lodash: { 
+                                version: '4.17.21' 
+                            }
+                        }
+                    }    
+                }
+            }
+        };
+        const minVersions = { commander: '^2.0.0', nodemon: '^3.9.0', lodash: '^4.17.20' };
+
+        const result = findPropertiesInTree(depGraph, minVersions);
+        //console.log(result);
+        expect(result).toEqual([
+            { dep: 'commander', ver: '2.0.0', min: '^2.0.0' },
+            { dep: 'nodemon', ver: '3.9.0', min: '^3.9.0' },
+            { dep: 'lodash', ver: '4.17.21', min: '^4.17.20' }
+        ]);
+    });
+});

package/src/facts/repoDependencyFacts.ts

@@ -0,0 +1,88 @@
+import { logger } from '../utils/logger';
+import _ from 'lodash';
+import axios from 'axios';
+import { execSync } from 'child_process';
+import { LocalDependencies, MinimumDepVersions, VersionData } from '../typeDefs';
+
+/**                                                                                                                    
+  * Collects the minimum dependency versions.                                                                           
+  * @returns The minimum dependency versions.                                                                           
+  */                                                                                                                    
+export async function collectMinimumDependencyVersions(configUrl?: string) {                                           
+    if (configUrl) {                                                                                                   
+        try {                                                                                                          
+            const response = await axios.get(configUrl);                                                               
+            return response.data.minimumDependencyVersions;                                                            
+        } catch (error) {                                                                                              
+            logger.error(`Error fetching minimum dependency versions from configUrl: ${error}`);                       
+            return {};                                                                                                 
+        }                                                                                                              
+    } else {                                                                                                           
+        return {
+            commander: '^2.0.0',
+            nodemon: '^3.9.0'
+        };                                                                                                              
+    }                                                                                                                  
+}
+
+/**
+ * Collects the local dependencies.
+ * @returns The local dependencies.
+ */
+export function collectLocalDependencies(): LocalDependencies {
+    let result: LocalDependencies = {};
+    try {
+        let stdout = execSync('npm ls -a --json');
+        result = JSON.parse(stdout.toString());
+    } catch (e) {
+        logger.error(`exec error: ${e}`);
+        //console.error(`exec error: ${e}`);
+    }
+    return result;
+}
+
+/**
+ * Gets the installed dependency versions.
+ * @returns The installed dependency versions.
+ */
+export async function getDependencyVersionFacts() {
+    const localDependencies = await collectLocalDependencies();
+    const minimumDependencyVersions = await collectMinimumDependencyVersions();
+
+    //console.log(localDependencies);
+
+    const installedDependencyVersions = findPropertiesInTree(localDependencies, minimumDependencyVersions);
+    return installedDependencyVersions;
+}
+
+/**
+ * Recursively search for properties in a tree of objects.
+ * @param depGraph - The object to search.
+ * @param minVersions - The minimum dependency versions to search for.
+ * @returns An array of results.
+ */
+export function findPropertiesInTree(depGraph: LocalDependencies, minVersions: MinimumDepVersions): VersionData[] {
+    let results: VersionData[] = [];
+
+    logger.debug(`depGraph: ${depGraph}`);
+
+    function walk(depGraph: LocalDependencies) {
+        if (_.isObject(depGraph) && !_.isArray(depGraph)) {
+            for (let depName in depGraph) {
+                if (Object.keys(minVersions).includes(depName)) {
+                    results.push({ dep: depName, ver: depGraph[depName].version, min: minVersions[depName] });
+                }
+                if (_.isObject(depGraph[depName])) {
+                    walk(depGraph[depName] as unknown as LocalDependencies);
+                }
+            }
+        } else if (_.isArray(depGraph)) {
+            for (let item of depGraph) {
+                walk(item);
+            }
+        }
+    }
+
+    walk(depGraph);
+    return results;
+}

package/src/facts/repoFilesystemFacts.ts

@@ -0,0 +1,80 @@
+import { logger } from '../utils/logger';
+import axios from 'axios';
+import fs from 'fs';
+import path from 'path';
+
+interface FileData {
+    fileName: string;
+    filePath: string;
+    fileContent: string;
+}
+
+async function parseFile(filePath: string): Promise<FileData> {
+    return Promise.resolve({
+        fileName: path.basename(filePath),
+        filePath,
+        fileContent: fs.readFileSync(filePath, 'utf8')
+    });
+}
+
+async function collectRepoFileData(repoPath: string): Promise<FileData[]> {
+    const filesData: FileData[] = [];
+
+    logger.debug(`collectingRepoFileData from: ${repoPath}`);
+    const files = fs.readdirSync(repoPath);
+
+    for (const file of files) {
+        const filePath = path.join(repoPath, file);
+        if (!ignored(filePath)) {
+            const stats = await fs.promises.lstat(filePath);
+            if (stats.isDirectory()) {
+                const dirFilesData = await collectRepoFileData(filePath);
+                filesData.push(...dirFilesData);
+            } else {
+                const fileData = await parseFile(filePath);
+                filesData.push(fileData);
+            }
+        }
+    }
+    return filesData;
+}
+
+function ignored(file: string){
+    return file.startsWith('.') 
+        || file.includes('node_modules')
+        || file.includes('/.')
+        || file.endsWith('-rule.json')
+        || file.includes('/dist/')
+        || file.includes('/lcov')
+        || file.startsWith('dist')
+        || file.endsWith('md')
+        || file.endsWith('.log')
+        || file.includes('LICENSE');
+}
+
+const standardStructure = {                                                                                            
+    "src": {                                                                                                           
+        "core": null,                                                                                                  
+        "utils": null,                                                                                                 
+        "operators": null,                                                                                             
+        "rules": null,                                                                                                 
+        "facts": null,
+        "FAIL": null                                                                                                  
+    }                                                                                                                  
+};                                                                                                                     
+                                                                                                                       
+async function collectStandardDirectoryStructure(configUrl?: string) {                                                     
+    if (configUrl) {                                                                                                   
+        try {                                                                                                          
+            const response = await axios.get(configUrl);                                                               
+            return response.data.standardStructure;                                                                    
+        } catch (error) {                                                                                              
+            logger.error(`Error fetching standard structure from configUrl: ${error}`);                                
+            return standardStructure;                                                                                  
+        }                                                                                                              
+    } else {                                                                                                           
+        return standardStructure;                                                                                      
+    }                                                                                                                  
+}
+
+export { collectRepoFileData, FileData, collectStandardDirectoryStructure }

package/src/index.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { logger } from './utils/logger';
+let json = require('format-json');
+import { options } from "./core/cli"; 
+import { analyzeCodebase } from "./core/engine";
+
+
+//console.log(`analyzing repo at path: [${options.dir}]`);
+
+try {
+    (async () => {
+        let results = await analyzeCodebase(options.dir, options.configUrl);
+        if (results.length > 0) {
+            //console.log('WARNING: lo-fi attributes detected in codebase!');
+            //console.log(results);
+        } else {
+            //console.log('hi-fi codebase detected!');
+        }
+        logger.info(results);
+        console.log(JSON.stringify(results));
+        //console.log(`opinionated codebase analysis completed with ${results.length} failed checks.`);
+    })().catch((e) => {console.log(e)});
+} catch(e) {
+    console.log(e)
+}