chore: JSDocs and moved interface

src/commands/compare.ts

@@ -198,7 +198,6 @@ export async function compareMany(
         changed,
         result,
         envName,
-        exampleName,
         opts.json ?? false,
         hasGitignoreIssue,
       );

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;
-};
+}

src/core/fixEnv.ts

@@ -7,18 +7,25 @@ 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;
 }
 
 /**
  * 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;
 }
 

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;
 }
 

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.

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';
 
 /**

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;
 }
 

src/services/printScanResult.ts

@@ -1,4 +1,4 @@
 import path from 'path';
 import { checkGitignoreStatus } from './git.js';
 import { printGitignoreWarning } from '../ui/shared/printGitignore.js';
 import type {
@@ -205,7 +205,6 @@
         addedEnv: fixContext.addedEnv,
       },
       comparedAgainst || DEFAULT_ENV_FILE,
-      opts.examplePath ? path.basename(opts.examplePath) : 'example file',
       isJson,
       fixContext.gitignoreUpdated,
     );

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() {

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;
 }
 

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.

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',

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;
 
 /**

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;
 }
 

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[];
 }
 
@@ -10,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 {

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;
 }
 

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;

test/unit/commands/compare.test.ts

@@ -387,7 +387,6 @@ describe('compareMany', () => {
       true,
       expect.any(Object),
       '.env',
-      '.env.example',
       false,
       false,
     );