From 18a54b31c2f4e3af3942177e6f00ac2a19399cab Mon Sep 17 00:00:00 2001 From: James Hobbs Date: Wed, 5 Aug 2026 11:57:27 -0500 Subject: [PATCH] docs: add Claude repository routing --- AGENTS.md | 85 +------------------------------------------------------ CLAUDE.md | 25 +++++++++++++++- 2 files changed, 25 insertions(+), 85 deletions(-) mode change 100644 => 120000 AGENTS.md mode change 120000 => 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 292cfb7604..0000000000 --- a/AGENTS.md +++ /dev/null @@ -1,84 +0,0 @@ -# Code Style & Organization - -- Order method, fields and properties, first by accessibility and then by alphabetical order. -- Don't add the Microsoft copyright header to new files. -- Use `Uri.joinPath()` for constructing file paths to ensure platform-correct path separators (e.g., `Uri.joinPath(venvPath, 'share', 'jupyter', 'kernels')` instead of string concatenation with `/`) -- Follow established patterns, especially when importing new packages (e.g. instead of importing uuid directly, use the helper `import { generateUuid } from '../platform/common/uuid';`) - -## Code conventions - -- Always run `npm run format-fix` after making changes to the code - -## Testing - -- Unit tests use Mocha/Chai framework with `.unit.test.ts` extension -- Test files should be placed alongside the source files they test -- Tests run against compiled JavaScript files in `out/` directory — build first with `npm run compile-tsc` -- Run all tests: `npm test` or `npm run test:unittests` -- Run tests matching a pattern: `npm run test:unittests -- --grep "SuiteName"` (forwards `--grep` to mocha, matches suite and test names) -- Run single test file: `npx mocha --config ./build/.mocha.unittests.js.json ./out/path/to/file.unit.test.js` -- Use `assert.deepStrictEqual()` for object comparisons instead of checking individual properties - -## Project Structure - -- VSCode extension for Jupyter notebooks -- Uses dependency injection with inversify -- Follows separation of concerns pattern -- TypeScript codebase that compiles to `out/` directory - -## Deepnote Integration - -- Located in `src/notebooks/deepnote/` -- Refactored architecture: - - `deepnoteTypes.ts` - Type definitions - - `deepnoteNotebookManager.ts` - State management - - `deepnoteNotebookSelector.ts` - UI selection logic - - `deepnoteDataConverter.ts` - Data transformations - - `deepnoteSerializer.ts` - Main serializer (orchestration) - - `deepnoteActivationService.ts` - VSCode activation -- Whitespace is good for readability, add a blank line after const groups and before return statements -- Separate third-party and local file imports -- How the extension works is described in @specs/architecture.md -- Snapshot mode: avoid persisting execution-time metadata (e.g., `contentHash`) to prevent dirty state; rely on in-memory tracking when needed -- `DeepnoteNotebookSerializer.detectContentChanges` should consider notebook-level fields (e.g., `name`, `executionMode`, `isModule`, `workingDirectory`) and detect removed notebooks, in addition to block-level comparisons - -## Best Practices - -### Resource Cleanup - -- Always dispose `CancellationTokenSource` - never create inline without storing/disposing -- Use try/finally to ensure cleanup: - - ```typescript - const cts = new CancellationTokenSource(); - try { - await fn(cts.token); - } finally { - cts.dispose(); - } - ``` - - -### DRY Principle - -- Extract duplicate logic into helper methods to prevent drift -- When similar logic appears in multiple places (e.g., placeholder controller setup, interpreter validation), consolidate it - -### Magic Numbers - -- Extract magic numbers (retry counts, delays, timeouts) as named constants near the top of the module - -### Error Handling - -- Use per-iteration error handling in loops - wrap each iteration in try/catch so one failure doesn't stop the rest -- Handle `withProgress` cancellation gracefully - it throws when user cancels, so wrap in try/catch and return appropriate value - -### State Validation - -- Verify state after async setup operations - methods can return early without throwing, so check expected state was created -- Validate cached state before early returns - before returning "already configured", verify the state is still valid (e.g., interpreter paths match, controllers aren't stale) - -### Cancellation Tokens - -- Use real cancellation tokens tied to lifecycle events instead of fake/never-cancelled tokens -- Create `CancellationTokenSource` tied to relevant events (e.g., notebook close, cell cancel) diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000000..681311eb9c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 120000 index 47dc3e3d86..0000000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..478ac55923 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,24 @@ +# Deepnote editor extension + +This TypeScript repository implements the Deepnote notebook extension for VS Code-compatible editors and its integration with Deepnote's format and Python runtime. + +## Working rules + +- Use the routing table before searching. Start with the architecture, owning feature directory, and colocated tests; do not traverse unrelated inherited VS Code code. +- Read `package.json`, build configuration, and CI for current commands, versions, and tooling instead of copying them into guidance. +- Add or update focused tests for behavior changes and compare complete objects with `assert.deepStrictEqual` where practical. +- Use platform path APIs rather than constructing paths with separators. Store and dispose lifecycle resources, and validate expected state after asynchronous setup or before cached early returns. +- Do not add the Microsoft copyright header to new files. Follow nearby import and organization patterns rather than inventing new ones. +- Document non-obvious coupling at every affected serializer, controller, service, or webview with reciprocal references. +- Put durable discoveries in shared repository documentation under `specs/` or the nearest README, not local memory files. Keep this file limited to behavior and routing. + +## Routing table + +| When looking for | Look into | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| User-facing capabilities and repository overview | [README.md](README.md) | +| Development workflow, build targets, and test suites | [CONTRIBUTING.md](CONTRIBUTING.md), `package.json`, and `.github/workflows/` | +| Deepnote extension architecture and data flow | [specs/architecture.md](specs/architecture.md) | +| A specific feature or platform abstraction | The owning directory under `src/`, its nearest README, and colocated tests | +| Notebook format, conversion, and integration schemas | [deepnote](https://github.com/deepnote/deepnote) (`../deepnote` when available) | +| Kernel, Jupyter, SQL, and language-server runtime | [deepnote-toolkit](https://github.com/deepnote/deepnote-toolkit) (`../deepnote-toolkit` when available) |