Skip to content
This repository was archived by the owner on Oct 10, 2025. It is now read-only.

Commit 56fac43

Browse files
killerappkillerapp
authored
fix: update spec general parameter lists and validation checks
fix: get the linter recursing and generating coverage & pass / fail
2 parents d2092b3 + af6c288 commit 56fac43

22 files changed

+857
-582
lines changed

‎.context.md‎

Lines changed: 57 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,61 @@
11
---
2-
projectName: Codebase Context Specification
3-
description: A specification and tools for embedding rich contextual information within codebases to enhance AI-assisted development
4-
version: 1.0-preview
5-
mainTechnologies:
6-
- Markdown
7-
- YAML
8-
- JSON
9-
- TypeScript
2+
module-name: MyAwesomeProject
3+
related-modules:
4+
- ./linters/typescript
5+
version: 1.0.0
6+
description: A revolutionary web application
7+
diagrams:
8+
- img/codebase-diagram.mermaid
9+
- img/codebase-diagram2.png
10+
technologies:
11+
- Node.js
12+
- React
13+
- MongoDB
1014
conventions:
11-
- Use .context.md files for structured (frontmatter) and general context
12-
- Use .context.yaml or .context.json for structured data when needed
13-
- Follow the Codebase Context Specification
14-
- Implement linters for various programming languages
15+
- Use consistent naming conventions within each file type
16+
- Each function should have a single responsibility
17+
directives:
18+
- Focus on performance optimizations
19+
- Suggest ways to improve error handling
20+
architecture:
21+
style: Microservices
22+
components:
23+
- Auth Service
24+
- User Service
25+
- Data Processing Service
26+
data-flow:
27+
- Client -> API Gateway -> Services -> Database
28+
development:
29+
setup-steps:
30+
- Install Node.js v14+
31+
- Run `npm install` in each service directory
32+
- Set up MongoDB instance
33+
build-command: npm run build
34+
test-command: npm test
35+
business-requirements:
36+
key-features:
37+
- User authentication
38+
- Real-time data processing
39+
- Mobile-responsive UI
40+
target-audience: Small to medium-sized businesses
41+
success-metrics:
42+
- User adoption rate
43+
- System response time
44+
- Data processing accuracy
45+
quality-assurance:
46+
testing-frameworks:
47+
- Jest
48+
- Cypress
49+
coverage-threshold: 80%
50+
performance-benchmarks:
51+
- API response time < 200ms
52+
- Database query time < 100ms
53+
deployment:
54+
platform: AWS
55+
cicd-pipeline: GitHub Actions
56+
staging-environment: dev.myawesomeproject.com
57+
production-environment: myawesomeproject.com
58+
1559
---
1660

1761
# Codebase Context Specification
@@ -27,7 +71,7 @@ This project defines and implements the Codebase Context Specification, a standa
2771

2872
## Key Components
2973

30-
1. Specification: Defined in CODEBASE-CONTEXT.md
74+
1. Specification: Defined in (CODEBASE-CONTEXT.md)
3175
2. Linter Implementations:
3276
- TypeScript: `linters/typescript/src/context_linter.ts`
3377
- Python: (To be implemented)

‎.contextdocs.md‎

