From 410bd373a8e0ae43bff425e66e4eba737298799f Mon Sep 17 00:00:00 2001
From: Chrilleweb <christian.munknissen@gmail.com>
Date: Sun, 8 Feb 2026 10:46:43 +0100
Subject: [PATCH 1/7] chore: JSDocs and moved interface

---
 src/config/types.ts                        | 13 +++++++++++--
 src/core/frameworks/frameworkDetector.ts   |  5 +++++
 src/core/security/exampleSecretDetector.ts |  8 +-------
 src/ui/scan/printExampleWarnings.ts        |  2 +-
 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/src/config/types.ts b/src/config/types.ts
index cdb6b0fc..840d86dd 100644
--- a/src/config/types.ts
+++ b/src/config/types.ts
@@ -1,6 +1,5 @@
 import { ALLOWED_CATEGORIES, GITIGNORE_ISSUES } from './constants.js';
 import { type SecretFinding } from '../core/security/secretDetectors.js';
-import { type ExampleSecretWarning } from '../core/security/exampleSecretDetector.js';
 
 /**
  * Supported frameworks
@@ -145,6 +144,16 @@ export interface EnvUsage {
  */
 export type VariableUsages = Record<string, EnvUsage[]>;
 
+/**
+ * Warning about secrets found in example files
+ */
+export interface ExampleSecretWarning {
+  key: string;
+  value: string;
+  reason: string;
+  severity: 'high' | 'medium' | 'low';
+}
+
 /**
  * Options for scanning the codebase
  */
@@ -349,4 +358,4 @@ export interface Discovery {
 export interface ComparisonFile {
   path: string;
   name: string;
-};
+}
diff --git a/src/core/frameworks/frameworkDetector.ts b/src/core/frameworks/frameworkDetector.ts
index 852ef224..c8681840 100644
--- a/src/core/frameworks/frameworkDetector.ts
+++ b/src/core/frameworks/frameworkDetector.ts
@@ -2,8 +2,13 @@ import fs from 'fs';
 import path from 'path';
 import type { DetectedFramework } from '../../config/types.js';
 
+/**
+ * Interface representing the detected framework and its version (if applicable)
+ */
 interface FrameworkDetection {
+  /** The detected framework (e.g., 'sveltekit', 'nextjs', or 'unknown') */
   framework: DetectedFramework;
+  /** The version of the detected framework (if available) */
   version?: string;
 }
 
diff --git a/src/core/security/exampleSecretDetector.ts b/src/core/security/exampleSecretDetector.ts
index e231bf88..005f2650 100644
--- a/src/core/security/exampleSecretDetector.ts
+++ b/src/core/security/exampleSecretDetector.ts
@@ -1,12 +1,6 @@
 import { PROVIDER_PATTERNS } from './secretDetectors.js';
 import { shannonEntropyNormalized } from './entropy.js';
-
-export interface ExampleSecretWarning {
-  key: string;
-  value: string;
-  reason: string;
-  severity: 'high' | 'medium' | 'low';
-}
+import type { ExampleSecretWarning } from '../../config/types.js';
 
 /**
  * Detects potential secrets in a .env.example file.
diff --git a/src/ui/scan/printExampleWarnings.ts b/src/ui/scan/printExampleWarnings.ts
index 4b1b5466..50ca3b19 100644
--- a/src/ui/scan/printExampleWarnings.ts
+++ b/src/ui/scan/printExampleWarnings.ts
@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import type { ExampleSecretWarning } from '../../core/security/exampleSecretDetector';
+import type { ExampleSecretWarning } from '../../config/types.js';
 
 /**
  * Prints example file secret warnings to the console.

From 7c163e982545dc29cf31d0cd47d640c436f54148 Mon Sep 17 00:00:00 2001
From: Chrilleweb <christian.munknissen@gmail.com>
Date: Sun, 8 Feb 2026 10:49:01 +0100
Subject: [PATCH 2/7] chore: JSDocs for secretseverity

---
 src/core/security/secretDetectors.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/core/security/secretDetectors.ts b/src/core/security/secretDetectors.ts
index 4bb385f3..6877877a 100644
--- a/src/core/security/secretDetectors.ts
+++ b/src/core/security/secretDetectors.ts
@@ -1,5 +1,8 @@
 import { shannonEntropyNormalized } from './entropy.js';
 
+/**
+ * Severity levels for detected secrets
+ */
 export type SecretSeverity = 'high' | 'medium' | 'low';
 
 /**

From aa3f6ea3a8450b5de20191e272dc73826154def5 Mon Sep 17 00:00:00 2001
From: Chrilleweb <christian.munknissen@gmail.com>
Date: Sun, 8 Feb 2026 10:53:02 +0100
Subject: [PATCH 3/7] chore: JSDocs for fixEnv

---
 src/core/fixEnv.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/core/fixEnv.ts b/src/core/fixEnv.ts
index efbf0599..5dc9e640 100644
--- a/src/core/fixEnv.ts
+++ b/src/core/fixEnv.ts
@@ -7,9 +7,13 @@ import { DEFAULT_GITIGNORE_ENV_PATTERNS } from '../config/constants.js';
  * Options for applying fixes to environment files
  */
 interface ApplyFixesOptions {
+  /** Path to the .env file to fix */
   envPath: string;
+  /** List of missing keys to add to the .env file */
   missingKeys: string[];
+  /** List of duplicate keys to remove from the .env file (keep last occurrence) */
   duplicateKeys: string[];
+  /** Whether to ensure .env is ignored in .gitignore (if in a git repo) */
   ensureGitignore?: boolean;
 }
 
