Code reference detail
index-service.ts
packages/extension/src/analytical_submodule/index-store/index-service.ts
| Idea | Status | Tags | Summary |
|---|---|---|---|
| active_base_switch | done | Changing the active base is a * * pointer swap * * onto a per-base `WorkspaceIndex` / store. - Do * * not * * await soft-sync, hard-rebuild, or a full `.rq` walk on the switch call itself. - Host surfaces rebind views to the newly active store ( status snapshot, tables, context panes ) immediately. - If the selected base is not yet ready, show its readiness / progress and * * schedule * * the normal activate catch-up ( open if needed, then one soft sync ) fire-and-forget — same path as ["../indexer/indexer.rq".triggers] / ["../extension/features-graph-analysers.rq".indexing_trigger_open], not a special switcher rebuild. - Idle staleness checks also heal unopened / never-synced bases ( they cannot mtime-diff without a store ). - `activateAll` isolates open failures so one bad base cannot leave siblings stranded in `uninitialized`. - Editor-follow must not overwrite a user pin on the same refresh that applies the selection. Surfaces: activity bar ["../extension/module/activitybar-panels/workspace.rq".workspace_base_picker], Ideas Summary ["../extension/module/ideas_summary/base-scope.rq".ideas_summary_base_scope]. Implemented by [editor_index_adapter] ( `setActiveBaseId` / `scheduleBaseCatchUp` ); engine: [base_registry] `ensureBaseReady`, [workspace_index] `ensureReady`. | |
| base | A base is a container for ideas, ideasets, and files. It forms the boundary of one ideas graph and is consumed by the CLI and the extension. Marker: a directory is a base only when it owns a `.reqlan` folder ( [app_memory_doc.application_memory] ). No bare workspace folder is treated as a base until the user creates `.reqlan` there ( [create_base_onboarding] ). Aligns with [ontology_base]. Discovery and registry: [base_discovery], [base_registry]. Marker path helpers: [application_memory_impl]. | ||
| create_base_onboarding | When discovery finds * * zero * * bases under any VS Code workspace folder ( root or child ), the extension prompts the user to create a reqlan base at the workspace-folder root. Do not auto-create `.reqlan`. Command `reqlan.createBase` creates `<folder>/.reqlan/` ( empty directory is a valid marker ), rediscovers, and activates indexing for that base. With multiple workspace folders and no bases, prompt against the first folder. Headless create-base helper: [create_base_impl] ( also used by CLI `init` ). | ||
| implied_context | The * * active base * * for editor-adjacent surfaces is the longest-matching base root that contains the focused file path. When no file is focused, the last selected base ( Ideas Summary switcher / activity bar ) or the first discovered base is used. Context, local graph, and analysers bind to the active base's index — not a merged global graph. User / explicit pin is a pointer swap only — [active_base_switch]. Core selection: [base_discovery] ( `baseForPath` / `selectDefaultBase` ); editor pin / switch: [editor_index_adapter]. | ||
| multi_base_environment | Analytical features are multibase aware via [base_registry]: one [ideas_index] / `WorkspaceIndex` per base, isolated catalogs ( no cross-base idea-id collision ). Surfaces list all discovered bases; Ideas Summary and context panes scope to the active / selected base ( [active_base_switch] ). Cross-base reference resolution and merged graphs are out of scope for the first multi-base pass. Headless ( CLI / MCP ) selects one base via [analysis_runtime]; the editor hosts [editor_index_adapter]. | ||
| cli_package | `packages/cli` ( `@reqlan/cli` ) is the Clipanion CLI published to npm as the `reqlan` ( and `rq` ) binary. It depends on `@reqlan/analytical` for base analysis and `@reqlan/language` for single-file parse. Entry: ["../../packages/cli/src/main.ts"]. Analysis commands reuse [application_memory] ( `<base>/.reqlan` ) and the analytical ["../indexer/indexer.rq".index] so the CLI shares the ideas index with the extension and MCP. | ||
| init | done | The cli should be able to initialise a new [base]. Creates `<path>/.reqlan/` ( empty directory is a valid marker ), matching [create_base_onboarding]. Headless helper lives in `@reqlan/analytical` so CLI and extension share one create-base path. | |
| extension_package | `packages/extension` ( npm `reqlan-extension` ) is the editor product per [distribution.extension_package]. It registers `.rq` language support, TextMate grammars, starts the language client, and owns activity bar, Ideas Summary, chat, skills, and mutation hooks. Ideas index engine lives in [analytical_package] / [indexer]; the extension only hosts a thin VS Code adapter ( [editor_index_adapter] ) for watchers and UI. Host entry: [extension_main]. LSP process entry: [language_server_main]. Depends on [language_package] and [analytical_package]. Follows [extension_architecture.event_driven] and [extension_architecture.state_machine_mindset] ( zustand ) for JS state. This is the one Marketplace / Open VSX shippable; see [package_versioning]. | ||
| ideas_index | The ideas index is built and maintained by the [indexer] in [analytical_package]. Path: parse with [language_package] → extract ideas / edges → SQLite via [workspace_index]. Application memory: each [bases.base] holds SQLite under `<base>/.reqlan/` ( shared by extension, [cli_package], and [mcp_package] ) — see ["./extension/module/index.rq".application_memory]. Multi-base: a BaseRegistry owns one [workspace_index] per discovered base; the extension adapter routes file events to the owning base. In the editor, [editor_index_adapter] watches `**\*.rq` and forwards changes to the owning base's [workspace_index]; it serves UIs, commands, chat, and analysers. Headless ( MCP / CLI ) uses [analysis_runtime] ( nearest base containing cwd when several exist ). Capability requirements: [graph_analysers.index_ideas], [graph_analysers.index_technology], and sibling analysers in that file. Triggers: [indexer.triggers] and ["./extension/module/index.rq".idea_index_triggers]. | ||
| runtime_topology | Two Langium runtimes share [language_package] but not one process. - LSP process: live `.rq` editing intelligence via [language_server_main]. - Analytical [workspace_index] ( extension host via [editor_index_adapter], MCP / CLI via [analysis_runtime] ): full-workspace graph for tables, local graph, chat, MCP. Editor ↔ extension host: VS Code APIs and webview postMessage. Editor ↔ LSP: vscode-languageclient IPC. Attribute catalog and similar custom notifications may sync from the index side into the LSP for completions. Stack sketch: [development_core.stack]. | ||
| scope | These requirements describe the cross-package system architecture of the reqlan monorepo: language definition, language server, ideas index, editor product, and companion tools. They are distinct from [extension_scope.scope], which bounds only the VS Code extension and LSP product surface. Language concepts live in [ontology]; syntax truth lives in [syntax]; editor module contracts live under extension / module. Grouped as [workspace_packages], [language_runtime], and [product_map]. | ||
| index_ideas | Each ["../bases/base.rq".base] maintains an index of its ideas for fast lookup and navigation ( ["../indexer/indexer.rq".index] ). The index should update incrementally as. rq files change within that base ( nested child bases excluded ). Persistence lives in [application_memory] per base, shared with CLI and MCP — not VS Code extension storage. Engine ownership: [workspace_index] in `@reqlan/analytical`; multi-base via BaseRegistry; editor watches via [editor_index_adapter]. | ||
| index_technology | The [index_ideas] graph database is sql. js SQLite, aligned with [graph_design]. On-disk location is [application_memory] ( `<base>/.reqlan/ideas-index.sqlite` ), not `context.globalStorageUri`. Implementation: [application_memory_impl], [workspace_index], headless [analysis_runtime] for CLI / MCP, and [editor_index_adapter] for the VS Code host. | ||
| indexing_trigger_auto | done | When the editor host is idle, run a * * background staleness check * * — not a reindex and not a soft full sync UI pass. Philosophy: computationally cheap. Load document mtimes in * * one * * SQLite read, compare each file's FS mtime in memory, and only then index mismatched or new files; drop deleted docs in one batched delete. A single MAX ( mtime ) watermark is not sufficient ( one file can get newer while another gets older ). If nothing is stale: no state transition, no progress UI, no parse. If some files are stale: index * * only those files * * under ["../indexer/indexer.rq".nonblocking_index]. Schedule after a quiet period with no index activity; prefer running when the window is unfocused; defer or cancel if the user becomes active again. Extension host only ( [editor_index_adapter] ); CLI / MCP have no idle loop ( they sync on activate / command ). | |
| refactor_changes | On rename, move, or delete of files or symbols, the extension should update the idea index, import statements, embedded file references, comment references, and other idea references that are affected. The index should be resilient to duplication, particularly when ideas move between files: the old hosting file URI must be cleared before or when the destination is reindexed. [refactor_file_moves] [refactor_symbol_rename] [refactor_symbol_move] [refactor_symbol_delete] Implemented by ["../../packages/analytical/src/index-store/workspace-index.ts"], ["../../packages/extension/src/analytical_submodule/index-store/index-service.ts"], ["../../packages/language/src/reqlan-idea-refactor.ts"], and ["../../packages/extension/src/mutation_hooks_module/register-file-mutation-hooks.ts"]. | ||
| consumption | Consumers of the analytical [index]: - [extension] — thin VS Code adapter [editor_index_adapter] ( file watchers, Uri conversion, UI status ) - CLI ( `["../cli/cli_package.rq".cli_package]` ) and MCP — headless [analysis_runtime] The extension does not own the indexing engine; it only hosts the adapter. | ||
| index | The ideas graph indexer: parse `.rq` with `@reqlan/language`, extract ideas / edges, persist to sql. js SQLite. Owned by [ownership]; consumed per [consumption]. | ||
| nonblocking_index | done | Index sync must stay non-blocking for the host UI ( notably [activity_bar_doc.activity_bar] and [workspace_pane_doc.workspace_loading] ). Editor startup is gated by ["../extension/activation.rq".first_paint_startup]; discovering a base must not construct Langium services, which are initialized lazily on the first parse. While syncing, surface progress — state, processed / total, and the current file — in [workspace_pane_doc.workspace_pane] and [ideas_summary_doc.index_panel]. In-flight sync must be cancellable from those surfaces; cancel keeps already-indexed rows and returns the index to ready. Incremental behaviour ( see also [graph_analysers.indexing_incrementality] ): - Single-file create / change / delete via watchers indexes only that file — never a full base walk. - Soft full sync ( `syncWorkspace` / Refresh ) skips parse + persist when the file's mtime matches the value stored on the documents row. - Hard refresh ( `clearAndRebuildIndex` / Clear & rebuild ) wipes the store and reindexes every file. Implemented by [workspace_index]; editor adapter [editor_index_adapter]. | |
| triggers | Index refresh behaviour ( capability detail in [graph_analysers] ): - [graph_analysers.indexing_incrementality] / [nonblocking_index] — incremental where possible - [graph_analysers.indexing_trigger_filesave] / [app_memory_doc.idea_index_triggers] — on `.rq` file change - [graph_analysers.indexing_trigger_manual] — manual reindex commands - [graph_analysers.indexing_trigger_open] — one soft sync after the activity-bar first-paint gate - [graph_analysers.indexing_trigger_auto] — idle background mtime staleness check ( cheap; not a full reindex ) Editor watches + idle scheduler: [editor_index_adapter]; headless syncs on runtime activate. |
Reference labels
../../packages/extension/src/analytical_submodule/index-store/index-service.ts, ../packages/extension/src/analytical_submodule/index-store/index-service.ts, editor_index_adapter