Skip to content

Commit 5120faa

Browse files
killerappkillerapp
committed
feat: add and refine the validation errors, use grey-matter
1 parent 92ee7eb commit 5120faa

File tree

10 files changed

+355
-126
lines changed

10 files changed

+355
-126
lines changed

‎.context.md‎

Lines changed: 78 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,114 @@
11
---
22
module-name: Codebase Context Specification
3-
related-modules:
4-
- ./linters/typescript: A TypeScript litner to provide a codified implementation of the spec in it's most basic form.
5-
- ./examples/context-editor: A sample editor to make it easy for folks to get started
63
version: 1.0.0
7-
description: README.md, meet SYSTEM PROMPT - In this session, we'll explore how CCS provides a structured yet flexible approach to documenting high-level architecture, design decisions, and project-specific conventions. Learn how this convention not only clarifies relationships within the code for human developers but also optimizes the codebase for AI model consumption, leading to more accurate suggestions and enhanced development efficiency.
8-
diagrams:
9-
- img/codebase-diagram.mermaid
4+
description: A specification for providing explicit context information about a codebase
5+
related-modules: []
6+
project-type: Specification
107
technologies:
11-
- Node.js
12-
- React
13-
- MongoDB
8+
- Markdown
9+
- YAML
10+
- JSON
1411
conventions:
15-
- Use consistent naming conventions within each file type
16-
- Each function should have a single responsibility
12+
- Follow Markdown best practices
13+
- Use YAML for structured data
14+
- Consistent naming conventions
1715
directives:
18-
- Focus on performance optimizations
19-
- Suggest ways to improve error handling
16+
- Maintain backward compatibility
17+
- Keep documentation up-to-date
18+
diagrams:
19+
- context-hierarchy.png
2020
architecture:
21-
style: Microservices
21+
style: Documentation-driven
2222
components:
23-
- Auth Service
24-
- User Service
25-
- Data Processing Service
26-
data-flow:
27-
- Client -> API Gateway -> Services -> Database
23+
- Specification document
24+
- Linters
25+
- Examples
26+
data-flow:
27+
- Codebase -> .context.md files -> Linters -> Validation results
2828
development:
2929
setup-steps:
30-
- Install Node.js v14+
31-
- Run `npm install` in each service directory
32-
- Set up MongoDB instance
30+
- Clone the repository
31+
- Review the specification documents
32+
- Install linter dependencies
3333
build-command: npm run build
3434
test-command: npm test
3535
business-requirements:
3636
key-features:
37-
- User authentication
38-
- Real-time data processing
39-
- Mobile-responsive UI
40-
target-audience: Small to medium-sized businesses
37+
- Provide a standardized format for codebase context
38+
- Enable AI-assisted development with explicit context
39+
- Support multiple programming languages and frameworks
40+
target-audience: Developers and AI assistants
4141
success-metrics:
42-
- User adoption rate
43-
- System response time
44-
- Data processing accuracy
42+
- Adoption rate among developers
43+
- Improved AI-assisted development accuracy
4544
quality-assurance:
4645
testing-frameworks:
4746
- Jest
48-
- Cypress
49-
coverage-threshold: 80%
47+
- Pytest
48+
coverage-threshold: "90%"
5049
performance-benchmarks:
51-
- API response time < 200ms
52-
- Database query time < 100ms
50+
- Linting speed for large codebases
51+
- Memory usage during linting
5352
deployment:
54-
platform: AWS
53+
platform: GitHub
5554
cicd-pipeline: GitHub Actions
56-
staging-environment: dev.myawesomeproject.com
57-
production-environment: myawesomeproject.com
58-
55+
staging-environment: GitHub Pages (Documentation)
56+
production-environment: npm registry (Linter package)
5957
---
6058

6159
# Codebase Context Specification
6260

63-
This project defines and implements the Codebase Context Specification, a standardized approach to providing context for AI-assisted development. The specification aims to enhance the effectiveness of AI models in understanding and working with codebases.
61+
This is the root directory for the Codebase Context Specification project. The specification defines a standardized way to provide explicit context information about a codebase, enabling more effective AI-assisted development.
6462

