feature: shell integration

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
 # GitHub Copilot Instructions for vscode-documentdb
 
-VS Code Extension for Azure Cosmos DB and MongoDB. TypeScript (strict mode), React webviews, Jest testing.
+VS Code Extension for Azure Cosmos DB and the MongoDB API. TypeScript (strict mode), React webviews, Jest testing.
 
 ## Critical Build Commands
 
@@ -178,6 +178,22 @@ For Discovery View, both `treeId` and `clusterId` are sanitized (all `/` replace
 
 See `src/tree/models/BaseClusterModel.ts` and `docs/analysis/08-cluster-model-simplification-plan.md` for details.
 
+## Terminology
+
+This is a **DocumentDB** extension that uses the **MongoDB-compatible wire protocol**.
+
+- Use **"DocumentDB"** when referring to the database service itself.
+- Use **"MongoDB API"** or **"DocumentDB API"** when referring to the wire protocol, query language, or API compatibility layer.
+- **Never use "MongoDB" alone** as a product name in code, comments, docs, or user-facing strings.
+
+| ✅ Do                                                | ❌ Don't                         |
+| ---------------------------------------------------- | -------------------------------- |
+| `// Query operators supported by the DocumentDB API` | `// MongoDB query operators`     |
+| `// BSON types per the MongoDB API spec`             | `// Uses MongoDB's $match stage` |
+| `documentdbQuery` (variable name)                    | `mongoQuery`                     |
+
+This applies to: code comments, JSDoc/TSDoc, naming (prefer `documentdb` prefix), user-facing strings, docs, and test descriptions.
+
 ## Additional Patterns
 
 For detailed patterns, see:

.github/workflows/main.yml

@@ -55,6 +55,9 @@ jobs:
             - name: 📦 Install Dependencies (npm ci)
               run: npm ci --prefer-offline --no-audit --no-fund --progress=false --verbose
 
+            - name: 🔨 Build Workspace Packages
+              run: npm run build --workspaces --if-present
+
             - name: 🌐 Check Localization Files
               run: npm run l10n:check
 

.gitignore

@@ -1,6 +1,9 @@
 ## Ignore Visual Studio temporary files, build results, and
 ## files generated by popular Visual Studio add-ons.
 
+/docs/analysis/
+/docs/plan/
+
 # User-specific files
 *.suo
 *.user
@@ -157,6 +160,9 @@ PublishScripts/
 **/packages/*
 # except build/, which is used as an MSBuild target.
 !**/packages/build/
+# Include our monorepo packages at the root
+!/packages/
+!/packages/**
 # Uncomment if necessary however generally it will be regenerated when needed
 #!**/packages/repositories.config
 # NuGet v3's project.json files produces more ignoreable files
@@ -268,6 +274,7 @@ dist
 stats.json
 *.tgz
 *.zip
+*.tsbuildinfo
 
 # Scrapbooks
 *.mongo

jest.config.js

@@ -1,11 +1,17 @@
 /** @type {import('ts-jest').JestConfigWithTsJest} **/
 module.exports = {
-    testEnvironment: 'node',
-    testMatch: ['<rootDir>/src/**/*.test.ts'],
-    transform: {
-        '^.+.tsx?$': ['ts-jest', {}],
-    },
     // Limit workers to avoid OOM kills on machines with many cores.
     // Each ts-jest worker loads the TypeScript compiler and consumes ~500MB+.
     maxWorkers: '50%',
+    projects: [
+        {
+            displayName: 'extension',
+            testEnvironment: 'node',
+            testMatch: ['<rootDir>/src/**/*.test.ts'],
+            transform: {
+                '^.+\\.tsx?$': ['ts-jest', {}],
+            },
+        },
+        '<rootDir>/packages/schema-analyzer',
+    ],
 };

l10n/bundle.l10n.json

@@ -721,7 +721,6 @@
   "No matching resources found.": "No matching resources found.",
   "No node selected.": "No node selected.",
   "No parent folder selected.": "No parent folder selected.",
-  "No properties found in the schema at path \"{0}\"": "No properties found in the schema at path \"{0}\"",
   "No public connectivity": "No public connectivity",
   "No result returned from the MongoDB shell.": "No result returned from the MongoDB shell.",
   "No results found": "No results found",

package.json

@@ -46,6 +46,9 @@
     "type": "git",
     "url": "https://github.com/microsoft/vscode-documentdb"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "main": "./main",
   "l10n": "./l10n",
   "activationEvents": [
@@ -55,8 +58,9 @@
     "onUri"
   ],
   "scripts": {
+    "prebuild": "npm run build --workspaces --if-present",
     "build": "tsc",
-    "clean": "git clean -dfx",
+    "clean": "rimraf out dist coverage && npm run clean --workspaces --if-present",
     "compile": "tsc -watch",
     "package": "run-script-os",
     "package:win32": "npm run webpack-prod && cd dist && npm pkg delete \"scripts.vscode:prepublish\" && npx vsce package --no-dependencies --out ../%npm_package_name%-%npm_package_version%.vsix",
@@ -67,9 +71,10 @@
     "lint": "eslint --quiet .",
     "lint-fix": "eslint . --fix",
     "prettier": "prettier -c \"(src|test|l10n|grammar|docs)/**/*.@(js|ts|jsx|tsx|json)\" \"./*.@(js|ts|jsx|tsx|json)\"",
-    "prettier-fix": "prettier -w \"(src|test|l10n|grammar|docs)/**/*.@(js|ts|jsx|tsx|json)\" \"./*.@(js|ts|jsx|tsx|json)\"",
+    "prettier-fix": "prettier -w \"(src|test|l10n|grammar|docs|packages)/**/*.@(js|ts|jsx|tsx|json)\" \"./*.@(js|ts|jsx|tsx|json)\"",
     "pretest": "npm run build",
     "test": "vscode-test",
+    "prejesttest": "npm run build --workspaces --if-present",
     "jesttest": "jest",
     "update-grammar": "antlr4ts -visitor ./grammar/mongo.g4 -o src/documentdb/grammar",
     "webpack-dev": "rimraf ./dist && npm run webpack-dev-ext && npm run webpack-dev-wv",
@@ -165,6 +170,7 @@
     "@trpc/client": "~11.10.0",
     "@trpc/server": "~11.10.0",
     "@vscode/l10n": "~0.0.18",
+    "@vscode-documentdb/schema-analyzer": "*",
     "antlr4ts": "^0.5.0-alpha.4",
     "bson": "~7.0.0",
     "denque": "~2.1.0",

packages/schema-analyzer/README.md

@@ -0,0 +1,43 @@
+# @vscode-documentdb/schema-analyzer
+
+Incremental JSON Schema analyzer for DocumentDB API and MongoDB API documents. Processes documents one at a time (or in batches) and produces an extended JSON Schema with statistical metadata — field occurrence counts, BSON type distributions, min/max values, and array length stats.
+
+> **Note:** This package is not yet published to npm. We plan to publish it once the API stabilizes. For now, it is consumed internally via npm workspaces within the [vscode-documentdb](https://github.com/microsoft/vscode-documentdb) repository.
+
+## Overview
+
+The `SchemaAnalyzer` incrementally builds a JSON Schema by inspecting DocumentDB API / MongoDB API documents. It is designed for scenarios where documents arrive over time (streaming, pagination) and the schema needs to evolve as new documents are observed.
+
+Key capabilities:
+
+- **Incremental analysis** — add documents one at a time or in batches; the schema updates in place.
+- **BSON type awareness** — recognizes BSON types defined by the MongoDB API (`ObjectId`, `Decimal128`, `Binary`, `UUID`, etc.) and annotates them with `x-bsonType`.
+- **Statistical extensions** — tracks field occurrence (`x-occurrence`), type frequency (`x-typeOccurrence`), min/max values, string lengths, array sizes, and document counts (`x-documentsInspected`).
+- **Known fields extraction** — derives a flat list of known field paths with their types and occurrence probabilities, useful for autocomplete and UI rendering.
+- **Version tracking & caching** — a monotonic version counter enables efficient cache invalidation for derived data like `getKnownFields()`.
+
+## Usage
+
+```typescript
+import { SchemaAnalyzer } from '@vscode-documentdb/schema-analyzer';
+
+// Create an analyzer and feed it documents
+const analyzer = new SchemaAnalyzer();
+analyzer.addDocument(doc1);
+analyzer.addDocuments([doc2, doc3, doc4]);
+
+// Get the JSON Schema with statistical extensions
+const schema = analyzer.getSchema();
+
+// Get a flat list of known fields (cached, version-aware)
+const fields = analyzer.getKnownFields();
+```
+
+## Requirements
+
+- **Node.js** ≥ 18
+- **mongodb** driver ≥ 6.0.0 (peer dependency)
+
+## License
+
+[MIT](../../LICENSE.md)

packages/schema-analyzer/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} **/
+module.exports = {
+    testEnvironment: 'node',
+    testMatch: ['<rootDir>/test/**/*.test.ts'],
+    transform: {
+        '^.+\\.tsx?$': ['ts-jest', {}],
+    },
+};

packages/schema-analyzer/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@vscode-documentdb/schema-analyzer",
+  "version": "1.0.0",
+  "description": "Incremental JSON Schema analyzer for DocumentDB API / MongoDB API documents with statistical extensions",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "test": "jest --config jest.config.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/vscode-documentdb",
+    "directory": "packages/schema-analyzer"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "mongodb": ">=6.0.0"
+  },
+  "dependencies": {
+    "denque": "~2.1.0"
+  }
+}