Lines changed: 58 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,60 @@
1-
# Project Context Documentation
2-
3-
## Overview
4-
This document provides context for the codebase-context-spec project, which aims to define and implement a specification for capturing and utilizing codebase context in software development.
5-
6-
## Project Structure
7-
- `.context.md`: Contains project-wide context information
8-
- `README.md`: Project introduction and general information
9-
- `CODEBASE-CONTEXT.md`: Detailed specification for codebase context
10-
- `img/`: Directory for project images
11-
- `linters/`: Directory containing linter implementations
12-
- `python/`: Python linter implementation
13-
- `typescript/`: TypeScript linter implementation
14-
15-
## Key Components
16-
1. **Context Specification**: Defined in `CODEBASE-CONTEXT.md`, this outlines the structure and format for capturing codebase context.
17-
18-
2. **Linter Implementations**:
19-
- Python linter in `linters/python/`
20-
- TypeScript linter in `linters/typescript/`
21-
22-
3. **Visual Representation**: `img/codebase-context.png` provides a visual overview of the codebase context concept.
23-
24-
## Development Guidelines
25-
- Follow the specification outlined in `CODEBASE-CONTEXT.md` when implementing context-aware features.
26-
- Ensure all linter implementations adhere to the same core principles while respecting language-specific best practices.
27-
- Keep `.context.md` files updated in each directory to maintain accurate context information.
28-
29-
## Tools and Technologies
30-
- TypeScript for the TypeScript linter implementation
31-
- Python for the Python linter implementation
32-
- Markdown for documentation
33-
34-
## Future Directions
35-
- Implement additional language-specific linters
36-
- Develop integration plugins for popular IDEs
37-
- Create a standardized API for context-aware tool interactions
38-
39-
## Contributing
40-
Refer to the project's contribution guidelines (if available) for information on how to contribute to this project.
41-
1+
---
2+
contextdocs:
3+
- name: TypeScript
4+
relationship: Main language for linter implementation
5+
resources:
6+
- Official Documentation: https://www.typescriptlang.org/docs/
7+
- TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/intro.html
8+
- TypeScript Deep Dive: https://basarat.gitbook.io/typescript/
9+
10+
- name: Node.js
11+
relationship: Runtime environment for TypeScript linter
12+
resources:
13+
- Official Documentation: https://nodejs.org/en/docs/
14+
- Getting Started Guide: https://nodejs.org/en/docs/guides/getting-started-guide/
15+
- Node.js Best Practices: https://github.com/goldbergyoni/nodebestpractices
16+
17+
- name: Jest
18+
relationship: Testing framework for TypeScript linter
19+
resources:
20+
- Official Documentation: https://jestjs.io/docs/getting-started
21+
- Testing TypeScript with Jest: https://basarat.gitbook.io/typescript/intro-1/jest
22+
- Jest with TypeScript in Node.js: https://stackoverflow.com/questions/54822273/how-to-use-jest-with-typescript-in-node-js
23+
24+
- name: ESLint
25+
relationship: Linting tool used as a reference for our custom linter
26+
resources:
27+
- Official Documentation: https://eslint.org/docs/user-guide/getting-started
28+
- ESLint with TypeScript: https://khalilstemmler.com/blogs/typescript/eslint-for-typescript/
29+
- Configuring ESLint for TypeScript: https://www.robertcooper.me/using-eslint-and-prettier-in-a-typescript-project
30+
31+
- name: YAML
32+
relationship: Used in .context.yaml/.context.yml files
33+
resources:
34+
- Official Specification: https://yaml.org/spec/1.2.2/
35+
- Learn YAML in Y minutes: https://learnxinyminutes.com/docs/yaml/
36+
- Common YAML Gotchas: https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-over-multiple-lines
37+
38+
- name: JSON
39+
relationship: Used in .context.json files
40+
resources:
41+
- Official Specification: https://www.json.org/json-en.html
42+
- JSON Schema: https://json-schema.org/learn/getting-started-step-by-step
43+
- Working with JSON in TypeScript: https://blog.logrocket.com/working-with-json-typescript/
44+
45+
- name: Markdown
46+
relationship: Used for documentation and .context.md files
47+
resources:
48+
- Official Guide: https://www.markdownguide.org/
49+
- GitHub Flavored Markdown Spec: https://github.github.com/gfm/
50+
- Mastering Markdown: https://guides.github.com/features/mastering-markdown/
51+
52+
- name: Python
53+
relationship: Used for Python version of the linter
54+
resources:
55+
- Official Documentation: https://docs.python.org/3/
56+
- Real Python Tutorials: https://realpython.com/
57+
- Python Linting Best Practices: https://stackoverflow.com/questions/1428872/pylint-pep8-and-pyflakes
4258
---
4359

44-
This context documentation provides a high-level overview of the project. For more detailed information, please refer to specific `.context.md` files in each directory and the `CODEBASE-CONTEXT.md` specification.
60+
This file contains a list of external dependencies and libraries used in the Codebase Context Specification project. The YAML front-matter above provides structured data about each dependency, including its relationship to the project and links to relevant resources. These resources include official documentation, articles, blogs, and Stack Overflow posts. This structure allows for easy parsing by automated tools while maintaining readability for developers.

‎CODEBASE-CONTEXT.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,15 @@ Date: 2024-08-31
55

66
## 1. Overview
77

8-
The AI Context Convention is a standardized method for embedding rich contextual information within codebases to enhance AI-assisted development. This specification outlines a flexible, language-agnostic approach to providing both structured and unstructured context at various levels of a project, catering to the needs of different team roles.
8+
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.
9+
10+
This convention allows developers to:
11+
12+
1. Document high-level architecture and design decisions
13+
2. Explain project-specific conventions and patterns
14+
3. Highlight important relationships between different parts of the codebase
15+
4. Provide context that might not be immediately apparent from the code itself
16+
5. 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.
917

1018
## 2. Key Principles
1119

@@ -456,8 +464,8 @@ documentation:
456464

457465
## 9. Conclusion
458466