@@ -17,8 +21,11 @@ interface ApplyFixesOptions {
  * Result of applying fixes to environment files
  */
 interface FixResult {
+  /** List of removed duplicate keys */
   removedDuplicates: string[];
+  /** List of added environment variables */
   addedEnv: string[];
+  /** Whether the .gitignore file was updated */
   gitignoreUpdated: boolean;
 }
 

From 0ef657d071fe205589cecc8eed85b0f0418a3121 Mon Sep 17 00:00:00 2001
From: Chrilleweb <christian.munknissen@gmail.com>
Date: Sun, 8 Feb 2026 11:00:41 +0100
Subject: [PATCH 4/7] chore: JSDocs

---
 src/services/envDiscovery.ts  |  3 +++
 src/ui/compare/printPrompt.ts | 12 +++++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/src/services/envDiscovery.ts b/src/services/envDiscovery.ts
index 28d00673..46e3cd37 100644
--- a/src/services/envDiscovery.ts
+++ b/src/services/envDiscovery.ts
@@ -7,8 +7,11 @@ import { DEFAULT_ENV_FILE, DEFAULT_EXAMPLE_FILE } from '../config/constants.js';
  * Arguments for the discoverEnvFiles function.
  */
 interface DiscoverEnvFilesArgs {
+  /** The current working directory to search for environment files */
   cwd: string;
+  /** The value of the --env flag if provided, otherwise null */
   envFlag: string | null;
+  /** The value of the --example flag if provided, otherwise null */
   exampleFlag: string | null;
 }
 
diff --git a/src/ui/compare/printPrompt.ts b/src/ui/compare/printPrompt.ts
index 9eeb0e13..850c50c0 100644
--- a/src/ui/compare/printPrompt.ts
+++ b/src/ui/compare/printPrompt.ts
@@ -2,7 +2,17 @@ import chalk from 'chalk';
 import path from 'path';
 
 /**
- * Prompt messages for user interactions.
+ * User interface messages for environment file operations.
+ *
+ * @description Provides formatted console output for various environment file
+ * comparison and creation scenarios. All methods output styled messages using
+ * chalk for enhanced readability.
+ *
+ * @property {Function} noEnvFound - Displays warning when no environment files are detected
+ * @property {Function} missingEnv - Displays warning for a specific missing environment file
+ * @property {Function} skipCreation - Notifies user that file creation was skipped
+ * @property {Function} envCreated - Confirms successful creation of .env file from example
+ * @property {Function} exampleCreated - Confirms successful creation of .env.example file from .env
  */
 export const printPrompt = {
   noEnvFound() {

From 83bef565dd402015b8f195e09424011a9f5c647d Mon Sep 17 00:00:00 2001
From: Chrilleweb <christian.munknissen@gmail.com>
Date: Sun, 8 Feb 2026 11:02:44 +0100
Subject: [PATCH 5/7] chore: JSDocs

---
 src/ui/compare/printStats.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/ui/compare/printStats.ts b/src/ui/compare/printStats.ts
index ba3ee7d5..3d30290c 100644
--- a/src/ui/compare/printStats.ts
+++ b/src/ui/compare/printStats.ts
@@ -1,11 +1,19 @@
 import chalk from 'chalk';
 import type { Filtered } from '../../config/types.js';
 
+/**
+ * Interface representing the comparison statistics between two environment files
+ */
 interface CompareStats {
+  /** Total number of keys in the environment file */
   envCount: number;
+  /** Total number of keys in the example file */
   exampleCount: number;
+  /** Number of keys that are shared between the environment and example files */
   sharedCount: number;
+  /** Number of duplicate keys found in either file */
   duplicateCount: number; // sum of (count - 1)
+  /** Number of keys that have mismatched values between the two files (if value checking is enabled) */
   valueMismatchCount: number;
 }
 

From 7f502a220a3f3afc5aae257e4ec7b06109cadc51 Mon Sep 17 00:00:00 2001
From: Chrilleweb <christian.munknissen@gmail.com>
Date: Sun, 8 Feb 2026 12:36:31 +0100
Subject: [PATCH 6/7] chore: JSDocs

---
 src/ui/scan/printFrameworkWarnings.ts | 3 +++
 src/ui/scan/printProgress.ts          | 8 ++++++++
 src/ui/scan/printStats.ts             | 8 ++++++++
 src/ui/shared/printAutoFix.ts         | 5 +++++
 src/ui/shared/printGitignore.ts       | 6 ++++++
 src/ui/shared/printStrictModeError.ts | 3 +++
 6 files changed, 33 insertions(+)

diff --git a/src/ui/scan/printFrameworkWarnings.ts b/src/ui/scan/printFrameworkWarnings.ts
index 8fde06ec..9a75d939 100644
--- a/src/ui/scan/printFrameworkWarnings.ts
+++ b/src/ui/scan/printFrameworkWarnings.ts
@@ -4,6 +4,9 @@ import type {
   DetectedFramework,
 } from '../../config/types.js';
 
+/**
+ * Labels for detected frameworks to display in warnings
+ */
 const FRAMEWORK_LABELS: Record<DetectedFramework, string> = {
   nextjs: 'Next.js',
   sveltekit: 'SvelteKit',
diff --git a/src/ui/scan/printProgress.ts b/src/ui/scan/printProgress.ts
index a05fbcc1..9b0933d4 100644
--- a/src/ui/scan/printProgress.ts
+++ b/src/ui/scan/printProgress.ts
@@ -1,12 +1,20 @@
 import chalk from 'chalk';
 
+/**
+ * Options for printing progress in the console.
+ */
 interface ProgressOptions {
+  /** Whether to output in JSON format (if true, progress will not be printed) */
   isJson: boolean;
+  /** The current progress count (e.g., number of files scanned) */
   current: number;
+  /** The total count for completion (e.g., total number of files to scan) */
   total: number;
+  /** Optional label to display alongside the progress bar (default: 'Scanning') */
   label?: string;
 }
 
+/** Internal flag to track if the progress bar has been rendered at least once */
 let hasRendered = false;
 
 /**
diff --git a/src/ui/scan/printStats.ts b/src/ui/scan/printStats.ts
index 48fe87c4..c9ce5f61 100644
--- a/src/ui/scan/printStats.ts
+++ b/src/ui/scan/printStats.ts
@@ -1,10 +1,18 @@
 import chalk from 'chalk';
 
+/**
+ * Statistics for codebase scanning
+ */
 interface ScanStats {
+  /** Total number of files scanned during the scan process */
   filesScanned: number;
+  /** Total number of environment variable references found across all scanned files */
   totalUsages: number;
+  /** Total number of unique environment variables referenced across all scanned files */
   uniqueVariables: number;
+  /** Total number of warnings found during the scan process */
   warningsCount: number;
+  /** Total duration of the scan process in seconds */
   duration: number;
 }
 
diff --git a/src/ui/shared/printAutoFix.ts b/src/ui/shared/printAutoFix.ts
index 10048643..3ebecd25 100644
--- a/src/ui/shared/printAutoFix.ts
+++ b/src/ui/shared/printAutoFix.ts
@@ -1,7 +1,12 @@
 import chalk from 'chalk';
 
+/**
+ * Result of the auto-fix operation to be printed to the user.
+ */
 interface AutoFixResult {
+  /** List of duplicate keys removed from the environment file */
   removedDuplicates: string[];
+  /** List of missing keys added to the environment file */
   addedEnv: string[];
 }
 
diff --git a/src/ui/shared/printGitignore.ts b/src/ui/shared/printGitignore.ts
index db838e19..e0d37752 100644
--- a/src/ui/shared/printGitignore.ts
+++ b/src/ui/shared/printGitignore.ts
@@ -2,9 +2,15 @@ import chalk from 'chalk';
 import type { GitignoreIssue } from '../../config/types.js';
 import { GITIGNORE_ISSUES } from '../../config/constants.js';
 
+/**
+ * Options for printing gitignore warnings to the user.
+ */
 interface GitignoreWarningOptions {
+  /** The name of the environment file */
   envFile: string;
+  /** The reason for the gitignore warning */
   reason: GitignoreIssue;
+  /** Optional custom log function (defaults to console.log) */
   log?: (msg: string) => void;
 }
 
diff --git a/src/ui/shared/printStrictModeError.ts b/src/ui/shared/printStrictModeError.ts
index a91162d1..263ea6eb 100644
--- a/src/ui/shared/printStrictModeError.ts
+++ b/src/ui/shared/printStrictModeError.ts
@@ -1,5 +1,8 @@
 import chalk from 'chalk';
 
+/**
+ * Context for strict mode warnings to be printed to the user.
+ */
 interface StrictModeContext {
   unused: number;
   duplicatesEnv: number;

From eec323bd122f082f7b1fe399a035c2f3bd898fad Mon Sep 17 00:00:00 2001
From: Chrilleweb <christian.munknissen@gmail.com>
Date: Sun, 8 Feb 2026 12:42:01 +0100
Subject: [PATCH 7/7] chore: removed unsued prop

---
 src/commands/compare.ts            | 1 -
 src/services/printScanResult.ts    | 1 -
 src/ui/shared/printAutoFix.ts      | 3 +--
 test/unit/commands/compare.test.ts | 1 -
 4 files changed, 1 insertion(+), 5 deletions(-)

diff --git a/src/commands/compare.ts b/src/commands/compare.ts
index cfc3d589..eb616380 100644
--- a/src/commands/compare.ts
+++ b/src/commands/compare.ts
@@ -198,7 +198,6 @@ export async function compareMany(
         changed,
         result,
         envName,
-        exampleName,
         opts.json ?? false,
         hasGitignoreIssue,
       );
diff --git a/src/services/printScanResult.ts b/src/services/printScanResult.ts
index d3a363d9..b2f17986 100644
--- a/src/services/printScanResult.ts
+++ b/src/services/printScanResult.ts
@@ -205,7 +205,6 @@ export function printScanResult(
         addedEnv: fixContext.addedEnv,
       },
       comparedAgainst || DEFAULT_ENV_FILE,
-      opts.examplePath ? path.basename(opts.examplePath) : 'example file',
       isJson,
       fixContext.gitignoreUpdated,
     );
diff --git a/src/ui/shared/printAutoFix.ts b/src/ui/shared/printAutoFix.ts
index 3ebecd25..c3efad9a 100644
--- a/src/ui/shared/printAutoFix.ts
+++ b/src/ui/shared/printAutoFix.ts
@@ -15,15 +15,14 @@ interface AutoFixResult {
  * @param changed - Whether any changes were made.
  * @param result - The result of the auto-fix operation.
  * @param envName - The name of the environment file.
- * @param exampleName - The name of the example file.
  * @param json - Whether to output in JSON format.
+ * @param gitignoreUpdated - Whether the .gitignore file was updated to ignore the environment file.
  * @returns void
  */
 export function printAutoFix(
   changed: boolean,
   result: AutoFixResult,
   envName: string,
-  exampleName: string,
   json: boolean,
   gitignoreUpdated: boolean,
 ): void {
diff --git a/test/unit/commands/compare.test.ts b/test/unit/commands/compare.test.ts
index bb8fe145..7c4a13ce 100644
--- a/test/unit/commands/compare.test.ts
+++ b/test/unit/commands/compare.test.ts
@@ -387,7 +387,6 @@ describe('compareMany', () => {
       true,
       expect.any(Object),
       '.env',
-      '.env.example',
       false,
       false,
     );