Code reference detail
register-comment-reference-links.ts
packages/extension/src/extension/register-comment-reference-links.ts
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| configuration_import_roots | `importRoots` is an optional array of alias-to-directory mappings in `.reqlan/config.json`. Each mapping has: - `alias` ( required non-empty string ): prefix before `/` in aliased import paths. - `root` ( optional non-empty string ): directory for that alias. A relative `root` resolves against the base root ( the parent of `.reqlan` ), not against the `.reqlan` directory. An absolute path or `file://` URI is used as that alias' import-root directory directly. When `root` is omitted for a mapping, that alias uses the workspace folder that contains the `.rq` file. When `importRoots` is omitted, empty, or has no valid entries, the default is one mapping with alias `importRootAlias` from ["../../../packages/analytical/src/core/defaults.json"] and no explicit root. When several aliases could match a path, the longest alias wins. Invalid or unreadable JSON, and a non-array `importRoots` value, fall back to defaults ( or no loaded config for discovery, then defaults at resolve time ). Language path forms and `@/` shorthand: ["../../language/imports.rq".import_paths] and ["../../language/imports.rq".configuration_import_root_alias]. Comment references in source files use the same mappings: ["../language/comment-references/functional-code-comment-references.rq".comment_reference_import_root_alias]. Schema: [configuration_schema_file]. Applying file discovery: [configuration_location]. Editor completion of aliased import paths: ["../language/syntax/features-syntax.rq".code_completion]. | 0.167 | ||
| 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. | 0.190 | ||
| comment_reference_import_root_alias | done | Qualified comment references use the same path forms as imports, including import-root aliases such as `@/`. `rq:["@/path/relative/to/import/root.rq".idea]` resolves against the alias's import-root directory ( workspace folder by default ), not the source file directory. `@reqs` without a following `/` is not an alias. Configured aliases and roots follow ["../../../language/imports.rq".configuration_import_root_alias] and ["../../host/configuration.rq".configuration_import_roots]. The language server applies this when resolving comment references in `.rq` files. The extension applies the same core resolver for `rq:[…]` links in non- `.rq` source. Related: ["../../../language/syntax.rq".comment_reference], [references_in_functional_code_comments], ["../../../language/imports.rq".import_paths]. | 0.235 | |
| comment_reference_language_blocklist | done | Comment rq editor features ( goto, diagnostics, ignore actions, navigate-back origin tracking ) apply to every language except a small blocklist. The blocklist is `reqlan` plus non-source editor buffers ( log, search-result, SCM input, git commit / rebase, github-issues ). The rust language client uses a file-scheme document selector and skips sync for blocklisted languages. TextMate resting underline injects into a wide `injectTo` scope list ( best-effort; goto still works without a matching grammar scope ). Related: [references_in_functional_code_comments], [comment_reference_resting_underline], ["../../../language/syntax.rq".comment_reference]. | 0.178 | |
| 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 | |
| comment_backlink_sequence | in-progress | `rq:[idea]` and `rq:["path".idea]` in code comments use one resolution for the link and the underline. A qualified path reads that `.rq` file, parses idea names, then links or errors. That read belongs to the comment file. Opening a different `.rq` buffer must not re-resolve every comment buffer. An unqualified name searches open `.rq` buffers first. The index snapshot may add a match later ( [lazy_features_after_outbound] ). Do not call `list_all_ideas` for that search. Do not create a document link when the idea is not confirmed. Related: [comment_reference_resolution_error_state]. | 0.103 | |
| comment_support | The extension should recognise reqlan references embedded in comments of arbitrary source files. Comment reference syntax should follow the form rq, then a quoted path, then a dotted idea name in line comments. Qualified comment paths must resolve import-root aliases such as `@/` the same way imports do — ["../../../language/imports.rq".configuration_import_root_alias], ["../comment-references/functional-code-comment-references.rq".comment_reference_import_root_alias]. Comment references in non-. rq files should support syntax highlighting ( resting underline: ["../comment-references/functional-code-comment-references.rq".comment_reference_resting_underline] ), hover, and go-to-definition. Arbitrary file references should be supported from both. rq files and comment references. | 0.059 | ||
| 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 | ||
| configuration_import_root_alias | An import path may start with an alias string, then `/`, then a relative path under that alias's import-root directory. Default alias string: `@`, written as `@/` plus a path relative to the import root. Default import-root directory: the workspace folder that contains the `.rq` file ( not the document directory ). The path after `/` is joined to that alias's import-root directory; the alias itself must be followed by `/` ( e. g. `@reqs` is not aliased ). Alias strings and import-root directories are configured as [configuration.configuration_import_roots] in the applying `.reqlan/config.json` from [configuration.configuration_location]. A configured relative `root` resolves against the base root ( parent of `.reqlan` ); an omitted `root` keeps the workspace-folder default. When several configured aliases could match a path, the longest alias wins. Related path forms: [import_paths], ["../extension/language/comment-references/functional-code-comment-references.rq".comment_reference_import_root_alias]. Completion: ["../extension/language/syntax/features-syntax.rq".code_completion]. File references and the language server use the same locate rule as ["../core_analysis/check.rq".check]: load `importRoots` from the applying `.reqlan/config.json` for the source file ( [configuration.configuration_location] ), then `resolve_rq_path` and join the workspace when the result is relative — including paths with spaces such as `["@/my file.ts"]`. | 0.296 | ||
| 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 | ||
| comment_reference | done | Reqlan references may appear in line comments of arbitrary source files. Comment reference syntax is `rq:[idea]` or `rq:["path".idea]` ( quoted path, optional extra qualification ). Qualified paths use the same path forms as imports, including import-root aliases such as `@/` — ["imports.rq".configuration_import_root_alias], ["../extension/language/comment-references/functional-code-comment-references.rq".comment_reference_import_root_alias]. Discovery skips quoted strings, including Rust raw strings ( `r#"…"#`, `r##"…"##`, `br#"…"#` ), so `rq:[…]` text in a string is not a live comment. Editor language coverage is a blocklist, not an allowlist: ["../extension/language/comment-references/functional-code-comment-references.rq".comment_reference_language_blocklist]. Indexed as `comment_link` by ["../indexer/indexer.rq".index_code_files]. Unresolved targets: [comment_reference_resolution_error]. Indexer listing: ["../core_analysis/core.rq".test_references]. Refactors: ["../extension/mutation/refactor_support.rq".comment_reference_refactor_support]. | 0.365 | |
| comment_reference_resolution_error | done | If a comment reference cannot be resolved, show it as an error diagnostic. Do not create a document link to a missing file ( that underline then raises a generic cannot-find-file editor error ). Related: [comment_reference], [comment_reference_ignore], ["../reference_types.rq".comment_reference], ["../extension/language/comment-references/functional-code-comment-references.rq".references_in_functional_code_comments]. | 0.151 | |
| file_suffix | Reqlan requirement documents use the. rq file suffix. | 0.052 | ||
| idea | done | A reqlan core unit is an idea. Syntax: ["./language/syntax.rq".simple_idea], ["./language/syntax.rq".block_idea]. Grammar: [reqlan_grammar] `Idea` / `OneLinerIdea`; index records: [analytical_types] `IdeaRecord`. Extract: [idea_extractor], [rust_extract]; AST: [rust_ast]. Product surface: [ideas_summary_tabs] Ideas tab per ["./extension/workspace-summary/ideas_summary/webview.rq".ontology_aligned_tabs]. | 0.110 | |
| referenced_files | done | Non- `.rq` files that ideas reference, or that reference ideas. These may be shared. They should be captured in the ["./indexer/indexer.rq".index]. Outbound file refs: ["./language/syntax.rq".reference_file], [file_reference_resolve], edge kind `file_reference` in [analytical_types]. Inbound comment refs: ["./extension/language/comment-references/functional-code-comment-references.rq".references_in_functional_code_comments] via [comment_resolver] / [comment_grammar]. Full non- `.rq` file indexing of comment-bearing sources: ["./indexer/indexer.rq".index_code_files]. Click treats those files as centres: ["./cli/click.rq".click_code_file]. | 0.169 | |
| comment_reference | done | Inbound ["./ontology.rq".reference] from comments in non- `.rq` source: `rq:[idea]` / `rq:["path".idea]`. Qualified paths may use import-root aliases ( `rq:["@/path".idea]` ) per ["./language/imports.rq".configuration_import_root_alias] and ["./extension/language/comment-references/functional-code-comment-references.rq".comment_reference_import_root_alias]. Spec: ["./extension/language/comment-references/functional-code-comment-references.rq".references_in_functional_code_comments] Syntax note: ["./language/syntax.rq".comment_reference]. Resolve: [comment_resolver]. Unresolved: ["./language/syntax.rq".comment_reference_resolution_error]. Index edge kind `comment_link`. Related capture of those files: ["./ontology.rq".referenced_files]. Indexer: ["./indexer/indexer.rq".index_code_files]. | 0.119 | |
| idea_reference | done | Idea-to-idea ["./ontology.rq".reference]: bracket `[name]` / `[ideaset.name]` targets a local, imported, or same-file idea. Syntax: ["./language/syntax.rq".reference_brackets], ["./language/syntax.rq".same_file_reference], ["./language/syntax.rq".reference_qualified], ["./language/syntax.rq".reference_embedding], ["./language/syntax.rq".references_to_subidea]. Index edge kind `references` on [analytical_types] / [rust_index_types]. Extract: [idea_extractor], [rust_extract]. A `[ideaset.member]` form records the edge on the member leaf, not on the ideaset container. An attribute uses the same brackets. See ["./language/syntax.rq".attribute_namespacing]. Wikilink surface for the same edge kind: [link_reference]. Fan-out across files: [wildcard_reference]. | 0.125 |
Reference labels
"../../../../packages/extension/src/extension/register-comment-reference-links.ts", "../../../packages/extension/src/extension/register-comment-reference-links.ts", "../../packages/extension/src/extension/register-comment-reference-links.ts", "../packages/extension/src/extension/register-comment-reference-links.ts", ../../../../packages/extension/src/extension/register-comment-reference-links.ts, ../../../packages/extension/src/extension/register-comment-reference-links.ts, ../../packages/extension/src/extension/register-comment-reference-links.ts, ../packages/extension/src/extension/register-comment-reference-links.ts