Code reference detail
references.test.ts
packages/language/test/references.test.ts
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| analytical_rust_port | in-progress | Port ["../core-architecture.rq".analytical_package] to Rust: lexer, parser ( index path ), extractor, SQLite index, search, and export. `@reqlan/analytical` remains the published JS facade ( `createAnalysisRuntime` / `AnalysisApi` / Zustand host state ). Native work lives in a `crates/` Cargo workspace and ships as per-architecture binaries per [distribution.rust_binary_distribution]. The editor language server is [lsp_rust.language_server_rust]. This analytical port does not replace that process. Component plans: [rust_crate_layout], [lexer_rust], [parser_rust], [parser_align], [indexer.indexer_rust], [search_rust], [export_rust], [native_bridge], [cutover]. | 0.243 | |
| comment_span_align | done | On every frozen [golden_corpus] `.rq` file, `//` and `/* … */` comment character ranges must be identical across: - the Langium lexer ( hidden `SL_COMMENT` / `ML_COMMENT` ) - `findCommentSpansInText` C-style spans ( host `#` / triple-quote spans are not `.rq` comments ) - TextMate `comment.line.reqlan` and `comment.block.reqlan` scopes Same-line fences, glob `/**/`, URL `://`, and fenced ` ` ` bodies must not open comments. Mid-line triple backticks are prose. They must not open a fence or hide later ideas. Example: `@reqlan/*` in inline code must not open a block comment. Related: [parser_align], ["../language/syntax.rq".code_snippets], ["../language/syntax.rq".comments], ["../language/syntax-edge-cases.rq".fencing_comments], ["../language/syntax.rq".inline_code]. | 0.141 | |
| 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_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 | ||
| fencing_comments | done | A complete same-line fence keeps `//` and `/*` as prose, not comments. Closed double quotes: " / / this line " contains no comment. Closed backticks: `//this line` contains no comment. Closed backticks with a glob: `@reqlan/*` does not open a block comment. An unclosed backtick is not a fence, so this line ` An unclosed quote is not a fence, so as does " The Langium lexer, the Rust lexer, comment scanners, and TextMate must use this rule. Related: ["./syntax.rq".comments], ["./syntax.rq".inline_code], ["./syntax.rq".naked_strings_in_body], ["../core_analysis/rust_port.rq".comment_span_align]. | 0.078 | |
| nested_curly_braces | if there is a prose block containing curly braces, { such as this one } they should be treated as part of the prose. Matching braces that end a line — including adjacent pairs like { { SITE_URL } } — stay in the body; they must not close the enclosing idea. A lone `}` on its own line still closes the structural block so an unbalanced prose `{` cannot swallow the idea closer. | 0.108 | ||
| code_snippets | Idea bodies and block attribute values may embed fenced code blocks delimited by triple backticks. An opening fence is three backticks as the first non-whitespace characters on a line, optionally followed by a language tag such as python or rq. A closing fence is three backticks as the first non-whitespace characters on a line. Three backticks in the middle of a line are prose. They do not open a fence. Everything between the fences is literal opaque text — it is not parsed as reqlan syntax. Keywords, imports, attributes, braces, and quotes inside a fence are inert for the parser and may be shown as examples without parse errors. Fenced blocks may span multiple lines and preserve their inner content verbatim. Brace-depth tracking must skip fence interiors so example braces cannot desync surrounding structure ( [no_name_idea_safe_warning] ). Related: ["../core_analysis/rust_port.rq".comment_span_align]. | 0.113 | ||
| 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 | |
| comments | done | Line comments use `//` through end of line ( hidden `SL_COMMENT` ). Block comments use `/* … */` and may span multiple lines ( hidden `ML_COMMENT` ). Meta comments on the same line after content are allowed ( `keep this // meta` ). Comments must not open inside a string / reference-string context: - Naked body quotes ( ["naked_strings_in_body"] ): a quoted slash-slash that is not a comment, quoted urls, `"../mod/**/*.rq"`. - Reference / import `STRING` paths ( `["…"]`, `from "…" import …` ) — the lexer consumes the whole quoted path as one `STRING`, so neither `//` nor `/*` inside the quotes starts a comment. Example: a file reference whose path text contains slash-slash, `["../extension/**/*.rq".*webview*]`. - URL / path-segment guard: `//` immediately after `:` or `/` is not a line comment. Same-line fences: ["./syntax-edge-cases.rq".fencing_comments] — complete `"…"`, `'…'`, and ` ` ` … ` ` ` spans keep ` Unclosed quote or backtick openers are not fences, so `//` after them is a comment. Comment-range identity across lexer, scanner, and TextMate: ["../core_analysis/rust_port.rq".comment_span_align]. Multiline / glob clash: the empty block form `/**/` is **not** a comment — it is the recursive glob segment used in paths such as `../mod/**/*.rq`. A real block comment needs a non-empty body ( `/* note */`, `/*\n note\n*/` ). The token builder rejects length-4 `/**/` matches; comment-span scanners skip the same sequence so embedded `rq:[…]` discovery stays aligned. Related: [comment_reference_ignore], [string_literals], ["./imports.rq".wildcard_references], ["../core_analysis/rust_port.rq".comment_span_align]. | 0.145 | |
| file_suffix | Reqlan requirement documents use the. rq file suffix. | 0.052 | ||
| inline_code | done | Single-backtick spans ( `…` ) are opaque `INLINE_CODE`. They may show example syntax such as a quoted path plus idea. The grammar does not parse bracket or file references inside the span. Check and the language server must not report those examples as unresolved ["../reference_types.rq".file_reference] or idea refs. Related: [code_snippets], ["../core_analysis/rust_port.rq".comment_span_align]. | 0.165 | |
| markdown_links | done | Markdown `[label](target)` links are supported; the label is not treated as an idea reference. Example: testing requirements and the golden corpus. Related: ["../development/core.rq".testing], ["../core_analysis/rust_port.rq".golden_corpus]. | 0.055 | |
| reference_file | References may target arbitrary files, not only. rq files. File reference syntax uses a bracketed quoted path. A relative path resolves from the document directory. When that path climbs with `..` and the file is not there, the same path is tried from each ancestor directory up to the workspace folder. The document-directory file wins when it exists. Line or line-range references append `L#n` or `L#n-m` after the path inside the brackets. Test-name references append `:` and the test title after the path ( for example `./app.test.ts:lists items` ). The first `:` after the path starts the title; later `:` characters stay in the title ( `e2e: …` ). `://` and a Windows drive `C:` / `C:/` are part of the path, not a test suffix. Symbol references append a dot-separated symbol path after the quoted file path. Quoted body text is not a file reference: ["../reference_types.rq".reference_edgecase]. | 0.266 | ||
| string_and_reference_apostrophes | strings should use double or single apostrophes interchangeably and support backslash escapes. | 0.040 | ||
| 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 | |
| file_reference | done | Outbound ["./ontology.rq".reference] to a file, folder, or symbol — not only `.rq`. Syntax: ["./language/syntax.rq".reference_file] ( bracketed quoted path, optional `L#` / symbol path ). Index edge kind `file_reference`. Resolve: [file_reference_resolve]; extract: [idea_extractor]. Editor links: ["./extension/language/syntax/features-syntax.rq".file_references]. Inbound file-reference CodeLens at the top of the target file: ["./extension/language/syntax/features-syntax-highlighting.rq".file_inbound_code_lens]. Non- `.rq` targets and inbound comment traffic: ["./ontology.rq".referenced_files]. Markdown `[label](target)` also stores this edge kind — see [link_reference]. Quoted body text is not this kind: [reference_edgecase]. | 0.211 | |
| 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 | |
| link_reference | done | Link-shaped ["./ontology.rq".reference] surfaces that are not a bare `[idea]` bracket. Wikilink `[[target]]` ( optional alias pipe ): ["./language/syntax.rq".reference_wikilink] — indexes as idea-to-idea `references`, same as [idea_reference]. Markdown `[label](target)`: ["./language/syntax.rq".markdown_links] — label is not an idea ref; the target indexes as `file_reference` ( [file_reference] ). | 0.112 | |
| reference_edgecase | done | A quoted string is a [file_reference] only when it is inside brackets. Example of a file reference: ["./reference_types.rq"] Example of body text: " this is not a reference. rq " The file suffix does not change this rule. The parser must not make a file reference from quoted body text. The language server must not make a document link or a missing-file error from quoted body text. Related: [file_reference], ["./language/syntax.rq".naked_strings_in_body], ["./language/syntax.rq".reference_file]. | 0.112 |
Reference labels
"../../../../packages/language/test/references.test.ts:finds rq: comment references in python triple-quoted comments", "../../../../packages/language/test/references.test.ts:finds rq: references in feature demo source files", "../../../../packages/language/test/references.test.ts:keeps colons inside the test name suffix", "../../packages/language/test/references.test.ts:e2e: findCommentSpansInText skips empty /**/ glob segments", "../../packages/language/test/references.test.ts:embedded file reference scan ignores fenced code blocks", "../../packages/language/test/references.test.ts:embedded file reference scan ignores inline code examples", "../../packages/language/test/references.test.ts:embedded file reference scan ignores markdown link labels", "../../packages/language/test/references.test.ts:embedded file reference scan ignores site showcase interlock inline example", "../../packages/language/test/references.test.ts:findCommentSpansInText does not treat mid-line ``` as a fence", "../../packages/language/test/references.test.ts:findCommentSpansInText skips /* inside complete backtick fences", "../../packages/language/test/references.test.ts:findCommentSpansInText treats unclosed fences as comments and closed fences as prose", "../../packages/language/test/references.test.ts:ignores // inside complete backtick fences when locating line comments", "../../packages/language/test/references.test.ts:ignores // inside string literals when locating line comments", "../../packages/language/test/references.test.ts:keeps colons inside the test name suffix", "../../packages/language/test/references.test.ts:parses :test name suffix from file reference strings", "../../packages/language/test/references.test.ts:parses L# line suffix from file reference strings", "../../packages/language/test/references.test.ts:parses markdown link label and target from raw link text", "../../packages/language/test/references.test.ts:skips rq tokens inside Rust raw strings", "../../packages/language/test/references.test.ts:unquotes single-quoted reqlan string literals", "../packages/language/test/references.test.ts:embedded file reference scan ignores markdown link labels", "../packages/language/test/references.test.ts:embedded file reference scan ignores unbracketed quoted paths", "../packages/language/test/references.test.ts:finds embedded file references in @tests lists", "../packages/language/test/references.test.ts:finds rq: bracket comment references in line comments", "../packages/language/test/references.test.ts:finds rq: comment references in block comments", "../packages/language/test/references.test.ts:parses markdown link label and target from raw link text", ../../../../packages/language/test/references.test.ts:finds rq: comment references in python triple-quoted comments, ../../../../packages/language/test/references.test.ts:finds rq: references in feature demo source files, ../../../../packages/language/test/references.test.ts:keeps colons inside the test name suffix, ../../packages/language/test/references.test.ts:embedded file reference scan ignores fenced code blocks, ../../packages/language/test/references.test.ts:embedded file reference scan ignores inline code examples, ../../packages/language/test/references.test.ts:embedded file reference scan ignores markdown link labels, ../../packages/language/test/references.test.ts:embedded file reference scan ignores site showcase interlock inline example, ../../packages/language/test/references.test.ts:findCommentSpansInText does not treat mid-line ``` as a fence, ../../packages/language/test/references.test.ts:findCommentSpansInText treats unclosed fences as comments and closed fences as prose, ../../packages/language/test/references.test.ts:ignores // inside complete backtick fences when locating line comments, ../../packages/language/test/references.test.ts:ignores // inside string literals when locating line comments, ../../packages/language/test/references.test.ts:keeps colons inside the test name suffix, ../../packages/language/test/references.test.ts:parses :test name suffix from file reference strings, ../../packages/language/test/references.test.ts:parses L# line suffix from file reference strings, ../../packages/language/test/references.test.ts:parses markdown link label and target from raw link text, ../../packages/language/test/references.test.ts:skips rq tokens inside Rust raw strings, ../../packages/language/test/references.test.ts:unquotes single-quoted reqlan string literals, ../packages/language/test/references.test.ts:embedded file reference scan ignores markdown link labels, ../packages/language/test/references.test.ts:embedded file reference scan ignores unbracketed quoted paths, ../packages/language/test/references.test.ts:finds embedded file references in @tests lists, ../packages/language/test/references.test.ts:finds rq: bracket comment references in line comments, ../packages/language/test/references.test.ts:finds rq: comment references in block comments, ../packages/language/test/references.test.ts:parses markdown link label and target from raw link text