🧠💻 Codebase Context Lint

🔎 Overview

This is a CLI linter for validating Codebase Context Specification (CCS) files, including .context.md, .context.yaml, .context.json, .contextdocs.md, and .contextignore files. The Codebase Context Specification is a convention for documenting your code to enhance understanding for both AI and human developers.

Codebase Context Editor

To help you get started with creating context files for your project, we've developed the Codebase Context Editor. This tool simplifies the process of generating .context.md, .contextdocs.md, and .contextignore files that adhere to the Codebase Context Specification.

Get Started with the Codebase Context Editor

The Codebase Context Editor provides an intuitive interface for:

• Creating and editing context files
• Viewing and copying AI prompts for context generation
• Validating your context files against the specification

Whether you're new to the Codebase Context Specification or an experienced user, the editor can significantly streamline your workflow.

📚 What is Codebase Context?

Codebase Context is a convention similar to .env and .editorconfig systems, but focused on documenting your code for both AI and humans. Just as .env files manage environment variables and .editorconfig ensures consistent coding styles, CCS files provide a standardized way to capture and communicate the context of your codebase.

This convention allows developers to:

1. Document high-level architecture and design decisions
2. Explain project-specific conventions and patterns
3. Highlight important relationships between different parts of the codebase
4. Provide context that might not be immediately apparent from the code itself

By adopting this convention, teams can ensure that both human developers and AI assistants have access to crucial contextual information, leading to better code understanding, more accurate suggestions, and improved overall development efficiency.

For more detailed information about the Codebase Context Specification, please refer to the main repository and the full specification.

Supported Node.js Versions

This linter supports the following Node.js versions:

• Node.js 18.x
• Node.js 20.x
• Node.js 22.x

We recommend using the latest LTS (Long Term Support) version of Node.js for optimal performance and security.

�📦 Installation

You can install the linter globally using npm:

npm install -g codebase-context-lint

Note: Make sure you're using a supported Node.js version (18.x, 20.x, or 22.x) when installing and running the linter.

🚀 Usage

After installation, you can use the linter from the command line:

codebase-context-lint <directory_to_lint>

Replace <directory_to_lint> with the path to the directory containing your Codebase Context Specification files.

✨ Features

• 🔍 Validates the structure and content of .context.md, .context.yaml, and .context.json files
• ✅ Checks for required fields and sections
• 📄 Verifies the format of .contextdocs.md files
• 🚫 Supports and validates .contextignore files for excluding specific files or directories
• 💬 Provides detailed error messages and warnings

📁 .contextignore Files

.contextignore files allow you to specify patterns for files and directories that should be ignored by the Codebase Context Lint. This is useful for excluding generated files, dependencies, or any other content that doesn't need context documentation.

How to use .contextignore

1. Create a file named .contextignore in any directory of your project.
2. Add patterns to the file, one per line. These patterns follow the same rules as .gitignore files.
3. The linter will respect these ignore patterns when processing files in that directory and its subdirectories.

Example .contextignore file:

# Ignore node_modules directory
node_modules/

# Ignore all .log files
*.log

# Ignore a specific file
path/to/specific/file.js

# Ignore all files in a specific directory
path/to/ignore/*

The linter will validate the syntax of your .contextignore files and warn about any problematic patterns, such as attempting to ignore critical context files.

🤖 Using with AI Assistants

While this linter provides automated validation of CCS files, you can also use the Codebase Context Specification with AI assistants without any specific tooling. The CODING-ASSISTANT-PROMPT.md file in the main repository provides guidelines for AI assistants to understand and use the Codebase Context Specification.

To use the Codebase Context Specification with an AI assistant:

1. Include the content of CODING-ASSISTANT-PROMPT.md in your prompt to the AI assistant.
2. Ask the AI to analyze your project's context files based on these guidelines.
3. The AI will be able to provide more accurate and context-aware responses by following the instructions in the prompt.

Note that while this approach allows for immediate use of the specification, some features like .contextignore are best implemented by tooling (such as this linter) for more robust and consistent application.

🛠️ Development

To contribute to this project:

1. Clone the repository:

   git clone https://github.com/Agentic-Insights/codebase-context-spec.git
   cd codebase-context-spec/linters/typescript

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. To test the CLI locally, you can use:

   npm link

   This will create a symlink to your local development version of the package.

5. Create your feature branch (git checkout -b feature/AmazingFeature)

6. Commit your changes (git commit -m 'Add some AmazingFeature')

7. Push to the branch (git push origin feature/AmazingFeature)

8. Open a Pull Request

🔄 Recent Updates

We've recently updated our dependencies to address security vulnerabilities and improve compatibility with different Node.js versions. If you encounter any issues after updating, please report them in our GitHub issues.

📖 Learn More

For a deeper dive into the Codebase Context Specification, check out this SubStack article by Vaskin, the author of the specification.

📄 License

This project is licensed under the MIT License.

🔗 Related Links

• Codebase Context Specification Repository
• Full Specification (CODEBASE-CONTEXT.md)
• NPM Package (codebase-context-lint)
• AI Assistant Prompt (CODING-ASSISTANT-PROMPT.md)