unqommented

A Node.js utility that quickly identifies files with uncommented code in your codebase. Designed for developers who want to efficiently tell LLMs exactly which files need comments added.

Perfect for LLM workflows: Instead of manually hunting through files, get a precise list of uncommented files to feed directly to ChatGPT, Claude, or other AI assistants for bulk commenting.

Installation

npm install unqommented

Requires Node.js >=14.14.0.

Dependencies

This project relies on several npm packages:

• fast-glob for file matching
• lodash for utility functions
• Node's built-in crypto.randomBytes for random ID generation
• validator for common validation helpers
• yargs for command-line argument parsing
• eslint and eslint-plugin-jsdoc for linting
• madge for dependency graph analysis
• qerrors for consistent error logging
• qtests for test output
• repomix for repository metrics

Quick Start

Unqommented runs solely as a CLI tool or Node.js library and does not expose any HTTP endpoints or server component.

As a Node.js Module

(async () => {
  const { findUncommentedFiles } = require('unqommented');

  // Scan a directory for files with uncommented code
  const { uncommentedFiles, errors } = await findUncommentedFiles('./src');
  console.log('Uncommented files:', uncommentedFiles); // ["src/app.js","src/utils.js","src/components/Button.js"]
  console.log('Errors:', errors); // [] if no errors

  // Check if any files have uncommented code
  if (uncommentedFiles.length) {
    console.log('Files with uncommented code found:', uncommentedFiles);
  } else {
    console.log('All files are properly commented!');
  }

  if (errors.length) {
    console.log('Errors encountered:', errors);
  }
})();

The call to findUncommentedFiles returns an object with uncommentedFiles and errors, allowing you to review both the files that need comments and any issues encountered during scanning.

Command Line Interface

# Check current directory
unqommented

# Check specific directory
 unqommented ./src

# You can also use the aliases `uncommented` or `check-uncommented`
uncommented ./src
check-uncommented ./src

What It Does

unqommented scans your codebase to identify files containing executable code that is not commented out. It is designed to be highly accurate, with logic that:

• Streams files line-by-line to efficiently handle large files without consuming excessive memory.
• Ignores commented code, including single-line (//), multi-line (/* ... */), and shebangs (#!).
• Handles language-specific comments, such as Python's hash (#) comments.
• Strips quoted strings before checking for comments to avoid false positives from comment-like text in strings.
• Excludes non-executable lines, such as those containing only closing brackets or braces.

Example

Given these files:

fully-commented.js:

// This file is fully commented
const message = "Hello World"; // const message = "Hello World";
// console.log(message);

mixed-content.js:

// This file has mixed content
const message = "Hello World";
// ^ this line has uncommented code;

unqommented will only flag mixed-content.js because it contains uncommented code.

Supported File Types

• JavaScript: .js, .jsx
• TypeScript: .ts, .tsx
• Java: .java
• C/C++: .c, .cpp
• C#: .cs
• Python: .py

API Reference

findUncommentedFiles(baseDir, outputStream)

Recursively scans a directory for files with uncommented code. File checks run concurrently using the limit defined in config/localVars.js, greatly reducing scan time on large projects.

Parameters:

• baseDir (string): Path to the directory to scan
• outputStream (Writable, optional): When provided, file paths are written to this stream as they are discovered. This allows streaming results without waiting for the full scan.

Returns:

• { uncommentedFiles, errors } (object):
  • uncommentedFiles (string[]): Array of file paths with uncommented code
  • errors (Array): Details of any errors encountered while scanning

Throws:

• Error if baseDir is not a string
• Error if directory doesn't exist
• Error if path is not a directory

Example:

(async () => {
  const { findUncommentedFiles } = require('unqommented');

  try {
    const { uncommentedFiles } = await findUncommentedFiles('./my-project');
    if (uncommentedFiles.length) {
      console.log('Uncommented files:', uncommentedFiles);
    } else {
      console.log('No uncommented files found');
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

Example with stream:

(async () => {
  const { findUncommentedFiles } = require('unqommented');

  await findUncommentedFiles('./my-project', process.stdout); // paths printed as they are found
})();

Bonus Utilities

unqommented also includes these additional utility functions:

formatString(input)

const { formatString } = require('unqommented');
console.log(formatString('  hello world  ')); // "Hello world"

validateEmail(email)

const { validateEmail } = require('unqommented');
console.log(validateEmail('[email protected]')); // true

generateId(length)

const { generateId } = require('unqommented');
console.log(generateId(8)); // "a1b2c3d4" (random hex ID)

Use Cases

Primary: LLM-Assisted Code Commenting

• Bulk Documentation: Get a list of files to send to ChatGPT/Claude with "Add comments to these files: [file list]"
• Selective Commenting: Focus LLM attention only on files that actually need comments
• Efficient Workflows: Skip manually scanning hundreds of files - let unqommented find the uncommented ones

Additional Uses

• Code Reviews: Ensure all code is properly documented
• CI/CD Integration: Fail builds if uncommented code is found
• Legacy Code Cleanup: Identify files that need commenting
• Documentation Standards: Maintain consistent commenting practices

Example LLM Workflow

# Find uncommented files
unqommented ./src
# Output:
# src/utils.js
# src/api/client.js
# src/components/Button.js

# Copy this list and tell your LLM:
# "Please add comprehensive comments to these files:
# src/utils.js
# src/api/client.js
# src/components/Button.js"

Testing

Testing focuses on CLI interactions and library functions. Run the test suite:

npm test

Contributing

1. Fork the repository
2. Create your feature branch
3. Add tests for your changes
4. Ensure all tests pass
5. Submit a pull request

License

MIT

Why "unqommented"?

The name combines "un" (not) + "qommented" (a playful take on "commented") to create a unique, memorable name for this uncommented code detection tool. Perfect for the age of AI-assisted development where finding uncommented code is the first step to getting LLMs to document your codebase efficiently.