fix: resolve CodeQL syntax errors, type checking issues, and update dependency version bounds (#45)

* fix: resolve CodeQL syntax errors in JavaScript/TypeScript and Python files

- Fix TypeScript syntax errors in contextforgeClient.ts:
  - Fix missing JSDoc comment opening
  - Fix method call parameter mismatch in shouldRetry
  - Implement complete v1Checkpoint method
  - Remove orphaned code blocks

- Fix Python syntax errors in test_vulnerability_scripts.py:
  - Remove duplicate @patch decorators
  - Remove invalid @@ syntax characters
  - Fix malformed test structure

- Remove empty test_optional_properties.ts file
- Add test_syntax.py for syntax validation

Resolves CodeQL parse errors for both JavaScript/TypeScript and Python languages

* docs: update cursor rules to prohibit --no-verify usage

- Add strict guidelines against using --no-verify flag
- Emphasize fixing all errors before pushing
- Add detailed explanations of why --no-verify is dangerous
- Provide specific solutions for common pre-commit failures
- Update Python, testing, and general rules with quality gates
- Ensure CI/CD alignment by preventing bypassed checks

This prevents CI failures and maintains code quality standards.

* fix: resolve all type checking issues

- Add type: ignore comments to tiktoken import in openai.py
- Add type: ignore comments to handler imports in test files
- Fix import resolution errors for dynamic path manipulation
- All type checking now passes with 0 errors, 0 warnings

Resolves pyright type checking issues:
- tiktoken import error in src/contextforge_memory/summarize/openai.py
- handlers.json_handler import error in tests/test_json_handler.py
- handlers.toml_handler import error in tests/test_toml_handler.py

* Update clients/typescript/contextforgeClient.ts

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* feat: add metadata validation to v1Checkpoint method

- Add validation guard for metadata parameter in v1Checkpoint method
- Validate that metadata is a non-null object when provided
- Reject arrays and null values to match validateMemoryItem behavior
- Throw descriptive error message for invalid metadata types
- Ensures type safety and consistency across the TypeScript client

* chore: update dependencies

- Update click from 8.1.8 to 8.3.0
- Update rich from 13.5.3 to 14.2.0
- Update tomli from 2.0.2 to 2.3.0
- Addresses potential CI dependency issues

* fix: add mypy dependency and resolve type checking issues

- Add mypy>=1.0.0 to requirements-dev.in
- Regenerate requirements-dev.txt with mypy==1.18.2
- Remove unused type: ignore comments in openai.py
- Fixes CI failure: 'mypy: command not found'
- Resolves mypy strict mode type checking errors

The CI was failing because mypy was not installed in the environment.
This commit adds mypy as a development dependency and removes
unnecessary type suppressions that were causing mypy errors.

* security: add SHA256 integrity hashes to requirements.txt

- Regenerate requirements.txt with pip-compile --generate-hashes
- All 20 dependencies now have corresponding --hash=sha256:... lines
- Ensures package integrity and prevents supply chain attacks
- Meets security requirements for dependency verification

Dependencies updated with hashes:
- click==8.3.0, rich==14.2.0, tomli==2.3.0 (previously missing hashes)
- All other dependencies also regenerated with current hashes
- Maintains exact same versions while adding security verification

* feat: update OpenAI and tiktoken version bounds

- Update openai constraint from <2.0.0 to <3.0.0 to allow 2.x versions
- Update tiktoken constraint from <1.0.0 to <1.0.0 (corrected from <2.0.0)
- Allows OpenAI 2.x versions for latest features and security patches
- Maintains tiktoken 0.x compatibility while preventing breaking 1.x changes
- All functionality tested and verified working
- Code formatting applied to maintain consistency

Resolves version constraint issues and future-proofs dependencies.

* fix: resolve CI hash mismatch by adding setuptools to requirements

- Add setuptools>=65.5.1 to requirements.in to resolve hash mismatch
- Regenerate requirements.txt with proper setuptools hashes
- Fixes CI failure: 'setuptools>=65.5.1' missing from requirements.txt
- Maintains version bounds for openai and tiktoken

* fix: include setuptools in requirements.txt to resolve CI hash mismatch

- Use --allow-unsafe flag with pip-compile to include setuptools
- Add setuptools==80.9.0 with proper hashes to requirements.txt
- Fixes CI failure: 'setuptools>=65.5.1' missing from requirements.txt
- Maintains version bounds for openai and tiktoken

---------

Co-authored-by: Ben De Cock <[email protected]>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: 3 people

.cursor/rules/general.mdc

@@ -76,11 +76,66 @@ globs: **/*
 5. Run linting ONLY in venv: `source .venv/bin/activate && make lint`
 6. Run type checking ONLY in venv: `source .venv/bin/activate && make type-check`
 7. Format code ONLY in venv: `source .venv/bin/activate && make format`
-8. Update documentation if needed
-9. Create pull request
+8. **CRITICAL**: Fix ALL errors before committing - never use `--no-verify`
+9. Update documentation if needed
+10. Create pull request
 
 **REMINDER**: All Python commands must be run within the activated virtual environment
 
+## Pre-commit and Push Rules
+
+🚨 **CRITICAL**: Never use `--no-verify` flag when pushing commits
+
+- **ALWAYS** fix all pre-commit hook errors before pushing
+- **ALWAYS** fix all linting errors before pushing
+- **ALWAYS** fix all type checking errors before pushing
+- **ALWAYS** fix all test failures before pushing
+- **ALWAYS** ensure all security scans pass before pushing
+
+### Why Never Use --no-verify
+
+- **CI/CD will fail**: GitHub Actions will catch the same errors and fail the build
+- **Security risks**: Bypassing security scans defeats the purpose of automated checks
+- **Code quality**: Skipping quality checks leads to technical debt
+- **Team workflow**: Other developers expect clean, tested code
+- **Production safety**: Errors that pass locally will fail in production
+
+### When Pre-commit Hooks Fail
+
+1. **Read the error message carefully**
+2. **Fix the underlying issue** (don't just suppress the error)
+3. **Run the specific command that failed** to understand the error
+4. **Test your fix** by running the command again
+5. **Only commit when all checks pass**
+
+### Common Pre-commit Failures and Solutions
+
+```bash
+# If ruff linting fails
+source .venv/bin/activate && make lint
+
+# If black formatting fails
+source .venv/bin/activate && make format
+
+# If mypy type checking fails
+source .venv/bin/activate && make type-check
+
+# If tests fail
+source .venv/bin/activate && make test
+
+# If security scans fail
+source .venv/bin/activate && pip-audit -r requirements.txt
+```
+
+### Emergency Situations
+
+If you absolutely must bypass pre-commit hooks (emergency fixes only):
+
+1. **Document why** in the commit message
+2. **Create a follow-up issue** to fix the bypassed checks
+3. **Fix the issues immediately** in the next commit
+4. **Never merge** code that bypasses security or quality checks
+
 ## Testing Strategy
 
 - **Dual-suite architecture**: Public API tests (`test_backfill_scanning.py`) + Integration tests (`test_backfill_integration.py`)

.cursor/rules/python.mdc

@@ -13,6 +13,46 @@ globs: **/*.py
 - Use `from __future__ import annotations` for forward references - MUST be placed before any other imports or executable code, but may come after optional module-level elements (shebang, encoding declaration, license/comments block, or module docstring) to ensure consistent forward-reference behavior across the codebase
 - Docstrings required for public functions and classes (Google style)
 
+## Pre-commit and Quality Gates
+
+🚨 **CRITICAL**: Never use `--no-verify` when pushing Python code
+
+- **ALWAYS** fix all linting errors before pushing
+- **ALWAYS** fix all type checking errors before pushing
+- **ALWAYS** fix all formatting issues before pushing
+- **ALWAYS** fix all security scan failures before pushing
+- **ALWAYS** ensure all tests pass before pushing
+
+### Python-Specific Quality Checks
+
+```bash
+# Activate virtual environment first
+source .venv/bin/activate
+
+# Run all quality checks
+make lint          # ruff linting
+make format        # black formatting
+make type-check    # mypy type checking
+make test          # pytest testing
+pip-audit -r requirements.txt  # security scanning
+```
+
+### Common Python Quality Issues
+
+```python
+# Fix import sorting issues
+# Run: ruff check --fix
+
+# Fix type annotation issues
+# Run: mypy src/ --strict
+
+# Fix formatting issues
+# Run: black src/
+
+# Fix security issues
+# Run: pip-audit -r requirements.txt
+```
+
 ## Type Hints
 
 ```python

.cursor/rules/testing.mdc

@@ -5,6 +5,39 @@ globs: **/tests/**/*.py
 
 # Testing Guidelines
 
+## Pre-commit Testing Rules
+
+🚨 **CRITICAL**: Never use `--no-verify` when pushing test code
+
+- **ALWAYS** ensure all tests pass before pushing
+- **ALWAYS** fix all test failures before pushing
+- **ALWAYS** ensure test coverage meets requirements before pushing
+- **ALWAYS** run both API and integration tests before pushing
+
+### Test Quality Gates
+
+```bash
+# Activate virtual environment first
+source .venv/bin/activate
+
+# Run all tests
+make test-api        # Quick API validation (recommended for development)
+make test-integration # Comprehensive functionality testing
+make test           # Full test suite (for CI/CD)
+
+# Run with coverage
+make test-coverage  # Run tests with coverage reporting
+```
+
+### When Tests Fail
+
+1. **Read the test failure message carefully**
+2. **Run the specific test that failed** to understand the issue
+3. **Fix the underlying problem** (don't just skip the test)
+4. **Re-run the test** to confirm the fix
+5. **Run the full test suite** to ensure no regressions
+6. **Only commit when all tests pass**
+
 ## Testing Strategy
 
 ### Dual Test Suite Architecture

.github/scripts/test_vulnerability_scripts.py

@@ -180,13 +180,6 @@ def test_create_issue_body_with_empty_vulns(self):
         self.assertIn("HIGH/CRITICAL vulnerabilities: 0", body)
 
     @patch("create_security_issue.subprocess.run")
-@@
-    @patch("create_security_issue.subprocess.run")
-@@
-    @patch("create_security_issue.subprocess.run")
-@@
-    @patch("create_security_issue.subprocess.run")
-    @patch("subprocess.run")
     def test_create_github_issue_failure(self, mock_run):
         """Test handling GitHub issue creation failure."""
         from subprocess import CalledProcessError

clients/typescript/contextforgeClient.ts

@@ -188,6 +188,8 @@ export class ContextForgeClient {
     }
     return false;
   }
+
+  /**
    * Parses error response body for better error messages.
    * @private
    */
@@ -247,7 +249,7 @@ export class ContextForgeClient {
       }
 
       // Decide whether to retry
-      if (attempt < this.retryConfig.maxRetries && lastError !== undefined && this.shouldRetry(lastError, lastResponse)) {
+      if (attempt < this.retryConfig.maxRetries && lastError !== undefined && this.shouldRetry(lastError)) {
         const delay = this.calculateDelay(attempt);
         // Log retry decision
         this.logger?.warn(`Retry attempt ${attempt + 1}/${this.retryConfig.maxRetries} for ${url}`, {
@@ -499,12 +501,54 @@ export class ContextForgeClient {
     return r.json() as Promise<{ vectors: number[][] }>;
   }
 
- if (summary !== undefined && typeof summary !== 'string') {
-   throw new Error('summary must be a string when provided');
- }
- if (summary !== undefined && summary.trim() === '') {
-   throw new Error('summary must be a non-empty string when provided');
- }
+  /**
+   * Creates a checkpoint for a session using the v1 API.
+   *
+   * @param session_id - The session ID to create a checkpoint for
+   * @param phase - The phase of the session (planning, execution, review)
+   * @param summary - Optional summary of the checkpoint
+   * @param metadata - Optional metadata for the checkpoint
+   * @returns Promise resolving to an object indicating success
+   * @throws Error if the API request fails
+   */
+  async v1Checkpoint(
+    session_id: string,
+    phase: 'planning' | 'execution' | 'review',
+    summary?: string,
+    metadata?: Record<string, unknown>
+  ): Promise<{ ok: boolean }> {
+    // Validate input
+    if (!session_id || typeof session_id !== 'string' || session_id.trim() === '') {
+      throw new Error('session_id must be a non-empty string');
+    }
+    if (!phase || !['planning', 'execution', 'review'].includes(phase)) {
+      throw new Error('phase must be one of: planning, execution, review');
+    }
+    if (summary !== undefined && (typeof summary !== 'string' || summary.trim() === '')) {
+      throw new Error('summary must be a non-empty string when provided');
+    }
+    if (metadata !== undefined) {
+      if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) {
+        throw new Error('metadata must be a non-null object when provided');
+      }
+    }
+
+    const body: {
+      session_id: string;
+      phase: string;
+      summary?: string;
+      metadata?: Record<string, unknown>;
+    } = { session_id, phase };
+    if (summary !== undefined) body.summary = summary;
+    if (metadata !== undefined) body.metadata = metadata;
+
+    const r = await this.fetchWithRetry(`${this.baseUrl}/v1/checkpoint`, {
+      method: "POST",
+      headers: this.authHeaders(true),
+      body: JSON.stringify(body),
+    });
+    return r.json() as Promise<{ ok: boolean }>;
+  }
 
   /**
    * Restores context for a session using the v1 API with retry logic.

pyproject.toml

@@ -76,6 +76,10 @@ dev = [
   "safety==3.6.2",
   "pip-audit==2.9.0",
 ]
+openai = [
+  "openai>=1.0.0,<3.0.0",
+  "tiktoken>=0.5.0,<1.0.0",
+]
 
 [tool.setuptools.packages.find]
 where = ["src"]

requirements-dev.in

@@ -13,3 +13,4 @@ tomli>=2.0.0
 tomli-w>=1.0.0
 pip-tools>=7.0.0
 pyright>=1.1.0
+mypy>=1.0.0

requirements-dev.txt

@@ -64,8 +64,12 @@ mdurl==0.1.2
     # via markdown-it-py
 msgpack==1.1.2
     # via cachecontrol
+mypy==1.18.2
+    # via -r requirements-dev.in
 mypy-extensions==1.1.0
-    # via black
+    # via
+    #   black
+    #   mypy
 nodeenv==1.9.1
     # via
     #   pre-commit
@@ -81,7 +85,9 @@ packaging==25.0
     #   pip-requirements-parser
     #   pytest
 pathspec==0.12.1
-    # via black
+    # via
+    #   black
+    #   mypy
 pip-api==0.0.34
     # via pip-audit
 pip-audit==2.9.0
@@ -152,7 +158,9 @@ types-aiofiles==25.1.0.20251011
 types-pyyaml==6.0.12.20250915
     # via -r requirements-dev.in
 typing-extensions==4.15.0
-    # via pyright
+    # via
+    #   mypy
+    #   pyright
 urllib3==2.5.0
     # via requests
 virtualenv==20.35.3

requirements.in

@@ -0,0 +1,23 @@
+# Core dependencies
+fastapi==0.120.0
+uvicorn[standard]==0.38.0
+pydantic==2.12.3
+orjson==3.11.3
+numpy==2.3.4
+pytest==8.4.2
+httpx==0.28.1
+ruff==0.14.2
+black==25.9.0
+starlette==0.48.0
+safety==3.6.2
+pip-audit==2.9.0
+tenacity==9.1.2
+aiofiles==25.1.0
+filelock==3.20.0
+click==8.3.0
+rich==14.2.0
+tomli==2.3.0
+tomli_w==1.2.0
+tiktoken>=0.5.0,<1.0.0
+openai>=1.0.0,<3.0.0
+# setuptools==80.9.0