CDEV Toolkit

A TypeScript library for parsing and manipulating CDEV (Code Development) notation files. This toolkit provides comprehensive functionality for working with structured code projects, including parsing, querying, validation, and execution of code modifications.

Features

• Parse CDEV notation files into structured project representations
• Query project contents with advanced search and filtering capabilities
• Execute code modifications through patches, overrides, renames, and truncations
• Validate operations before execution to prevent errors
• Generate diffs to track changes
• AI-friendly context building for code analysis workflows
• Full TypeScript support with comprehensive type definitions

Installation

npm install cdev-toolkit

Project Structure

cdev-toolkit/
├── package.json                 # Package configuration
├── tsconfig.json               # TypeScript configuration
├── jest.config.js              # Jest testing configuration
└── src/
    ├── index.ts                # Main exports and CdevToolkit class
    ├── types/
    │   └── index.ts            # Type definitions and interfaces
    ├── parser/
    │   ├── CdevParser.ts       # Main CDEV format parser
    │   ├── MetadataParser.ts   # Project metadata parser
    │   └── OperationParser.ts  # Code operation parser
    ├── query/
    │   ├── CdevQuery.ts        # Project querying functionality
    │   ├── FunctionFinder.ts   # Function detection and extraction
    │   └── ContextBuilder.ts   # AI context generation
    └── executor/
        ├── CdevExecutor.ts     # Main execution coordinator
        ├── PatchExecutor.ts    # Code patch application
        ├── FileOperations.ts   # File manipulation utilities
        └── Validator.ts        # Operation validation

Quick Start

import { CdevToolkit } from 'cdev-toolkit';

// Parse a CDEV project from text
const toolkit = CdevToolkit.fromText(`
\`\`\`cdev
=== METADATA ===
project: my-app
version: 1.0.0
language: typescript
=== end metadata ===

=== FILE: /src/index.ts ===
export function hello(name: string): string {
  return \`Hello, \${name}!\`;
}
=== end ===

=== end of project ===
\`\`\`
`);

// Query the project
console.log('Files:', toolkit.listFiles());
console.log('Functions:', toolkit.findFunctions());
console.log('Metadata:', toolkit.getMetadata());

// Generate AI context
const context = toolkit.buildAIContext({
  includeMetadata: true,
  maxFileSize: 5000
});

Core Classes

CdevToolkit

The main class that provides a unified interface to all functionality:

// Create instances
const toolkit = CdevToolkit.fromText(cdevText);
const empty = CdevToolkit.empty();
const fromProject = CdevToolkit.fromProject(project);

// Parse and serialize
toolkit.parse(cdevText);
const serialized = toolkit.serialize();

// Query operations
const files = toolkit.listFiles(/\.ts$/);
const content = toolkit.getFile('/src/index.ts');
const functions = toolkit.findFunctions('myFunction');
const results = toolkit.searchContent(/TODO/gi);

CdevParser

Handles parsing and serialization of CDEV format:

import { CdevParser } from 'cdev-toolkit';

const project = CdevParser.parse(cdevText);
const serialized = CdevParser.serialize(project);

CdevQuery

Provides advanced querying capabilities:

import { CdevQuery } from 'cdev-toolkit';

const query = new CdevQuery(project);

// Search and analyze
const searchResults = query.searchContent('function');
const dependencies = query.getDependencyGraph();
const context = query.buildAIContext({
  fileFilter: /\.ts$/,
  includeMetadata: true
});

CdevExecutor

Handles code modifications with validation and rollback:

import { CdevExecutor } from 'cdev-toolkit';

const executor = new CdevExecutor(project);

// Execute patches with validation
const validation = executor.validatePatches(patches);
if (validation.isValid) {
  const result = executor.executePatches(patches);
  console.log('Modified files:', result.filesModified);
  console.log('Diff:', result.diff);
}

// Rollback if needed
executor.rollback();

CDEV Format

The CDEV format is a structured way to represent code projects:

```cdev
=== METADATA ===
project: example
version: 1.0.0
author: Developer
=== end metadata ===

=== FILE: /src/main.js ===
function main() {
  console.log('Hello World');
}
=== end ===

=== end of project ===

## Operations

### Patches

Apply targeted code modifications:

```typescript
const patches: CdevPatch[] = [{
  filePath: '/src/index.ts',
  operations: [{
    type: 'after',
    target: 5,
    additions: ['// New comment', 'const newVar = true;'],
    deletions: []
  }]
}];

const result = toolkit.executePatches(patches);

Overrides

Replace entire file contents:

const overrides: CdevOverride[] = [{
  filePath: '/src/config.ts',
  content: 'export const config = { debug: true };'
}];

toolkit.executeOverrides(overrides);

Renames

Rename files within the project:

const renames: CdevRename[] = [{
  fromPath: '/src/old-name.ts',
  toPath: '/src/new-name.ts'
}];

toolkit.executeRenames(renames);

Truncates

Delete files from the project:

const truncates: CdevTruncate[] = [{
  filePath: '/src/temp-file.ts'
}];

toolkit.executeTruncates(truncates);

Advanced Features

Function Finding

Detect and extract functions from code:

// Find all functions
const allFunctions = toolkit.findFunctions();

// Find specific function
const specificFunction = toolkit.findFunctions('myFunction', '/src/utils.ts');

// Function information includes:
// - name, filePath, startLine, endLine, content

Dependency Analysis

Analyze project dependencies:

const graph = toolkit.getDependencyGraph();
// Returns array of DependencyNode with imports/exports for each file

AI Context Building

Generate structured context for AI workflows:

const context = toolkit.buildAIContext({
  includeMetadata: true,
  fileFilter: /\.(ts|js)$/,
  maxFileSize: 10000,
  includeDependencies: true
});

Validation

Validate operations before execution:

const validation = toolkit.validatePatches(patches);
if (!validation.isValid) {
  console.error('Validation errors:', validation.errors);
  console.warn('Warnings:', validation.warnings);
}

Error Handling

The toolkit provides specific error types:

import { CdevError, CdevParseError, CdevExecutionError } from 'cdev-toolkit';

try {
  const project = CdevParser.parse(invalidCdevText);
} catch (error) {
  if (error instanceof CdevParseError) {
    console.error(`Parse error at line ${error.line}: ${error.message}`);
  }
}

TypeScript Support

Full TypeScript definitions are included:

import type { 
  CdevProject, 
  CdevMetadata, 
  PatchOperation,
  ValidationResult,
  ExecutionResult 
} from 'cdev-toolkit';

Development

# Build the project
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch

# Lint code
npm run lint

License

MIT License - see package.json for details.

Contributing

This toolkit is designed for AI-assisted code development workflows. Contributions should focus on improving parsing accuracy, execution reliability, and AI integration capabilities.