unqommented/README.md

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.

# 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

```bash
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

```javascript
(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

```bash
# 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:**
```javascript
// This file is fully commented
const message = "Hello World"; // const message = "Hello World";
// console.log(message);
```

**mixed-content.js:**
```javascript
// 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:**
```javascript
(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:**
```javascript
(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)
```javascript
const { formatString } = require('unqommented');
console.log(formatString('  hello world  ')); // "Hello world"
```

### validateEmail(email)
```javascript
const { validateEmail } = require('unqommented');
console.log(validateEmail('test@example.com')); // true
```

### generateId(length)
```javascript
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
```bash
# 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:

```bash
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.