Code reference detail
workspace-index.ts
packages/analytical/src/index-store/workspace-index.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]. | ||
| base_ownership | Each base holds its own [ideas_index] store under `<base>/.reqlan/ideas-index.sqlite`. Path keys inside the index are relative to that base root, not the VS Code workspace root. Store path: [application_memory_impl]; per-base engine: [workspace_index] via [base_registry]. | ||
| analytical_package | `packages/analytical` ( `@reqlan/analytical` ) is the shared requirement graph index and analysis layer. It owns the [indexer]: extracts ideas and edges from Langium ASTs into a sql. js SQLite store ( [workspace_index] ), holds Zustand analytical state, and exposes analysers and an analysis API. Headless entry is [analysis_runtime] via `createAnalysisRuntime` / `WorkspaceIndex`. Consumers: [extension_package] ( thin editor adapter ), [mcp_package], [cli_package]. Depends on [language_package]. Published to npm alongside [cli_package]; version graph role: [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]. | ||
| configuration_location | An optional `.reqlan/config.json` may appear under a base's `.reqlan` directory. For a given `.rq` file, the applying base is the nearest ancestor directory that owns a `.reqlan` folder. The applying config is that base's `.reqlan/config.json` when present. If the owning base has no `config.json`, or no owning base is found, defaults from [configuration_import_roots] apply. A child base does not inherit a parent base's config. Implemented by ["../../packages/language/src/reqlan-path-resolve.ts"]. | ||
| configuration_rqignore | done | Each base may define path ignore rules in `.reqlan/.rqignore` using * * gitignore syntax * *. Patterns are relative to the base root ( parent of `.reqlan` ), not the `.reqlan` directory. Owned by `@reqlan/analytical` so the CLI, MCP, and extension share one filter for discovery and indexing walks. Built-in defaults always apply ( dependencies, venvs, build output, VCS / editor stores, `*.db3` / sqlite DBs, `*.secret.rq`, hidden entries, and `.reqlan/` itself ); the on-disk file adds or overrides via the same syntax, including `!` negation. New bases seed `.reqlan/.rqignore` with those defaults ( ["./module/index.rq".rqignore] ). Missing or unreadable `.rqignore` still uses built-in defaults. Location convention: [configuration_location]. Application memory: ["./module/index.rq".application_memory]. | |
| 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. | ||
| index_diagnostics | done | Indexing performance diagnostics: measure and inspect time spent indexing a [indexer.index] base. Timing is persisted in a dedicated * * diagnostic index * * under application memory ( [app_memory.index_diagnostics_store] ), not in `ideas-index.sqlite`, so history survives Clear & rebuild. Surfaces: [index_diagnostics_webview]. Owned by `@reqlan/analytical` for recording; the extension hosts the webview. | |
| index_diagnostics_metrics | done | For each sync / index run on a base, record: - wall-clock * * sum / total duration * * of the pass - * * file count * * ( visited ), skipped-by-mtime count, indexed ( parse / persist attempted ) count, error count - * * average path depth * * of visited files ( segments under the base root ) - per-file * * duration * * and outcome ( `mtime_skip` | `mtime_refresh` | `hash_skip` | `persisted` | `error` ) Runs are attributable to a trigger ( `soft_sync` | `rebuild` | `enqueue` | `stale` ). Instrumentation wraps [workspace_index] soft sync and [indexer.nonblocking_index] single-file paths via [diagnostics_store]. | |
| application_memory | done | Base-local application memory for reqlan tools lives under `<base>/.reqlan/`. The presence of `.reqlan` * * marks * * a directory as a ["../../bases/base.rq".base]; each base owns its own store. Shared by the VS Code extension, ["../../cli/cli_package.rq".cli_package], and MCP ( [mcp_server] ) — not VS Code `globalStorageUri` / extension-private storage. The ideas graph index ( ["../features-graph-analysers.rq".index_ideas] / ["../features-graph-analysers.rq".index_technology] ) persists as `ideas-index.sqlite` inside that directory. Index timing diagnostics persist separately as `index-diagnostics.sqlite` ( [index_diagnostics_store] / ["../features-index-diagnostics.rq".index_diagnostics] ) so rebuilds of the ideas index do not wipe history. Export form defaults ( all formats via ["../features-export.rq".export_webview], including HTML options in ["../features-html-export.rq".html_export_form] ) persist as `export_settings.json` in the same directory ( active base ). Path ignore rules live as `.rqignore` in the same directory ( [rqignore] / [configuration.configuration_rqignore] ). Path resolution is owned by [application_memory_impl] ( `resolveApplicationMemoryPath` ); consumers must use it ( or `REQLAN_INDEX_PATH` override for a single store ) so tools read and write the same store for a given base. Multi-base discovery / registry: ["../../bases/base.rq".multi_base_environment]. Index engine ownership: ["../../indexer/indexer.rq".ownership]. Extension wiring: [analytical_submodule]. Aligns with ["../../cli/cli_package.rq".function_parity]: shared analytical memory, not host-only state. | |
| rqignore | done | `.reqlan/.rqignore` filters which paths discovery and indexing crawl, using gitignore syntax relative to the base root. Owned by [rqignore_impl] in `@reqlan/analytical` so CLI and editor share behaviour. Defaults cover `node_modules/`, virtualenvs, build dirs, VCS / editor stores, database files ( `*.db3`, sqlite ), secrets, and hidden entries; new bases seed the file via create-base. Product configuration statement: [configuration.configuration_rqignore]. | |
| 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"]. | ||
| extension_startup_reliability | done | Reqlan startup must make the activity-bar shell and contributed commands available before optional indexing, parser construction, database initialization, or language-client startup can monopolize the extension host. The implementation contract is [first_paint_contract], [deferred_startup_sequence], [lazy_runtime_dependencies], and [development_bundle_freshness]. Operational diagnosis follows [startup_diagnostics]. [activation.activation_sequence] [activitybar.loading_state] [indexer.nonblocking_index] [build.extension_bundle] | |
| lazy_runtime_dependencies | done | Base discovery must be cheap: - Constructing `WorkspaceIndex` does not construct Langium / Chevrotain services; services are memoized on first parse. - sql. js asm is not parsed as part of `main.cjs`; both index stores dynamically import the generated vendor bundle when a database first opens. - Export / physics source is generated at build time rather than read via extension-runtime URLs. The host bundle consequently fell from approximately 11. 2 MB to 2. 66 MB; sql. js occupies a separate approximately 8. 0 MB lazy vendor bundle. ["../../packages/analytical/src/index-store/workspace-index.ts"] ["../../packages/analytical/src/index-store/sqlite-store.ts"] ["../../packages/analytical/src/index-store/index-diagnostics-store.ts"] ["../../packages/extension/esbuild.mjs"] | |
| 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]. | |
| ownership | The [index] / indexer lives in `packages/analytical` ( `@reqlan/analytical` ). Canonical single-base engine: [workspace_index] ( `WorkspaceIndex` facade ). Sync / idle impl: [workspace_index_sync]; one-file parse + persist: [workspace_index_file]; mtime stale diff: [workspace_mtime]. Multi-base registry: one `WorkspaceIndex` per discovered ["../bases/base.rq".base] under [app_memory_doc.application_memory] ( `<base>/.reqlan/` ). Headless entry: [analysis_runtime] via `createAnalysisRuntime` ( CLI / MCP ) — discovers bases under the resolved root and defaults to the nearest base containing cwd. On-disk store path: [application_memory_impl] under `<base>/.reqlan/` — see [app_memory_doc.application_memory]. |
Reference labels
../../../packages/analytical/src/index-store/workspace-index.ts, ../../packages/analytical/src/index-store/workspace-index.ts, ../packages/analytical/src/index-store/workspace-index.ts, workspace_index