Code reference detail
reqlan.langium
packages/language/src/reqlan.langium
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| grammar_and_parser | The language server parses with `reqlan-parse` ( [lsp_rust.language_server_rust] ). Do not switch the language to tree-sitter. Main `.rq` grammar file: [reqlan_grammar]. Comment-token grammar for `rq:[…]` in non- `.rq` sources: [comment_grammar]. `langium generate` still builds host AST modules and TextMate JSON per [development_build.build_prepare]. The checked-in TextMate grammar paints the editor before semantic tokens. Syntax requirements that the grammar must satisfy live in [syntax]; conceptual units in [ontology.idea], [ontology.ideaset], [ontology.reference], [ontology.import_statement]. Host services stay in [language_module]. The language server does not load them. | 0.172 | ||
| 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 | |
| parser_align | done | Langium and `reqlan-parse` stay two engines as a dual-parser **test oracle**. Grammar truth is [syntax] / ["../../packages/language/src/reqlan.langium"]. The same source must yield the same parse snapshot: top-level elements, live bracket and wiki refs, inline-code count, and fence count. One Node test runs Langium and native `parseReqlanSource` ( `parseAlignSnapshot` ) together. A committed name dump is not the only check. The default editor LSP already uses Rust ( [lsp_rust.language_server_rust] ); this idea does not gate that cutover. Related: [golden_corpus], [parser_rust], [comment_span_align]. | 0.150 | |
| parser_rust | done | Recursive-descent parser matching ["../../packages/language/src/reqlan.langium"] productions into a Rust AST the extractor can walk. Recovery: nameless `{...}` and local import mistakes still yield a usable document ( [parser_lexer.recovery_vs_budget] ). Wall-clock [parser_lexer.parse_budget_timeout] via native timeout / cancel — no Node worker process required on the index path. Open `.rq` buffers and CLI `parse` use `reqlan-parse` ( [lsp_rust.language_server_rust] ). Langium remains a dual-parser test oracle and the transitional `node` engine fallback — not the default editor LSP. Alignment contract: [parser_align]. | 0.217 | |
| import_error_recovery | A malformed import must not invalidate the rest of the file. Recoverable invalid `from` shapes parse as local import nodes with a line-level diagnostic: - `from "path" as alias` ( mistaken namespace form ) — suggest `import "path" as alias` or `from "path" import <idea>` - bare `from "path"` — require the `import <idea>` clause - `from` without a quoted path — consume the remainder of the line as an invalid import Later imports and top-level ideas continue to parse and link normally. Same recovery posture for nameless top-level braces: ["./syntax.rq".no_name_idea_safe_warning]. If lex / parse never completes, see ["./parser_lexer.rq".parse_budget_timeout]. | 0.058 | ||
| 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 | ||
| import_tokenisation | if an import is given an alias, then the base name is still available as a variable name and should not cause a conflict. Only the alias binds in the importing file; the imported idea's base name may be reused for a local idea. e. g. The same rule applies to qualified imports with `as`. Unaliased imports still bind the idea name and conflict with a local idea of that name. Related: ["../extension/language/syntax/features-syntax.rq".sensible_alias_support]. | 0.053 | ||
| 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 | |
| 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 | ||
| 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 | |
| empty_attribute | A line that contains only @ is insignificant whitespace. Spaces or tabs may precede that @. Spaces or tabs may follow that @. The lexer consumes that @ as hidden whitespace. The parser does not build an attribute for that line. That line does not cause a parser error. That line does not cause a lexer error. That line does not cause a tokenizer error. That line does not cause an extension error. A flag keeps the form @ name. A negated flag keeps the form @ name!. A valued attribute keeps its value after the name. A syntax error on a different line is still reported. | 0.040 | ||
| 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 | |
| no_name_idea_safe_warning | done | A top-level nameless curly-brace block — `{... }` with no idea name — must not take down the parser or the language server workspace. Parse the block as a recoverable anonymous top-level element, emit a descriptive warning that a name is required before `{`, and continue so later ideas, imports, and links still work. Nameless blocks inside parenthesized lists remain valid list items per [lists]; only top-level nameless blocks warn. Related recovery posture: ["./imports.rq".import_error_recovery]. Block shape: [block_idea]. Fenced examples must stay opaque per [code_snippets] so braces inside snippets cannot desync structural depth. Non-termination ( lex / parse never finishes ) is a different failure mode: ["./parser_lexer.rq".parse_budget_timeout]. | 0.072 | |
| reference_resolution_order | done | For each `.rq` file, identify the names in local scope, then resolve references. Sequence: 1. Collect all idea, one-liner, and ideaset declarations in the file. Declaration order does not change which names are in scope. 2. Collect reference candidates in the file. 3. Resolve each candidate against those local declarations. 4. Resolve imports only for candidates that have no local match. Stop import lookup for a candidate when a local match exists. The language server and the indexer must use this sequence. Open-file editor underlines follow [open_file_reference_sequencing]. Related: [same_file_reference], [ideaset], ["./imports.rq".import_tokenisation], ["../indexer/indexer.rq".local_symbolic_analysis]. | 0.053 | |
| reference_url | done | A bracket reference may target an unquoted absolute URL ( `scheme://…` ). Example: `[https://reqlan.com/]`. The URL is one token; `://` is not a line comment. Unbracketed URLs in body prose stay text. Quoted remote paths stay [reference_file] ( `["https://example.com/file.ts"]` ). Index and check: ["../reference_types.rq".url_reference]. | 0.137 | |
| references_to_subidea | done | It is valid to reference a member of an [ideaset] as `[ideaset.member]`, for example [example_ideaset.subidea1]. The indexer must record that reference on the namespace leaf node. In this example the leaf is [subidea1], not [example_ideaset]. Related: [reference_brackets], [same_file_reference], ["../reference_types.rq".idea_reference], ["../indexer/indexer.rq".index]. | 0.167 | |
| attribute | done | Attributes are classification, functional, or nonfunctional metadata. Syntax: ["./language/syntax.rq".attribute_marker], ["./language/syntax.rq".attribute_forms], ["./language/syntax.rq".attribute_values], ["./language/syntax.rq".attribute_location]. Policy: ["./language/attributes.rq".attribute_configuration]. Indexed on [analytical_types] `IdeaAttributeMap`; extract: [idea_extractor], [rust_extract]. Product surface: [ideas_summary_tabs] Attributes tab. | 0.070 | |
| attribute_body | done | The first attribute in an idea, if not marked otherwise, is the main body attribute. It is unstructured text. Syntax: ["./language/syntax.rq".block_idea]; extract summary from that body: [idea_extractor], [rust_extract]. | 0.054 | |
| file | done | Files store ideas and form ideasets. Documents use the `.rq` suffix ( ["./language/syntax.rq".file_suffix] ) and ["./language/syntax.rq".file_layout]. Indexed as ideaset kind `file` in [analytical_types]. | 0.094 | |
| grammar_rule | done | Grammar rules describe the syntax features. Requirements: ["./language/syntax.rq"]; lexer bridge: ["./language/parser_lexer.rq".lexer_bridge_to_syntax]. Langium: [reqlan_grammar]; comment grammar: [comment_grammar]; index-path AST: [rust_ast]. | 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 | |
| idea_name | done | The idea name is a string / handle / variable that uniquely identifies the idea ( within the ideaset / file ). It should not be a reserved [keyword]. Syntax: ["./language/syntax.rq".idea_name]; grammar: [reqlan_grammar] `IdeaName`. | 0.069 | |
| ideaset | done | Ideasets are namespace containers for ideas. Syntax: ["./language/syntax.rq".ideaset]. Grammar: [reqlan_grammar] `IdeaSet`. Index kind `ideaset` plus `ideaset_member` edges: [analytical_types], [idea_extractor], [rust_index_types]. A [file] is an implicit ideaset ( ["./language/syntax.rq".file_layout] ). Product surface: [ideas_summary_tabs] Ideasets tab. | 0.134 | |
| import_statement | done | Imports describe references. Some [keyword] s are reserved for imports. Forms: ["./language/imports.rq".import_from], ["./language/imports.rq".import_namespace], ["./language/imports.rq".import_qualified]. Grammar: [reqlan_grammar] `Import`; resolve: [import_resolver]. | 0.063 | |
| keyword | done | As a language, reqlan has keywords that are reserved in some contexts. Import statement keywords: ["./language/imports.rq".import_keywords] ( `import`, `from`, `as` ). Grammar: [reqlan_grammar] — those tokens are keywords only at statement start. Idea names should not use reserved keywords ( [idea_name] ). | 0.057 | |
| reference | done | References link ideas to other ideas, files, and symbols. Syntax: ["./language/syntax.rq".reference_brackets], ["./language/syntax.rq".reference_wikilink], ["./language/syntax.rq".reference_qualified], ["./language/syntax.rq".reference_file], ["./language/syntax.rq".reference_url], ["./language/syntax.rq".reference_embedding]. Kinds: [reference_types]. Grammar: [reqlan_grammar] `ReferenceTarget`; index edges: [idea_extractor], [rust_extract]. | 0.655 | |
| 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 | |
| ideaset_reference | done | References to an ["./ontology.rq".ideaset] or a namespace that behaves as one. Syntax: ["./language/syntax.rq".ideaset]; namespace import alias: ["./language/imports.rq".import_namespace] ( `[alias]` opens the imported file and links only the alias name ). Membership edges are `ideaset_member`; a bare namespace-alias bracket is stored as `file_reference` ( [idea_extractor] ), not `references`. | 0.057 | |
| 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 | |
| url_reference | done | A bracket reference whose target is an absolute URL with a scheme and `://`. Example: [https://reqlan.com/]. Syntax: ["./language/syntax.rq".reference_url]. Index edge kind `url_reference` on [analytical_types] / [rust_index_types]. Extract: [idea_extractor], [rust_extract]. [check] does not treat a URL reference as a missing idea or a missing file. Unbracketed URLs in body prose stay text, not this kind. Related: [file_reference], [link_reference]. | 0.075 | |
| wildcard_reference | done | One ["./ontology.rq".reference] that matches many ideas: quoted path glob + idea pattern ( `*` / `?` ). Syntax and navigation: ["./language/imports.rq".wildcard_references], ["./language/imports.rq".wildcard_references_webview]. Index: one `wildcard_reference` edge per catalog match ( ["./indexer/indexer.rq".wildcard_reference_edges] ); never stored as plain `references`. Native extract: ["../crates/reqlan-index/src/extract.rs"]. Sparse match handling: ["./core_analysis/check.rq".check_wildcard_sparse] ( ["./core_analysis/check.rq".check_wildcard_zero], ["./core_analysis/check.rq".check_wildcard_one] ). | 0.279 |
Reference labels
"../../packages/language/src/reqlan.langium", ../../packages/language/src/reqlan.langium, ../packages/language/src/reqlan.langium