6563
## Project Structure
6664

67-
- Root directory: Contains specification files, main documentation, and linter subdirectories
68-
- `linters/`: Contains language-specific linter implementations
69-
- `typescript/`: TypeScript linter implementation
70-
- `python/`: Python linter implementation (placeholder)
65+
- `CODEBASE-CONTEXT.md`: The main specification document
66+
- `examples/`: Directory containing example implementations
67+
- `linters/`: Directory containing linter implementations for various languages
68+
- `README.md`: Project overview and quick start guide
7169

72-
## Key Components
70+
## Getting Started
7371

74-
1. Specification: Defined in (CODEBASE-CONTEXT.md)
75-
2. Linter Implementations:
76-
- TypeScript: `linters/typescript/src/context_linter.ts`
77-
- Python: (To be implemented)
78-
3. Documentation:
79-
- Main README: README.md
80-
- Linter-specific README: `linters/typescript/README.md`
72+
To get started with the Codebase Context Specification:
8173

82-
## Development Guidelines
74+
1. Review the `CODEBASE-CONTEXT.md` file for the full specification
75+
2. Check out the `examples/` directory for implementation examples
76+
3. Use the linters in the `linters/` directory to validate your .context.md files
8377

84-
- Follow the specification outlined in CODEBASE-CONTEXT.md
85-
- Ensure all new features have corresponding tests
86-
- Keep the linter implementations for different languages consistent in functionality
87-
- Update examples and documentation when making significant changes to the specification
78+
## Development
8879

89-
## Getting Started
80+
To contribute to the Codebase Context Specification:
81+
82+
1. Fork the repository
83+
2. Create a new branch for your changes
84+
3. Make your changes and ensure all tests pass
85+
4. Submit a pull request with a clear description of your changes
86+
87+
## Quality Assurance
88+
89+
We maintain high-quality standards through:
90+
91+
- Automated linting of .context.md files using Jest and Pytest
92+
- Manual review of all changes to the specification
93+
- Maintaining a test coverage threshold of 90%
94+
- Performance benchmarking for linting speed and memory usage
95+
96+
## Deployment
97+
98+
The Codebase Context Specification is versioned and released through GitHub. We use the following environments:
99+
100+
- GitHub for version control and collaboration
101+
- GitHub Actions for continuous integration and deployment
102+
- GitHub Pages for hosting documentation (staging)
103+
- npm registry for distributing the linter package (production)
90104

91-
Refer to the main README.md file for an overview of the project and its components. For language-specific linter setup and usage, see the README files in the respective linter directories.
105+
Each release goes through the following process:
92106

93-
## Contributing
107+
1. Development and testing on feature branches
108+
2. Merging to the main branch after review
109+
3. Running automated tests and linting
110+
4. Manual review of changes
111+
5. Deployment to staging (documentation update)
112+
6. Final approval and deployment to production (npm package release)
94113

95-
We welcome contributions! Please see the main README.md file for guidelines on how to contribute to this project. When contributing to specific linters, refer to their individual documentation for language-specific contribution guidelines.
114+
For more detailed information, please refer to the individual documents and subdirectories.

‎CODING-ASSISTANT-PROMPT.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,28 @@
1-
## Support the Codebase Context Specification
1+
## Instructions for Codebase Context (.context files)
22

33
You are tasked with reading and understanding the Codebase Context Specification files in a project to get explicit context information from the codebase itself.
44

55
Follow these guidelines:
66

77
1. Look for the following files in the project root and subdirectories:
8-
- .context.md (primary)
9-
- .context.yaml or .context.yml
10-
- .context.json
8+
- .context.md (primary, may be in json or yaml form)
119
- .contextdocs.md
1210
- .contextignore
1311

14-
2. Prioritize reading .context.md files, as they are the primary source of context information.
12+
2. Review the related-modules element for references to other modules. These other modules should have a .context.md at their root to review. If your task involves those modules, read the .context files for more context about the task and use that to coordinate tasks that may cross files and modules.
1513