459-
The AI Context Convention provides a flexible, standardized approach to enriching codebases with contextual information for AI models. By adopting this convention and including role-specific information, development teams can enhance AI-assisted workflows, improving code quality and development efficiency across projects of any scale or complexity. The addition of role-specific guidelines and consistent naming conventions ensures that AI models have access to comprehensive, relevant, and well-structured information tailored to different aspects of the software development lifecycle.
467+
The Codebase Context Specification provides a flexible, standardized approach to enriching codebases with contextual information for AI models. By adopting this convention and including role-specific information, development teams can enhance AI-assisted workflows, improving code quality and development efficiency across projects of any scale or complexity. The addition of role-specific guidelines and consistent naming conventions ensures that AI models have access to comprehensive, relevant, and well-structured information tailored to different aspects of the software development lifecycle.
460468

461469
## 10. TypeScript Linter Implementation
462470

463-
For details on the TypeScript implementation of the linter for validating AI Context Convention files, please refer to the [TypeScript Linter README](linters/typescript/README.md).
471+
For details on the TypeScript implementation of the linter for validating Codebase Context Specification files, please refer to the [TypeScript Linter README](linters/typescript/README.md).

‎img/codebase-diagram.mermaid‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
graph TD
2+
subgraph "Codebase Context Specification"
3+
Root[Root Directory]
4+
Spec[Specification CODEBASE-CONTEXT.md]
5+
MainDoc[Main Documentation README.md]
6+
Linters[Linters Directory]
7+
TypeScript[TypeScript Linter]
8+
Python[Python Linter]
9+
10+
Root --> Spec
11+
Root --> MainDoc
12+
Root --> Linters
13+
Linters --> TypeScript
14+
Linters --> Python
15+
end
16+
17+
subgraph "TypeScript Linter"
18+
TSLinter[context_linter.ts]
19+
TSTests[Tests]
20+
TSREADME[TypeScript README]
21+
22+
TypeScript --> TSLinter
23+
TypeScript --> TSTests
24+
TypeScript --> TSREADME
25+
end
26+
27+

img/codebase-context.png renamed to img/codebase-diagram2.png

File renamed without changes.

‎linters/.context.md‎

Lines changed: 49 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,57 @@
11
---
2-
directoryName: linters
3-
description: Contains linting tools for validating AI Context Convention files
4-
languages:
2+
module-name: Codebase Context Specification Linters
3+
related-modules:
4+
- ../examples
5+
version: 1.0.0
6+
description: Contains linting tools for validating Codebase Context Specification files
7+
diagrams: []
8+
technologies:
59
- Python
610
- TypeScript
11+
conventions:
12+
- Follow language-specific best practices
13+
- Adhere to Codebase Context Specification
14+
directives:
15+
- Ensure consistency between different language implementations
16+
- Write clear, well-documented code
17+
architecture:
18+
style: Multi-language
19+
components:
20+
- Python linter
21+
- TypeScript linter
22+
data-flow:
23+
- Input files -> Language-specific linter -> Validation results
24+
development:
25+
setup-steps:
26+
- Clone the repository
27+
- Follow language-specific setup instructions in each subdirectory
28+
build-command: See individual linter directories
29+
test-command: See individual linter directories
30+
business-requirements:
31+
key-features:
32+
- Validate structure of context files
33+
- Ensure required fields are present
34+
- Check for proper YAML frontmatter in Markdown files
35+
target-audience: Developers using the Codebase Context Specification
36+
success-metrics:
37+
- Consistency of linting results across languages
38+
- Adoption rate among project contributors
39+
quality-assurance:
40+
testing-frameworks:
41+
- Language-specific testing frameworks (see subdirectories)
42+
coverage-threshold: 90%
43+
performance-benchmarks:
44+
- Linting speed for various file sizes and complexities
45+
deployment:
46+
platform: GitHub
47+
cicd-pipeline: GitHub Actions
48+
staging-environment: N/A
49+
production-environment: GitHub Releases
750
---
851

952
# Linters Directory
1053

11-
This directory contains linting tools for validating AI Context Convention files in different programming languages. The linters ensure that context files adhere to the specification and provide consistent, high-quality contextual information for AI-assisted development.
54+
This directory contains linting tools for validating Codebase Context Specification files in different programming languages. The linters ensure that context files adhere to the specification and provide consistent, high-quality contextual information for AI-assisted development.
1255

1356
## Contents
1457

@@ -24,9 +67,9 @@ Each language-specific subdirectory contains its own linter implementation. Refe
2467
When contributing to or modifying the linters:
2568

2669
1. Ensure consistency between different language implementations
27-
2. Follow the AI Context Convention Specification strictly
70+
2. Follow the Codebase Context Specification strictly
2871
3. Write clear, well-documented code
2972
4. Include appropriate error messages and logging for easier debugging
3073
5. Add unit tests for any new functionality or bug fixes
3174

32-
Please refer to the main README.md file in the project root for more detailed contribution guidelines and the full specification of the AI Context Convention.
75+
Please refer to the main README.md file in the project root for more detailed contribution guidelines and the full specification of the Codebase Context Specification.

0 commit comments

Comments
 (0)