Code reference detail
reqlan-document-link-provider.ts
packages/language/src/reqlan-document-link-provider.ts
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| comment_reference_resolution_error_state | done | [comment_reference_resolution_error] The language server must share one resolution result for clickable links and the error underline. Resolve comment references once against the loaded idea index, then reuse that result for both consumers. When you create an idea that matches a comment reference, the language server must clear the underline and the missing-idea message. Resolution and the index should be performed once and shared between consumers. | 0.053 | |
| references_in_functional_code_comments | done | Comments in functional code should be able to reference reqlan ideas using the an `rq:` prefixed to an idea: `rq:[idea]` as demonstrated in python, but actually applicable to any language's comment context: Editor hosts are every language except [comment_reference_language_blocklist]. With the rust language server, a resolved `rq:[…]` site is Ctrl + click navigable via go-to-definition. File document links stay out of the editor ( ["../syntax/features-syntax-highlighting.rq".editor_reference_activation] ). Comment `rq:[…]` sites use TextMate `meta.link.reqlan markup.underline` so the resting editor shows they are link-shaped ( [comment_reference_resting_underline] ). After that goto, Alt + Left restores the comment-host caret ( [comment_reference_navigate_back] ). Missing ideas keep the error underline and have no definition target. Relates to ["../../mutation/refactor_support.rq".comment_reference_refactor_support], [comment_reference_import_root_alias], ["../support/language-server-rust.rq".language_server_rust], ["../syntax/features-syntax-highlighting.rq".editor_reference_activation]. | 0.300 | |
| file_reference_errors | done | If a [file_reference] is not found, is broken, or cannot be resolved, the language server must show an underline. Do not show the underline when [comment_reference_ignore] ( `//rq-ignore-error` ) is on the line before. Missing files: error underline, no document link. Do not underline examples inside [inline_code] or ["../../../language/syntax.rq".code_snippets]. Empty files and files with parse errors: warning underline; the document link stays. Import-root aliases such as `@/` resolve the same way as ["../../../core_analysis/check.rq".check] and ["../../../language/imports.rq".configuration_import_root_alias]. Related: [general_errors], [comment_reference_resolution_error], [inline_code], ["./features-imports.rq".import_does_not_exist_error], ["../syntax/features-syntax.rq".file_references]. | 0.092 | |
| general_errors | error messages should be deliberate and developer friendly. recommendations should be offerred where appropriate. | 0.083 | ||
| missing_reference_colour_sequence | done | Paint links and errors in two steps. The hot path paints same-file names and import targets ( [outbound_one_hop] ). The background pass paints qualified-reference idea lines ( [lazy_features_after_outbound] ). Related: [unresolved_reference_diagnostics], [reference_rendering], [file_reference_errors], [import_does_not_exist_error]. Hot path: - URL references: document link, no error. - Wildcard references: document link, no error underline for zero matches. - Import path missing: error underline, no document link. - Imported idea present: document link to that idea line. - Imported idea missing: error underline, no document link. - Same-file idea missing: error underline, no document link. - Qualified reference: document link to the file from the path token. Do not underline a missing idea yet. Background pass: - Qualified idea present: document link to that idea line. - Qualified idea missing: error underline, and remove the document link. - Drop a false missing-idea error only for the range that this pass confirms. Keep a different missing name on the same line. | 0.153 | |
| node_engine_open_path | done | This idea applies when `reqlan.languageServer.engine` is `node`. The default engine is [language_server_rust]. The node server populates a Langium AST for the open buffer at `DocumentState.Parsed`. Later builder phases attach scopes, links, and diagnostics. They must not replace that AST. Parsed-time handlers must not read Langium `.ref`. Use `$refText`, the symbolic extract, or `peekResolvedRef` until `ComputedScopes`. The linker must not resolve a cross-reference while that document is below `ComputedScopes`. Do not log the Langium warning. Do not store a failed link. Scope lookup, code lens, completion, and idea summaries use `readResolvedRef` or `peekResolvedRef` until that phase. When another `.rq` file changes, relink this document when the index says it is affected, when comment references name that file, or when this document's outbound targets include the changed URI. Do not relink every document that still has a linker error. Workspace load parses at most 8 files at a time ( [workspace_parse_concurrency] ). `fileIdeasCache` and `importPathCache` drop a URI when that document is removed ( [scope_cache_release] ). Related: [open_file_algorithm], [ast_lifecycle]. | 0.133 | |
| complementary_information_rendering | The extension should render computed information inline in the editor as complementary text. Complementary rendering should include resolved references and optionally indirect references behind a toggle. Complementary rendering should not mutate source files unless the user explicitly applies a change. | 0.040 | ||
| non_web_reference_navigation | done | Non-web references ( idea brackets / wikilinks, local file paths, import paths ) must be Ctrl + click navigable via document links and / or go-to-definition. Built-in http ( s ) link detection is not enough. The rust engine builds same-file links and import-target links on the open path ( ["../../../language/syntax.rq".open_file_reference_sequencing], ["../support/open-file-sequencing.rq".outbound_one_hop] ). When the engine is node, idea underlines use the path-local Rust extract ( ["../../../indexer/indexer.rq".local_symbolic_analysis] ), and go-to-definition uses Langium when the idea ref is already linked. Qualified-reference idea lines follow ["../support/open-file-sequencing.rq".lazy_features_after_outbound]. Related: [reference_document_links], [reference_goto_definition_speed], [reference_underline_syntax_align], ["../../../language/syntax.rq".open_file_reference_sequencing]. | 0.163 | |
| reference_document_links | done | Bracket and wikilink idea references — both same-file and cross-file — must emit a document link so the editor can follow them the same way as file-path references. Editor activation is [editor_reference_activation]. All resolved `LocalReference` and `QualifiedReference` idea / ideaset tokens should emit links targeting the declaration name, regardless of whether the target lives in the same file or an imported one. Namespace-import alias tokens ( `[alias]` → file ) keep their existing file-target link. Each link must include a `target` and a `tooltip` so VS Code does not show " Loading... ". Implemented by ["../../../../packages/language/src/reqlan-file-link-resolver.ts"] ( `resolveIdeaReferenceLinks`, `collectFileLinks` ) and ["../../../../packages/language/src/reqlan-document-link-provider.ts"]. | 0.124 | |
| unresolved_reference_diagnostics | in-progress | Unresolved idea references must report a linking error diagnostic. A same-file miss and an import-target miss have an error and no document link. A qualified reference may link to its file before the idea line is confirmed. After confirmation, a missing idea has an error and no document link ( ["../support/open-file-sequencing.rq".missing_reference_colour_sequence] ). A false idea link looked like a happy reference while Ctrl + click could not navigate. Missing file references stay on ["./features-syntax.rq".file_references] / ["../support/language-server-errors.rq".file_reference_errors] ( error, no document link ). Related: [reference_rendering], [non_web_reference_navigation]. | 0.117 | |
| file_references | A file reference should act as a link in the editor. If the target file is empty or has a parse error, the link should remain available and clickable, but should show a warning underline. If the target file is missing, show an error underline and do not create a document link — see ["../support/language-server-errors.rq".file_reference_errors]. Same-file and imported idea bracket references use the same editor activation as file targets. See ["./features-syntax-highlighting.rq".editor_reference_activation]. Implemented by ["../../../../packages/language/src/reqlan-file-link-resolver.ts"], ["../../../../packages/language/src/reqlan-document-link-provider.ts"], ["../../../../packages/language/src/reqlan-definition-provider.ts"], and ["../../../../packages/language/src/reqlan-validator.ts"]. | 0.118 | ||
| syntax_features | The extension should provide language support for. rq files via the lsp. Syntax features should cover ideas, ideasets, imports, references, attributes, comments, and lists. Broken imports and references should be validated and reported in the editor. Go-to-definition and find-references should work for ideas, imports, and cross-file links. Find-references is served by ["../support/language-server-rust.rq".language_server_rust] ( `textDocument/references` ). Autoformatting should be supported for. rq files. | 0.046 | ||
| definition | The indexer should live in the [core_analysis] module. On-disk schema: [sqlite_schema.ideas_index_sqlite] and [diagnostics_schema.diagnostics_sqlite]. Layout and WAL sidecars: [sidecars.reqlan_directory_layout]. Consumers: [consumers.index_consumers] ( extends [consumption] ). Sequencing and triggers: [sequencing.index_sequencing] ( extends [triggers] ). Cache reuse opportunities: [cache_reuse.index_cache_reuse]. | 0.040 | ||
| local_symbolic_analysis | done | Open-file symbolic analysis must run in Rust on one file only. Input: file URI plus source text ( and optional import-root mappings ). Output: ideas in that file, import binding names in that file, outbound edges with UTF-8 source byte spans, and same-file inbound backlinks ( edges whose target is an idea declared in this file ). Import binding names let a qualified reference name an import alias ( ["../core_analysis/check.rq".check_qualified_missing_idea] ). LSP document-link and error underlines must convert those spans to UTF-16 ( ["../extension/language/syntax/features-syntax-highlighting.rq".reference_underline_syntax_align] ). Cross-file inbound still comes from SQLite via ["./cache-reuse.rq".unify_inbound_indexes]. Do not read SQLite. Do not walk other workspace documents. Do not load an idea catalog. The open-buffer model is ["../extension/language/support/open-file-sequencing.rq".ast_lifecycle]. The hot path parses this buffer once. It does not run this extract as a second parse. Import-target confirmation is a separate depth-1 parse ( ["../extension/language/support/open-file-sequencing.rq".outbound_one_hop] ). That parse is not this extract. The language server caches the open buffer by URI plus text fingerprint ( ["../extension/language/support/open-file-sequencing.rq".open_file_hot_path] ). Wildcard forms stay one `wildcard_reference` pattern edge ( unresolved ); sync still expands them later via [wildcard_reference_edges]. Flag: `ExtractOptions.local_symbolic` forces an empty candidate list. CLI: ["../cli/cli_package.rq".commands] `analyse --local-symbolic <file>`. Sidebar: ["../extension/local-context/activitybar-panels/current_context_scope.rq".reference_lists_pane] merges live same-file inbound / outbound with indexed refs ( [local_symbolic_sidebar] ). Related: ["../language/syntax.rq".open_file_reference_sequencing], [index], ["./cache-reuse.rq".unify_inbound_indexes]. | 0.387 | |
| import_keywords | The keywords import, from, and as are reserved for import statements. Import keywords may also appear as ordinary words in idea body text when not at statement start. | 0.047 | ||
| wildcard_references | done | Qualified path + idea-pattern references match multiple ideas across files. Surface forms: bracket `[…]` and wikilink `[[…]]` ( same `WildcardReference` target ). Path is a quoted string that may include shell-style globs ( `*`, `**`, `?` ) and `@/` import-root aliases ( [configuration_import_root_alias] ). Relative globs resolve against the defining document directory; `.` / `..` segments are collapsed before matching. Idea pattern is an unquoted `WILDCARD_NAME` that must contain at least one `*` or `?` Exact quoted-path plus idea stays ["./syntax.rq".reference_qualified]. Matching uses anchored globs ( not full JS regex ): path `*` is one segment, `**` crosses segments; idea `*` / `?` match within the idea name. Zero matches produce a warning diagnostic. One match also produces a warning — a wildcard is for many ideas; use a concrete ["./syntax.rq".reference_qualified] when only one idea matches ( ["../core_analysis/check.rq".check_wildcard_one] ). Path segment `/**/` must not be lexed as an empty block comment — see ["./syntax.rq".comments]. Lexer note: `ID` is a prefix of many wildcard names ( `import_` vs `import_*` ); the token builder sets `ID.LONGER_ALT = WILDCARD_NAME` so `import_*` is one token. Body prose `*` tokens are accepted via `WILDCARD_NAME` in PlainText so ordinary `*` characters still parse. Without that longer-alt, a live wildcard inside a block body can fail Idea recovery and leave later top-level ideas unindexed ( soft mtime sync will not rebuild until the `.rq` file changes ). Navigation does not emit N LocationLinks. A document-link click opens `reqlan.openWildcardReference` with `{ pathPattern, ideaPattern, fromUri }` ( see [wildcard_references_webview] ). Go-to-definition does not open that panel. Indexing fans out per ["../indexer/indexer.rq".wildcard_reference_edges] ( owned under ["../indexer/indexer.rq".index] ): native extract writes one `wildcard_reference` edge per catalog match; empty catalog / zero matches → one unresolved edge of that kind labeled with the pattern text. ["../core_analysis/check.rq".check] handles 0 - match and 1 - match fan-out through ["../core_analysis/check.rq".check_wildcard_zero] and ["../core_analysis/check.rq".check_wildcard_one] ( ["../core_analysis/check.rq".check_wildcard_sparse] ). Ideas Summary graph toggles those edges via ["../extension/workspace-summary/ideas_summary/graphical_graph.rq".wildcard_refs_toggle]. The server can answer `reqlan/wildcardReferenceAt`. Go-to-definition does not call it. Related: ["./syntax.rq".reference_embedding], ["./syntax.rq".reference_brackets], ["./syntax.rq".reference_wikilink], ["../indexer/indexer.rq".wildcard_reference_edges], ["../core_analysis/check.rq".check_wildcard_sparse], ["../core_analysis/check.rq".check_wildcard_zero], ["../core_analysis/check.rq".check_wildcard_one]. Illustrative forms ( fenced so this file does not embed live wildcards ): | 0.486 | |
| attribute_namespacing | done | A bracket link `[idea.attribute]` targets one attribute of that idea. The first name is the idea name. The second name is the attribute name. The grammar types that name as an attribute or an idea declaration. `[attribute_namespacing.example]` targets the `example` attribute of this idea. The form `[ideaset.member]` still targets an ideaset member. See [references_to_subidea]. The editor opens the attribute when the first name is an idea. The editor reports an error when that idea has no attribute with the second name. The link target is only that attribute on that idea. HTML export uses the same link form. The export link opens that attribute on the idea page. See [attribute_namespacing.example]. Related: [reference_brackets], [attribute_marker], ["../core_analysis/html_export.rq".html_export_internal_links]. | 0.129 | |
| file_suffix | Reqlan requirement documents use the. rq file suffix. | 0.052 |
Reference labels
"../../../../packages/language/src/reqlan-document-link-provider.ts", "../../packages/language/src/reqlan-document-link-provider.ts", ../../../../packages/language/src/reqlan-document-link-provider.ts, ../../packages/language/src/reqlan-document-link-provider.ts