1614
3. When analyzing .context.md files:
1715
- Pay attention to the YAML front matter for structured data.
1816
- Carefully read the free-form Markdown content for additional context.
1917

20-
4. For .context.yaml, .context.yml, or .context.json files:
18+
4. For .context.md (json/yaml) files:
2119
- Parse the structured data and understand the relationships between different fields.
22-
- Look for key sections such as project-name, version, description, main-technologies, conventions, and ai-prompts.
20+
- Look for key sections such as module-name, related-modules, description, main-technologies, conventions, and ai-prompts.
2321

2422
5. When encountering a .contextdocs.md file:
2523
- Understand that it specifies external documentation sources.
2624
- Note the types of documentation sources (local, URL, or package) and their relevance to the project.
25+
- You should use these URLs when you need more context, use your browser tool to do this as needed.
2726

2827
6. If a .contextignore file is present:
2928
- Recognize that it specifies files or directories to be excluded from context consideration.
@@ -48,4 +47,6 @@ Follow these guidelines:
4847

4948
10. Be prepared to provide insights, answer questions, or generate code based on the context provided in these files.
5049

50+
11. If you encounter a siutation where the .context.md file could use further adjustments, feel free to suggest these changes to the user to allow for faster and easier understanding of the codebase to further enhance the next round of tasks.
51+
5152
Remember, the Codebase Context Specification is designed to enhance AI-assisted development. Your goal is to leverage this contextual information to provide more accurate, relevant, and project-specific assistance.

