feat: context-sensitive completions — cursor-aware filtering & type suggestions

[tnaum-ms]

Step 4.5: Context-Sensitive Completions

Adds cursor-position-aware completion filtering to the documentdb-query language. Instead of showing all operators at every cursor position, completions are filtered based on the semantic context of where the cursor sits in the query expression.

Changes

Cursor context detection (cursorContext.ts)

• Heuristic backward-scanning algorithm detects cursor position: key, value, operator, or array-element
• Pure function — handles incomplete/mid-typing input gracefully
• Field type enrichment via completion store lookup

Context-sensitive filtering

Cursor position	Example	Completions shown
Key	{ | }	Field names + logical operators ($and, $or, $nor)
Value	{ age: | }	Type suggestions + operators + BSON constructors + JS globals
Operator	{ age: { | } }	Comparison operators ($gt, $eq, $in...) with stripped braces
Array element	{ $and: [ | ] }	Same as key position
Unknown/empty	Empty input	Field names + key-position operators

Type-aware value suggestions (typeSuggestions.ts)

When the field BSON type is known from the schema, contextual suggestions appear first (sort prefix 00_):

• boolean → true, false
• number → { $gt: …, $lt: … } range query, { $gte: … }
• string → { $regex: /…/ }, { $regex: /\.com$/ }, ""
• date → ISODate("…"), date range, { $gt: new Date(Date.now() - …) }
• objectid → ObjectId("…")
• array → { $elemMatch: { … } }, { $size: … }
• null → null

Type-aware operator sorting

When the field type is known, operators are sorted by relevance:

• 0_ — Type-relevant (operator's applicableBsonTypes matches the field)
• 1a_ — Comparison operators (universal, most commonly used)
• 1b_ — Other universal operators ($exists, $type, $mod)
• 2_ — Non-matching operators (demoted, not hidden)
• 3_ — BSON constructors (ObjectId, ISODate)
• 4_ — JS globals (Date, Math, RegExp, Infinity)

JavaScript global completions (jsGlobals.ts)

Restored JS globals that were lost when the custom documentdb-query language replaced the built-in Monaco JS worker:

• Constructors: Date (→ new Date($1)), RegExp
• Static methods: Date.now(), Math.floor(), Math.ceil(), Math.round(), Math.min(), Math.max()
• Primitives: Infinity, NaN, undefined

Source: @mongodb-js/shell-bson-parser sandbox scope (the same runtime that executes queries).

Completion knowledge configuration (completionKnowledge.ts)

Centralised domain rules for the completion provider:

• KEY_POSITION_OPERATORS — operators valid only at root/key position ($and, $or, $nor, etc.)
• LABEL_PLACEHOLDER — the … character for completion labels
• INFO_INDICATOR — the ℹ character for descriptions

Field completion improvements

• Selecting a field name now inserts fieldName: | (snippet with cursor at value position)
• Field type shown right-aligned in the completion list via label.description

Validator enhancements

• Unknown function calls → red error: Unknown function 'XyzAbc'. Expected a BSON constructor or a known global.
• Unknown new constructors → red error: Unknown constructor 'Daddddte'.
• Near-miss typos → yellow warning (unchanged): Did you mean 'ObjectId'?
• Previously, unknown identifiers with Levenshtein distance > 2 produced no diagnostic at all

Projection/sort fix

• PROJECTION_COMPLETION_META was ['field:identifier'] returning 0 static entries — projection operators ($slice, $elemMatch, $) and BSON constructors were never shown in project/sort editors. Fixed by adding 'query:projection' and 'bson' to the preset.

Bug fixes

• Fix $gt snippet producing { : value } — $ was interpreted as a Monaco snippet variable
• Fix double-brace insertion for $and/$or at key position
• Fix ISODate snippet using format pattern instead of example date

Refactoring

Extracted monolithic documentdbQueryCompletionProvider.ts into completions/ folder:

• createCompletionItems.ts — main entry, context branching
• mapCompletionItems.ts — operator/field → CompletionItem mapping
• typeSuggestions.ts — type-aware value suggestions
• jsGlobals.ts — JS globals from shell-bson-parser sandbox
• completionKnowledge.ts — curated domain rules
• snippetUtils.ts — snippet text manipulation
• README.md — architecture and sorting documentation

Tests

• 202 tests across 5 test suites — all pass
• 41 cursor context detection tests (complete + incomplete input)
• 95 completion provider tests (context-sensitive filtering, type sorting, field mapping)
• 38 validator tests (syntax errors, typos, unknown identifiers, NewExpression)
• 25 getFilteredCompletions tests
• 3 completion store tests

[Copilot]

Pull request overview

This PR enhances the documentdb-query Monaco language by making completions cursor-context-aware (key/value/operator/array-element) and by adding type-aware value suggestions and JS-global completions, plus associated refactoring and test coverage.

Changes:

• Add heuristic cursor context detection (detectCursorContext) and wire it into the Monaco completion provider to filter/sort suggestions by cursor position.
• Introduce type-aware value suggestions and restore JS global completions used by the @mongodb-js/shell-bson-parser sandbox.
• Fix projection/sort completion presets in documentdb-constants and refactor completion logic into a dedicated completions/ module with extensive new tests.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/webviews/documentdbQuery/registerLanguage.ts	Wires cursor context detection into Monaco completions; adds debug logging.
src/webviews/documentdbQuery/index.ts	Re-exports cursor context utilities.
src/webviews/documentdbQuery/documentdbQueryValidator.ts	Adds errors for unknown calls/constructors and supports NewExpression diagnostics.
src/webviews/documentdbQuery/documentdbQueryValidator.test.ts	Adds/updates tests for unknown identifiers and constructors.
src/webviews/documentdbQuery/documentdbQueryCompletionProvider.ts	Becomes a barrel re-export for the refactored completions module.
src/webviews/documentdbQuery/documentdbQueryCompletionProvider.test.ts	Expands tests for context-sensitive completions, sorting, snippet escaping, and type suggestions.
src/webviews/documentdbQuery/cursorContext.ts	New cursor context detector (heuristic backward scanning).
src/webviews/documentdbQuery/cursorContext.test.ts	New unit tests for cursor context detection across complete/incomplete inputs.
src/webviews/documentdbQuery/completions/createCompletionItems.ts	New context-sensitive completion routing and filtering logic.
src/webviews/documentdbQuery/completions/mapCompletionItems.ts	New mapping utilities for operators/fields with sorting & snippet handling.
src/webviews/documentdbQuery/completions/typeSuggestions.ts	New type-aware value suggestions shown at value position.
src/webviews/documentdbQuery/completions/jsGlobals.ts	New JS global completion items (Date/Math/RegExp/etc.).
src/webviews/documentdbQuery/completions/snippetUtils.ts	New utilities for brace stripping and $ escaping in Monaco snippets.
src/webviews/documentdbQuery/completions/completionKnowledge.ts	New centralized completion rules/constants (key-only operators, placeholders).
src/webviews/documentdbQuery/completions/index.ts	New module barrel exports.
src/webviews/documentdbQuery/completions/README.md	Documents completion architecture and sorting tiers.
packages/documentdb-constants/src/metaTags.ts	Fixes projection/sort preset to include projection operators and BSON constructors.
packages/documentdb-constants/src/getFilteredCompletions.test.ts	Updates tests to validate the new projection preset behavior.
packages/documentdb-constants/src/bsonConstructors.ts	Updates ISODate snippet placeholder to an example timestamp.
.github/copilot-instructions.md	Adds git safety guidance (avoid git add -f, don’t commit planning docs).

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.