Skip to content

Commit fd3ee0d

Browse files
osolmazosolmaz
authored
Claude code test (ts implementation for types) (#13)
* Add CLAUDE.md * Commit first passing version * Checkpoint * Model did reward hacking * Checkpoint * Second try * Don't hardcode enums as well * Use the main page example for serialization test * Run prettier
1 parent f33d0e6 commit fd3ee0d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

81 files changed

+7316
-0
lines changed

‎CLAUDE.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
JSON-DOC is a standardized format for storing structured content in JSON files, inspired by Notion's data model. It supports a wide variety of content types including paragraphs, headings, lists, tables, images, code blocks, and more.
8+
9+
The project consists of:
10+
1. A JSON schema specification for the format
11+
2. A Python implementation
12+
3. A TypeScript implementation (in progress)
13+
4. Converters for various formats (HTML, Markdown, etc.)
14+
15+
## Project Structure
16+
17+
- `/schema/`: JSON schemas defining the structure of JSON-DOC files
18+
- `/python/`: Python implementation
19+
- `/ts/`: TypeScript implementation (in progress)
20+
- `/docs/`: Documentation
21+
- `/examples/`: Example files showing the format
22+
- `/tests/`: Tests for both implementations
23+
24+
## Development Commands
25+
26+
### Python Development
27+
28+
```bash
29+
# Set up development environment
30+
cd /Users/onur/tc/JSON-DOC/python
31+
python -m pip install -e .
32+
python -m pip install -e ".[dev]"
33+
34+
# Run tests
35+
cd /Users/onur/tc/JSON-DOC/python
36+
pytest
37+
38+
# Run a specific test
39+
cd /Users/onur/tc/JSON-DOC/python
40+
pytest tests/test_serialization.py -v
41+
42+
# Run validation tests
43+
cd /Users/onur/tc/JSON-DOC/python
44+
python tests/test_validation.py schema
45+
46+
# Run linting
47+
cd /Users/onur/tc/JSON-DOC/python
48+
ruff check .
49+
ruff format .
50+
```
51+
52+
### TypeScript Development
53+
54+
```bash
55+
# Set up development environment
56+
cd /Users/onur/tc/JSON-DOC/ts
57+
npm install
58+
59+
# Build TypeScript
60+
cd /Users/onur/tc/JSON-DOC/ts
61+
npm run build
62+
63+
# Run tests
64+
cd /Users/onur/tc/JSON-DOC/ts
65+
npm test
66+
```
67+
68+
## Architecture Overview
69+
70+
### JSON-DOC Schema
71+
72+
The JSON-DOC schema is defined in JSONSchema format, with the following primary components:
73+
74+
1. **Page**: The top-level container for all content
75+
2. **Block**: Content blocks of various types (paragraph, heading, list item, etc.)
76+
3. **Rich Text**: Text content with formatting (bold, italic, etc.)
77+
4. **File**: External file references (images, etc.)
78+
79+
Each block type has specific schemas and validation rules.
80+
81+
### Python Implementation
82+
83+
The Python implementation uses Pydantic models for validation and serialization, with:
84+
85+
- Block types implemented as classes inheriting from a base Block class
86+
- Rich text types implemented as classes inheriting from a base RichText class
87+
- Serialization/deserialization functions for loading and saving JSON-DOC files
88+
- Converters for HTML, Markdown, and other formats
89+
90+
Key modules:
91+
- `jsondoc.models`: Pydantic models for JSON-DOC
92+
- `jsondoc.serialize`: Functions for loading/saving JSON-DOC
93+
- `jsondoc.validate`: Schema validation
94+
- `jsondoc.convert`: Conversion between formats
95+
96+
### TypeScript Implementation
97+
98+
The TypeScript implementation is in progress, following similar architecture to the Python version:
99+
100+
- Type definitions for all JSON-DOC structures
101+
- Functions for loading/saving JSON-DOC files
102+
- Schema validation
103+
- Converters for other formats
104+
105+
## Testing Strategy
106+
107+
- Schema validation tests ensure examples conform to schemas
108+
- Serialization tests ensure round-trip conversion preserves data
109+
- Conversion tests verify correct transformation between formats
110+
- Integration tests for end-to-end workflows
111+
112+
## Implementation Notes
113+
114+
1. The project follows a modular architecture with clear separation between:
115+
- Schema definition
116+
- Model implementation
117+
- Validation
118+
- Serialization
119+
- Conversion
120+
121+
2. The TypeScript implementation should follow the same patterns as the Python implementation, with appropriate adaptations for the TypeScript ecosystem.
122+
123+
3. The core functionality is focused on:
124+
- Loading JSON-DOC files into typed objects
125+
- Validating JSON-DOC files against schemas
126+
- Converting between JSON-DOC and other formats

‎docs/typescript-implementation.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: "TypeScript Implementation"
3+
author: "TextCortex Dev Team"
4+
date: "2025-05-21"
5+
---
6+
7+
This file was generated by Claude Code.
8+
9+
---
10+
11+
# JSON-DOC TypeScript Implementation
12+
13+
In addition to the Python implementation, JSON-DOC is also available as a TypeScript library. This allows for better integration with JavaScript/TypeScript projects and web applications.
14+
15+
## Installation
16+
17+
```bash
18+
# Using npm
19+
npm install jsondoc
20+
21+
# Using yarn
22+
yarn add jsondoc
23+
```
24+
25+
## Features
26+
27+
The TypeScript implementation provides the following features:
28+
29+
- Full TypeScript type definitions for all JSON-DOC objects
30+
- Loader/serializer functions similar to the Python implementation
31+
- Runtime validation using JSON Schema (via ajv)
32+
- Support for all block types defined in the JSON-DOC specification
33+
34+
## Usage
35+
36+
```typescript
37+
import { loadJsonDoc, jsonDocDumpJson } from 'jsondoc';
38+
39+
// Load JSON-DOC from a string
40+
const jsonString = '{"object":"page","id":"page-id","children":[...]}';
41+
const doc = loadJsonDoc(jsonString);
42+
43+
// Or load from an object
44+
const jsonObject = {
45+
object: 'page',
46+
id: 'page-id',
47+
children: [...]
48+
};
49+
const doc2 = loadJsonDoc(jsonObject);
50+
51+
// Serialize back to JSON
52+
const serialized = jsonDocDumpJson(doc, 2); // 2 spaces indentation
53+
```
54+
55+
## Type Definitions
56+
57+
The TypeScript implementation provides type-safe interfaces for all JSON-DOC objects. These are automatically generated from the same JSON schemas used by the Python implementation.
58+
59+
```typescript
60+
import {
61+
Page,
62+
BlockBase,
63+
BlockType,
64+
RichTextText
65+
} from 'jsondoc';
66+
67+
// Create a simple page
68+
const page: Page = {
69+
object: 'page',
70+
id: 'page-id',
71+
children: [
72+
{
73+
object: 'block',
74+
type: BlockType.Paragraph,
75+
paragraph: {
76+
rich_text: [
77+
{
78+
type: 'text',
79+
text: {
80+
content: 'Hello, world!'
81+
}
82+
}
83+
]
84+
}
85+
}
86+
]
87+
};
88+
```
89+
90+
## Validation
91+
92+
The TypeScript implementation includes validation functions similar to the Python implementation:
93+
94+
```typescript
95+
import { validateAgainstSchema, loadSchema } from 'jsondoc';
96+
97+
// Load a schema
98+
const schema = await loadSchema('path/to/schema.json');
99+
100+
// Validate a document
101+
try {
102+
validateAgainstSchema(document, schema);
103+
console.log('Document is valid');
104+
} catch (error) {
105+
console.error('Validation failed:', error.message);
106+
}
107+
```
108+
109+
## Implementation Details
110+
111+
### Code Generation
112+
113+
The TypeScript interfaces are generated directly from the JSON schemas using `json-schema-to-typescript`. This ensures that the TypeScript types match the JSON schema definitions exactly.
114+
115+
### Architecture
116+
117+
The TypeScript implementation follows a similar architecture to the Python implementation:
118+
119+
- **models/**: TypeScript interfaces for JSON-DOC objects
120+
- **validation/**: Schema validation functionality
121+
- **serialization/**: Loading and serializing JSON-DOC objects
122+
- **utils/**: Utility functions
123+
124+
### Differences from Python Implementation
125+
126+
While we strive to keep the API similar between the Python and TypeScript implementations, there are some differences due to the nature of the languages:
127+
128+
1. TypeScript's type system is compile-time only, so runtime validation is handled separately using ajv
129+
2. The TypeScript implementation uses standard ES modules for imports/exports
130+
3. Function naming follows JavaScript conventions (camelCase instead of snake_case)
131+
132+
## Development
133+
134+
If you want to contribute to the TypeScript implementation, see the [README.md](../ts/README.md) file in the `ts` directory for development instructions.

‎ts/.github/workflows/build.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Build and Test
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "ts/**"
8+
pull_request:
9+
branches: [main]
10+
paths:
11+
- "ts/**"
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
defaults:
17+
run:
18+
working-directory: ./ts
19+
20+
strategy:
21+
matrix:
22+
node-version: [16.x, 18.x, 20.x]
23+
24+
steps:
25+
- uses: actions/checkout@v3
26+
- name: Use Node.js ${{ matrix.node-version }}
27+
uses: actions/setup-node@v3
28+
with:
29+
node-version: ${{ matrix.node-version }}
30+
cache: "npm"
31+
cache-dependency-path: ./ts/package-lock.json
32+
33+
- name: Install dependencies
34+
run: npm ci
35+
36+
- name: Generate types
37+
run: npm run generate-types
38+
39+
- name: Build
40+
run: npm run build
41+
42+
- name: Test
43+
run: npm test

‎ts/.github/workflows/publish.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Publish Package
2+
3+
on:
4+
release:
5+
types: [created]
6+
7+
jobs:
8+
build:
9+
runs-on: ubuntu-latest
10+
defaults:
11+
run:
12+
working-directory: ./ts
13+
14+
steps:
15+
- uses: actions/checkout@v3
16+
- uses: actions/setup-node@v3
17+
with:
18+
node-version: "16.x"
19+
registry-url: "https://registry.npmjs.org"
20+
21+
- name: Install dependencies
22+
run: npm ci
23+
24+
- name: Generate types
25+
run: npm run generate-types
26+
27+
- name: Build
28+
run: npm run build
29+
30+
- name: Test
31+
run: npm test
32+
33+
- name: Publish
34+
run: npm publish
35+
env:
36+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

0 commit comments

Comments
 (0)