‎examples/context-editor/.context.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
module-name: Context Editor
3+
related-modules:
4+
- ../../linters/typescript: TypeScript linter for validating context files
5+
version: 1.0.0
6+
description: A sample editor to make it easy for users to create and edit Codebase Context Specification files
7+
project-type: Web Application
8+
technologies:
9+
- React
10+
- TypeScript
11+
- Create React App
12+
conventions:
13+
- Use functional components with hooks
14+
- Follow React best practices and patterns
15+
- Use TypeScript for type safety
16+
directives:
17+
- Ensure responsive design for various screen sizes
18+
- Implement accessibility features
19+
architecture:
20+
style: Single Page Application
21+
components:
22+
- Header
23+
- ContextForm
24+
- MetadataSection
25+
- ArchitectureSection
26+
- DevelopmentSection
27+
- BusinessRequirementsSection
28+
- QualityAssuranceSection
29+
- DeploymentSection
30+
- MarkdownContentSection
31+
data-flow:
32+
- User Input -> ContextForm -> Generate Context File
33+
development:
34+
setup-steps:
35+
- Install Node.js v14+ and npm
36+
- Clone the repository
37+
- Run `npm install` in the project directory
38+
build-command: npm run build
39+
test-command: npm test
40+
start-command: npm start
41+
business-requirements:
42+
key-features:
43+
- User-friendly interface for creating .context.md files
44+
- Support for YAML front matter and Markdown content
45+
- Real-time preview of generated context file
46+
- Export functionality for saving .context.md files
47+
target-audience: Developers using the Codebase Context Specification
48+
success-metrics:
49+
- User adoption rate
50+
- Ease of use (measured through user feedback)
51+
- Accuracy of generated context files
52+
quality-assurance:
53+
testing-frameworks:
54+
- Jest
55+
- React Testing Library
56+
coverage-threshold: 80%
57+
performance-benchmarks:
58+
- Initial load time < 2s
59+
- UI responsiveness (60fps scrolling and interactions)
60+
deployment:
61+
platform: GitHub Pages
62+
cicd-pipeline: GitHub Actions
63+
staging-environment: N/A
64+
production-environment: https://example.com/context-editor
65+
---
66+
67+
# Context Editor
68+
69+
The Context Editor is a sample web application designed to help users create and edit Codebase Context Specification files easily. This tool demonstrates the practical application of the Codebase Context Specification and serves as a reference implementation for developers looking to integrate context creation into their workflows.
70+
71+
## Architecture Overview
72+
73+
The Context Editor follows a Single Page Application (SPA) architecture using React and TypeScript. The main components of the application include:
74+
75+
1. Header: Displays the application title and navigation (if applicable).
76+
2. ContextForm: The main form component that allows users to input context information.
77+
3. Various Section components (MetadataSection, ArchitectureSection, etc.): Handle specific sections of the context file.
78+
4. MarkdownContentSection: Allows users to input free-form Markdown content.
79+
80+
The application uses a unidirectional data flow, where user input is captured in the ContextForm component, which then generates the final context file.
81+
82+
## Development Guidelines
83+
84+
- Use functional components with hooks for all React components.
85+
- Leverage TypeScript for type safety and improved developer experience.
86+
- Follow React best practices, including proper state management and component composition.
87+
- Ensure the application is responsive and works well on various screen sizes.
88+
- Implement accessibility features to make the application usable by all.
89+
90+
## Setup and Running the Application
91+
92+
1. Ensure you have Node.js v14+ and npm installed.
93+
2. Clone the repository.
94+
3. Navigate to the project directory and run `npm install` to install dependencies.
95+
4. Use `npm start` to run the application in development mode.
96+
5. Use `npm test` to run the test suite.
97+
6. Use `npm run build` to create a production build.
98+
99+
## Business Context
100+
101+
The Context Editor aims to simplify the process of creating and editing Codebase Context Specification files. Key features include:
102+
103+
- An intuitive user interface for inputting context information
104+
- Support for YAML front matter and Markdown content
105+
- Real-time preview of the generated context file
106+
- Export functionality to save the created .context.md file
107+
108+
The target audience is developers who are using or plan to use the Codebase Context Specification in their projects. Success will be measured by user adoption rates, ease of use (gathered through user feedback), and the accuracy of generated context files.
109+
110+
## Quality Assurance
111+
112+
Our QA process ensures a high-quality, reliable application through:
113+
114+
- Unit and integration testing using Jest and React Testing Library
115+
- A minimum test coverage threshold of 80%
116+
- Performance benchmarks for initial load time and UI responsiveness
117+
- Accessibility testing to ensure WCAG compliance
118+
119+
## Deployment and Operations
120+
121+
The Context Editor is deployed as a static site on GitHub Pages:
122+
123+
1. Developers push code to the GitHub repository
124+
2. GitHub Actions run tests and build the application
125+
3. Successful builds are automatically deployed to GitHub Pages
126+
127+
The production environment is accessible at https://example.com/context-editor (replace with the actual URL when available).
128+
129+
## Contribution Guidelines
130+
131+
We welcome contributions to the Context Editor! If you'd like to contribute:
132+
133+
1. Fork the repository and create a new branch for your feature or bug fix.
134+
2. Ensure your code follows the project's coding conventions and best practices.
135+
3. Write or update tests as necessary.
136+
4. Submit a pull request with a clear description of your changes.
137+
138+
Please refer to the main project README for more detailed contribution guidelines.

‎linters/typescript/package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎linters/typescript/package.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,16 +32,16 @@
3232
},
3333
"homepage": "https://github.com/Agentic-Insights/codebase-context-spec#readme",
3434
"devDependencies": {
35+
"@semantic-release/changelog": "^6.0.3",
36+
"@semantic-release/git": "^10.0.1",
3537
"@types/jest": "^29.5.12",
3638
"@types/js-yaml": "^4.0.9",
3739
"@types/markdown-it": "^14.1.2",
3840
"@types/node": "^22.5.1",
3941
"jest": "^29.7.0",
40-
"ts-jest": "^29.1.2",
41-
"typescript": "^5.5.4",
4242
"semantic-release": "^22.0.12",
43-
"@semantic-release/changelog": "^6.0.3",
44-
"@semantic-release/git": "^10.0.1"
43+
"ts-jest": "^29.1.2",
44+
"typescript": "^5.5.4"
4545
},
4646
"dependencies": {
4747
"gray-matter": "^4.0.3",

0 commit comments

Comments
 (0)