properties-comparator 1.0.4 → 1.0.6

package/.github/workflows/sonarcloud.yml

@@ -0,0 +1,75 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# This workflow helps you trigger a SonarCloud analysis of your code and populates
+# GitHub Code Scanning alerts with the vulnerabilities found.
+# Free for open source project.
+
+# 1. Login to SonarCloud.io using your GitHub account
+
+# 2. Import your project on SonarCloud
+#     * Add your GitHub organization first, then add your repository as a new project.
+#     * Please note that many languages are eligible for automatic analysis,
+#       which means that the analysis will start automatically without the need to set up GitHub Actions.
+#     * This behavior can be changed in Administration > Analysis Method.
+#
+# 3. Follow the SonarCloud in-product tutorial
+#     * a. Copy/paste the Project Key and the Organization Key into the args parameter below
+#          (You'll find this information in SonarCloud. Click on "Information" at the bottom left)
+#
+#     * b. Generate a new token and add it to your Github repository's secrets using the name SONAR_TOKEN
+#          (On SonarCloud, click on your avatar on top-right > My account > Security
+#           or go directly to https://sonarcloud.io/account/security/)
+
+# Feel free to take a look at our documentation (https://docs.sonarcloud.io/getting-started/github/)
+# or reach out to our community forum if you need some help (https://community.sonarsource.com/c/help/sc/9)
+
+name: SonarCloud analysis
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  pull-requests: read # allows SonarCloud to decorate PRs with analysis results
+
+jobs:
+  Analysis:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run tests with coverage
+        run: npm test -- --coverage
+
+      - name: Analyze with SonarCloud
+        uses: SonarSource/sonarcloud-github-action@4006f663ecaf1f8093e8e4abb9227f6041f52216
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        with:
+          args: -Dsonar.projectKey=zackria_properties-comparator
+            -Dsonar.organization=zackria
+            -Dsonar.sources=index.js,cli.js,src
+            -Dsonar.tests=test
+            -Dsonar.test.inclusions=test/**/*.test.js
+            -Dsonar.exclusions=node_modules/**,coverage/**,index.js
+            -Dsonar.cpd.exclusions=index.js
+            -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info
+          projectBaseDir: .

package/DOCUMENTATION.md

@@ -2,13 +2,18 @@
 
 ## Overview
 
-This utility parses and compares **.properties** and **.yml or .yaml (YAML)** files. It reads each file as key-value pairs, compares the values for each key across multiple files, and logs the results.
+This utility parses and compares **.properties** and **.yml or .yaml (YAML)** files. It reads each file as key-value pairs, compares the values for each key across multiple files, and produces detailed comparison reports.
 
 ### Features:
 - Parse **.properties** files into key-value objects.
 - Parse **.yml or .yaml** (YAML) files into flattened key-value objects (supports nested keys).
 - Compare key values across multiple files (both **.properties** and **.yml or .yaml**).
-- Log detailed comparison results, including mismatches.
+- Generate reports in multiple formats:
+  - Console output with color-coded highlighting
+  - HTML reports with CSS styling
+  - Markdown reports
+- Save reports to files or display in console
+- Flexible command-line interface with options
 
 ---
 
@@ -26,7 +31,26 @@ This utility parses and compares **.properties** and **.yml or .yaml (YAML)** fi
 Run the script using Node.js with file paths provided as command-line arguments:
 
 ```bash
-node script.js <filePath1> <filePath2> [<filePath3> ...]
+node compareUtility.js [options] <filePath1> <filePath2> [<filePath3> ...]
+```
+
+### Command-Line Options
+```
+Options:
+  --format, -f <format>   Output format: console, html, or markdown
+  --output, -o <file>     Output file for html or markdown reports
+```
+
+### Examples
+```bash
+# Basic comparison with console output
+node compareUtility.js file1.properties file2.yaml
+
+# Generate HTML report and save to output.html
+node compareUtility.js --format html --output output.html file1.properties file2.yaml
+
+# Short form options
+node compareUtility.js -f markdown -o report.md file1.properties file2.properties file3.yml
 ```
 
 ### Input Format
@@ -37,6 +61,13 @@ key2=value2
 # Comments are ignored
 ```
 
+YAML files should follow standard YAML format. Nested structures will be flattened with dot notation:
+```yaml
+key1: value1
+key2:
+  nestedKey: nestedValue  # Will be accessible as "key2.nestedKey"
+```
+
 ---
 
 ## Functions
@@ -60,113 +91,213 @@ console.log(properties);
 
 ---
 
-### `compareProperties(filePaths)`
+### `parseYamlFile(filePath)`
 
-Compares properties across multiple properties files and logs the results.
+Parses a .yml or .yaml file into a flat key-value map using dot notation for nested keys.
 
 #### Parameters:
-- `filePaths` (string[]): Array of file paths to be compared.
+- `filePath` (string): Path to the YAML file.
 
 #### Returns:
-- None. Outputs comparison results to the console.
+- (Object): A flattened object containing key-value pairs from the YAML file.
 
 #### Example:
-```bash
-node script.js file1.properties file2.yaml file3.yml
+```javascript
+const data = parseYamlFile('/path/to/yaml/file');
+console.log(data);
+// Output: { 'key1': 'value1', 'key2.nestedKey': 'nestedValue' }
 ```
 
-#### Output Example:
-```text
-Comparing properties across files:
+---
 
-Key: key1 - Values match across all files.
-Key: key2 - Mismatched values:
-  File 1: value1
-  File 2: value2
-  File 3: value3
-```
+### `parseFile(filePath)`
+
+Detects file extension and parses the file content into an object.
+
+#### Parameters:
+- `filePath` (string): Path to the file (.properties, .yml, or .yaml).
+
+#### Returns:
+- (Object): Parsed content as a key-value map, or {} if unsupported.
 
 ---
 
-### Runtime Input Handling
+### `compareFileData(filePaths)`
 
-The script expects file paths as command-line arguments:
-- Extracted from `process.argv`.
-- If no file paths are provided, it displays an error and exits:
-  ```
-  Please provide the paths to the properties files as command-line arguments.
-  ```
-- Verifies the existence of all specified files. If any file is missing:
-  ```
-  One or more properties files are missing. Ensure all specified properties files exist.
-  ```
+Internal helper that compares key-value data from multiple files and returns structured results.
+
+#### Parameters:
+- `filePaths` (string[]): Array of file paths.
+
+#### Returns:
+- (Object): An object containing mismatch count and detailed comparison information.
+
+---
+
+### `checkIfAllValuesMatch(filePaths)`
+
+Checks if all values match across the provided files.
+
+#### Parameters:
+- `filePaths` (string[]): Array of file paths.
+
+#### Returns:
+- (boolean): True if all properties match across all files, false otherwise.
 
 ---
 
-### Additional Functions
+### `getMismatchFields(filePaths)`
 
-#### `parseFile(filePath)`
-Detects file extension and parses `.properties`, `.yaml`, or `.yml` files. Returns an object with flattened key-value pairs or `{}` if unsupported.
+Returns a list of fields (keys) that do not match across the provided files.
 
-#### `parseYamlFile(filePath)`
-Parses a `.yml` or `.yaml` file into a flat key-value map. Returns an object with dot-notation keys for nested values.
+#### Parameters:
+- `filePaths` (string[]): Array of file paths.
 
-#### `compareFileData(filePaths)`
-Internally compares parsed data from multiple files. Returns an object with `mismatchCount` and detailed info for each key.
+#### Returns:
+- (string[]): List of mismatched keys.
 
-#### `checkIfAllValuesMatch(filePaths)`
-Checks if all keys match across all provided files. Returns a boolean.
+---
 
-#### `getMismatchFields(filePaths)`
-Returns an array of keys whose values differ across files.
+### `generateHtmlReport(filePaths, comparisonData)`
 
-#### `compareFiles(filePaths)`
-Logs detailed comparison of key-value pairs across files. Prints a summary indicating mismatched keys.
+Generates an HTML report for the comparison results.
+
+#### Parameters:
+- `filePaths` (string[]): Array of file paths that were compared.
+- `comparisonData` (Object): The output from compareFileData function.
 
-#### `run()`
-CLI entry point. Reads file paths, checks existence, and calls `compareFiles`.
+#### Returns:
+- (string): HTML document as string.
+
+---
+
+### `generateMarkdownReport(filePaths, comparisonData)`
+
+Generates a Markdown report for the comparison results.
+
+#### Parameters:
+- `filePaths` (string[]): Array of file paths that were compared.
+- `comparisonData` (Object): The output from compareFileData function.
+
+#### Returns:
+- (string): Markdown document as string.
+
+---
+
+### `compareFiles(filePaths, options)`
+
+Compares properties/keys across multiple files and generates a report based on options.
+
+#### Parameters:
+- `filePaths` (string[]): Array of file paths.
+- `options` (Object): Options for comparison output.
+  - `format` (string): Output format ('console', 'html', or 'markdown').
+  - `outputFile` (string): Path to save the report (for html and markdown).
+
+#### Example:
+```javascript
+// Compare with console output
+compareFiles(['file1.properties', 'file2.yaml']);
+
+// Generate HTML report
+compareFiles(['file1.properties', 'file2.yaml'], { 
+  format: 'html', 
+  outputFile: 'report.html' 
+});
+```
+
+---
+
+### `run()`
+
+CLI entry point. Parses command-line arguments and runs the comparison.
+
+---
+
+## Output Formats
+
+### Console Output
+The default output format provides:
+- A table showing all keys and their values across files
+- Highlighted mismatched rows for easy identification
+- A summary of mismatched keys
+
+### HTML Report
+Generates a visually appealing HTML report with:
+- CSS styling
+- Color-coded cells for matches and mismatches
+- Summary section with quick statistics
+- Responsive design
+
+### Markdown Report
+Creates a Markdown document with:
+- File list with paths
+- Comparison table
+- Summary section with mismatched keys highlighted
 
 ---
 
 ## Error Handling
 
 - **No File Paths Provided**: Logs an error and exits.
+- **Only One File Provided**: Logs an error about needing at least two files and exits.
 - **Missing Files**: Logs missing files and exits.
-- **Empty or Malformed Properties Files**: Skips invalid lines.
+- **Unsupported File Extensions**: Logs a warning and treats as empty file.
+- **Invalid YAML**: Logs error details and treats as empty file.
+- **Invalid Format Option**: Falls back to console output with warning.
 
 ---
 
-## Example Properties Files
+## Example Scenarios
+
+### Basic Comparison
 
-### File 1 (`file1.properties`):
+#### Command:
+```bash
+node compareUtility.js file1.properties file2.properties
 ```
-key1=value1
-key2=value2
+
+#### Output:
 ```
+Comparing properties/keys across files:
+
+┌─────────┬─────┬────────────┬────────────┐
+│ (index) │ Key │ Matched    │ ...        │
+├─────────┼─────┼────────────┼────────────┤
+│ 0       │ ... │ 'Yes'      │ ...        │
+│ 1       │ ... │ 'No'       │ ...        │
+└─────────┴─────┴────────────┴────────────┘
 
-### File 2 (`file2.properties`):
+=== Highlighted Mismatched Rows ===
+Key: key2 | File 1: value2 | File 2: value3
+
+=== Summary ===
+1 key(s) have mismatched values.
+Mismatched keys: key2
 ```
-key1=value1
-key2=value3
+
+### HTML Report Generation
+
+#### Command:
+```bash
+node compareUtility.js -f html -o report.html file1.properties file2.yaml
 ```
 
----
+#### Output:
+```
+HTML report saved to: report.html
+```
 
-## Sample Execution
+### Markdown Report Generation
 
-### Command:
+#### Command:
 ```bash
-node script.js file1.properties file2.properties
+node compareUtility.js -f markdown -o report.md file1.properties file2.properties
 ```
 
-### Output:
-```text
-Comparing properties across files:
-
-Key: key1 - Values match across all files.
-Key: key2 - Mismatched values:
-  File 1: value2
-  File 2: value3
+#### Output:
+```
+Markdown report saved to: report.md
 ```
 
 ---
@@ -174,21 +305,23 @@ Key: key2 - Mismatched values:
 ## Dependencies
 
 - `fs` module (Node.js File System)
-- `js-yaml` module (Node.js YAML library)
+- `path` module (Node.js Path)
+- `js-yaml` module (YAML parsing)
+- `chalk` module (Terminal styling)
 
 ---
 
 ## Limitations
 
-- Assumes properties are simple key-value pairs separated by `=`.
-- Ignores keys without a corresponding value.
-- Does not support multi-line properties.
+- Assumes properties are simple key-value pairs separated by `=`
+- Does not support multi-line properties in .properties files
+- Flattens all nested YAML structures to dot notation
 
 ---
 
 ## License
 
-This script is licensed under the MIT License.
+This utility is licensed under the MIT License.
 
 ---
 

package/PUBLISH.MD

@@ -4,13 +4,15 @@
 ###  Test Locally 
 `npm link`
 
+`npm unlink -g`
+
+`npm link properties-comparator`
 
 ## Now you can run the script globally using:
 
 ```properties-comparator <filePath1> <filePath2>```
 
 
-
 ## Publish the Package
 ### Login to npm (if you haven't already):
 `npm login`

package/README.md

@@ -1,20 +1,91 @@
 # properties-comparator
-This utility provides functionality to parse and compare **.properties** and **.yml or .yaml(YAML)** files in the format of key-value pairs. It reads these files, compares the values for each key across multiple files, and logs the results.
 
+A powerful utility for parsing and comparing **.properties** and **.yml/.yaml** files. This tool reads files as key-value pairs, compares values across multiple files, and generates detailed comparison reports in various formats.
 
-Utility is available as NPM Package [https://www.npmjs.com/package/properties-comparator](https://www.npmjs.com/package/properties-comparator)
+[![NPM Package](https://img.shields.io/npm/v/properties-comparator.svg)](https://www.npmjs.com/package/properties-comparator)  [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=zackria_properties-comparator&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=zackria_properties-comparator) 
 
+## Features
 
-###  Install the Package
-`npm install -g properties-comparator`
+- **Multi-format Support**: Parse both **.properties** files and **.yml/.yaml** (YAML) files
+- **Nested Structure Handling**: Flatten nested YAML structures into key-value pairs
+- **Comprehensive Comparison**: Compare values across multiple files simultaneously
+- **Multiple Report Formats**:
+  - Console output with color-coded highlighting
+  - HTML reports with CSS styling
+  - Markdown reports
+- **Flexible Output Options**: Save reports to files or display in console
+- **User-friendly CLI**: Simple command-line interface with intuitive options
 
+## Installation
 
-## Now you can run the script globally using:
+```bash
+# Install globally
+npm install -g properties-comparator
 
-```properties-comparator <filePath1> <filePath2>```
+# To uninstall
+npm uninstall -g properties-comparator
+```
 
-## Compiled on npm@11.1.0 & node v22.13.0
-`npm install -g npm@11.1.0`
+## Usage
 
+### Basic Usage
 
-### Check [Documentation](DOCUMENTATION.md) for more details
+Compare two or more files:
+
+```bash
+properties-comparator <filePath1> <filePath2> [<filePath3> ...]
+```
+
+### Examples
+
+Compare multiple files:
+```bash
+properties-comparator ./config1.properties ./config2.yml ./config3.properties
+```
+
+Generate HTML report:
+```bash
+properties-comparator -f html -o report.html ./config1.properties ./config2.yml
+```
+
+Generate Markdown report:
+```bash
+properties-comparator -f markdown -o report.md ./config1.properties ./config2.yml
+```
+
+### Command Options
+
+- `-f, --format <type>` - Report format (console, html, markdown)
+- `-o, --output <file>` - Output file for the report
+- `-h, --help` - Display help information
+
+## Report Examples
+
+### Terminal View
+![Terminal Report](./screenshots/TerminalTable.png)
+
+### HTML View
+![HTML Report](./screenshots/HtmlReport.png)
+
+### Markdown View
+![Markdown Report](./screenshots/MarkDownReport.png)
+
+## Quality Assurance
+
+This package is thoroughly tested with over 90% code coverage to ensure reliability.
+
+![Test Coverage](./screenshots/TestCoverage.png)
+
+## Compatibility
+
+Developed and tested with:
+- npm v11.7.0
+- Node.js v25.2.1
+
+## Documentation
+
+For more detailed information, please check the [Documentation](DOCUMENTATION.md).
+
+## License
+
+[MIT](LICENSE)

package/TEST.md

@@ -12,4 +12,51 @@ or
 
 ### Check jest.config.js for testing configuration
 
-`npm test -- --coverage`
+`npm test -- --coverage`
+
+
+### Test Comparisons 
+
+`node index.js ./test/config1.properties ./test/config1.yaml`
+
+`node index.js ./test/config1.properties ./test/config2.yml`
+
+`node index.js ./test/config1.properties ./test/config2.properties`
+
+`node index.js ./test/config2.properties ./test/config2.yml`
+
+`node index.js ./test/config3.txt ./test/config3.yml2`
+
+`node index.js --format html --output report.html  ./test/config1.properties ./test/config2.yml`
+
+`node index.js -f markdown -o report.md ./test/config1.properties ./test/config2.yml`
+
+### NPM LINK Test
+
+`properties-comparator ./test/config1.properties ./test/config1.yaml`
+
+`properties-comparator ./test/config1.properties ./test/config2.yml`
+
+`properties-comparator ./test/config1.properties ./test/config2.properties`
+
+`properties-comparator ./test/config2.properties ./test/config2.yml`
+
+`properties-comparator ./test/config3.txt ./test/config3.yml2`
+
+`properties-comparator --format html --output report.html  ./test/config1.properties ./test/config2.yml`
+
+`properties-comparator -f markdown -o report.md ./test/config1.properties ./test/config2.yml`
+
+
+`properties-comparator ./test/config1.properties ./test/config2.yml ./test/config3.properties`
+
+`properties-comparator -v ./test/config1.properties ./test/config2.yml ./test/config3.properties`
+
+
+`properties-comparator -f html -o report.html ./test/config1.properties ./test/config1.yaml`
+
+`properties-comparator -f html -o report.html ./test/config1.properties ./test/config2.yml`
+
+`properties-comparator -f html -o report.html ./test/config1.properties ./test/config2.yml ./test/config3.properties`
+
+`properties-comparator -f markdown -o report.md ./test/config1.properties ./test/config2.yml ./test/config3.properties`

package/babel.config.js

@@ -0,0 +1,3 @@
+export default {
+  presets: ['@babel/preset-env'],
+};

package/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { compareFiles } from './index.js';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+// Get version from package.json
+let version = '1.0.0';
+
+try {
+  const packageJson = JSON.parse(readFileSync('./package.json', 'utf8'));
+  version = packageJson.version;
+} catch (err) {
+  // Use default version if package.json can't be read
+  console.warn(`Warning: Could not read version from package.json (${err.message}). Using default 1.0.0`);
+}
+
+// Check if no arguments were provided
+if (process.argv.length <= 2) {
+  console.log(`properties-comparator v${version}`);
+  console.log('Usage: properties-comparator [options] <file1> <file2> [file3...]');
+  process.exit(0);
+}
+
+program
+  .version(version)
+  .description('Compare properties between multiple files')
+  .option('-f, --format <format>', 'Output format: console, html, or markdown (default: console)')
+  .option('-o, --output <path>', 'Output file path for results')
+  .option('-v, --verbose', 'Show verbose output')
+  .arguments('<files...>')
+  .usage('[options] <file1> <file2> [file3...]')
+  .action((files, options) => {
+    if (files.length < 2) {
+      console.error('Error: At least two files are required for comparison');
+      program.help();
+      process.exit(1);
+    }
+
+    try {
+      // Resolve all file paths
+      const resolvedPaths = files.map(file => path.resolve(file));
+
+      // Prepare options for compareFiles
+      const comparisonOptions = {
+        format: options.format || 'console',
+        outputFile: options.output,
+        verbose: options.verbose // Pass verbose option to compareFiles
+      };
+
+      // Run the comparison
+      compareFiles(resolvedPaths, comparisonOptions);
+
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);