Code reference detail
native-analysis-api.ts
packages/analytical/src/native/native-analysis-api.ts
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| agent_advisory | done | Agents must pass the [click_session] ID ( `sessionKey` ) to the next click action. This keeps one agent thread on the same session so a revisit can expand connected content and so ranking can use session distance. MCP tool text states this rule and the unique / ambiguous / search paths clearly ( [mcp_server] `click` ). | 0.101 | |
| click | done | The [click_ontology] function returns compact local context for one target. Input: an idea name, a `path#idea` ref, a `.rq` file path, or an indexed code file ( [click_input], [click_code_file] ). Resolution uses [click_ambiguity]: no match uses search; more than one match is ranked; one match uses [click_output]. Optional [click_max_detail] flags cap how many names and bodies are listed. Optional `sessionKey` continues a [click_session]. A second click on a centre already clicked in that session returns the connected content ( [click_session] ). Surfaces: CLI `reqlan click` ( [click_cli] ), MCP `click` ( [mcp_server] ), and [native_analysis_api] `click`. MCP search and retrieval use this tool only ( ["../extension/agent/skills-and-mcp.rq".mcp_click_retrieval] ). Engine: [click_rust] on ["./cli_package.rq".architecture] / ["../core_analysis/rust_port.rq".analytical_rust_port]. Related: [function_parity], [commands], [agent_advisory], [click_session], [click_input], [click_max_detail], [click_output]. | 0.200 | |
| click_ambiguity | done | Engine function that classifies a name or target as none, unique, or ambiguous. A name is ambiguous when more than one indexed idea or indexed file shares that exact name. Names are unique inside one file ( [idea_name] ); ambiguity is across files. `path#idea` and a full indexed path are unique when that record exists. Click uses this function to choose the [click_input] path and to decide when [click_output] prints a file path next to a name. Outbound [wildcard_reference] targets are ambiguous: print their matching paths. Surfaces: AnalysisApi `checkNameAmbiguity` ( engine ). Click must call it. CLI / MCP exposure is not required. | 0.103 | |
| click_output | done | The result always includes `sessionKey` ( [agent_advisory] ). The result does not include an `edges` list. Links are implied by the lists below. Shape depends on [click_input]: Unique ( one centre ): - the idea ( or file ) and its content ( indexed unmarked body / summary ) - count of outbound links from that content only: idea refs and [file_reference] that occur in the unmarked body. Do not list refs that occur only in `@tests`, `@implementation`, or `@todo`. Do not list [comment_reference] code files as outbound. List names. When [click_ambiguity] says the name is ambiguous, print the file path with the name. File names are unquoted basenames. - count of backlinks and the first n names ( [click_max_detail] ); print the file when the name is ambiguous or shared; then " + m more " for the remainder - count of siblings ( same [ideaset] / file ), not the ideas named in the content, and the first n names, with file when the name is ambiguous or shared - for a code-file centre, see [click_code_file] Ambiguous ( more than one match ): ranked candidate names with file paths. Include hop distance only when the session has prior ideas. No idea bodies. Cap with `maxCandidates`. Search ( no exact match ): [fuzzy_search] / [file_search] hits. Cap with `maxCandidates`. Revisit: see [click_session]. Show content of the connected nodes, not the centre body again. | 0.117 | |
| diff | done | Compare ideas in two git snapshots. The key is the file path plus the [idea_name]. The command reads `.rq` files from git and parses each snapshot. It does not read or write the ideas index. Line position does not count. The same body and attributes at a different line are unchanged. Content is the idea body plus its attributes. Change kinds: - created — the key exists only on the right snapshot - deleted — the key exists only on the left snapshot - modified — the key exists on both snapshots and the content differs - moved — the name exists in exactly one file on each side, the paths differ, and the content is the same The same name in more than one file on one side stays on the path-plus-name key. A renamed idea is deleted plus created. Unchanged ideas are omitted. A reference-only edit stays modified. No arguments: if any `.rq` path is staged, unstaged, or untracked and not gitignored, the left side is `HEAD` and the right side is that pending snapshot. Otherwise the left side is `HEAD~1` and the right side is `HEAD`. A non- `.rq` change does not select the pending snapshot. One argument: that revision against `HEAD`. Two arguments: the first revision against the second. A target is a branch, a commit, `HEAD`, `~N` ( `HEAD~N` ), or `<rev>~N`. The pending snapshot uses the working-tree file for an unstaged edit, the index blob when the working tree matches `HEAD`, and the working-tree file when a path is both staged and unstaged. An untracked `.rq` file that git does not ignore is included. If `HEAD` has no parent, the left snapshot is empty and every idea on `HEAD` is created. A missing revision or a directory that is not a git repository is an error. Exit status is 2. A successful diff exits 0, including an empty diff. When a side is filled by a default, the human CLI and [diff_webview] print a header `Comparing <from> -> <to>` before the rows. Explicit two-argument runs omit that header. `--json` and MCP stay a row array only. Surfaces: CLI `reqlan diff` ( [commands] ), MCP [skills_and_mcp.mcp_diff], and [diff_webview]. Engine: ["../../crates/reqlan-analytical/src/diff.rs"]. Git spawns stay hidden ( [consumption_silence] ). Related: [architecture] [function_parity] [idea] [idea_reference] [diff_verbosity] [diff_cli_color] | 0.163 | |
| check | done | `reqlan check` should run perform the following checks: - ensure all rq [reference] point to real nodes, unless rq ignored with [comment_reference_ignore]. - this tests rqcomments point to real parts of the namespace, that code references exist, and that rq references exists. - report unresolved imports: [check_unresolved_imports]. - report a comment reference with invalid syntax: [code_comment_syntax_errors]. - report a qualified reference whose file is not on disk: [check_qualified_missing_file]. - report a qualified reference whose `.rq` file does not declare the idea: [check_qualified_missing_idea]. - it should really just be a wrapper of the [index] and return the issues ( as a pipe, terminal output, or json ). Issue order: [check_order_by_target]. Sparse wildcards: [check_wildcard_sparse] via flags [check_wildcard_zero] and [check_wildcard_one]. Path globs: [check_glob_patterns]. Skip missing targets: [check_skip_targets] [check_skip_gitignored_targets]. CLI: ["../cli/cli_package.rq".commands]. MCP: ["../extension/agent/skills-and-mcp.rq".mcp_check]. CI: [check_meta_implementation]. Site demo: ["../site/site.rq".broken_links_showcase]. | 1.000 | |
| check_glob_patterns | done | [check] accepts more than one `--glob` pattern. Repeat `--glob` for each pattern. A file is in the recursive scan when it matches any glob. One `--glob` selects the same files as one path glob. A reference target that matches no glob is still checked. That target must resolve. [check] does not walk a directory that matches no glob. A positional path can name a file outside the globs. [check] checks that file. A positional path that is a directory outside the globs is not walked. An empty `--glob` value is an error. API: `AnalysisApi.check({ pathGlobs, paths })`. CLI: ["../cli/cli_package.rq".commands]. MCP: ["../extension/agent/skills-and-mcp.rq".mcp_check]. Related: [check] | 0.308 | |
| check_skip_gitignored_targets | done | [check] omits a file [reference] issue when Git ignore rules ignore the missing target. The analyser function `check_references` takes `skip_gitignored_targets` ( default false ). Match uses the workspace ["../../.gitignore"] and nested `.gitignore` files on the target path. Match uses the resolved path from the workspace root, not the authored path in the source file. Idea references, comment references, and missing imported idea names stay in the issue list. Missing import paths follow the same skip as file references ( [check_unresolved_imports] ). Use this when a referenced file is build output or editor config that git does not store. Examples: `.cursor/` for ["../extension/agent/chat-participant.rq".mcp], and `packages/extension/media/webviews/` for ["../extension/host/onboarding/page-thanks-for-installing.rq".installation_event]. CLI: `--skip-gitignored-targets` ( ["../cli/cli_package.rq".commands] ). API: `AnalysisApi.check({ skipGitignoredTargets })`. CI: ["../../.github/workflows/ci.yml"] and ["../../azure-pipelines.yml"] pass `--skip-gitignored-targets` because a CI checkout does not contain gitignored files ( [check_meta_implementation] ). Related: [check] [check_skip_targets] [check_unresolved_imports] [check_meta_implementation] | 0.445 | |
| check_skip_targets | done | [check] omits an issue when the missing [reference] target matches a skip glob. The analyser function `check_references` takes `skip_targets`: a list of globs. Match uses the same path glob rules as `--glob`. Match is against the issue `label` ( the missing target ), not the source file. An empty skip glob has no effect. Use this when a referenced file is not in git and you name the skip glob. For all Git ignore rules, use [check_skip_gitignored_targets]. CLI: repeatable `--skip-target <glob>` ( ["../cli/cli_package.rq".commands] ). API: `AnalysisApi.check({ skipTargets })`. Related: [check] [check_skip_gitignored_targets] [check_meta_implementation] | 0.445 | |
| check_wildcard_one | done | `check_references` flag `wildcard_one` ( default `warn` ) controls a ["../reference_types.rq".wildcard_reference] that matches exactly 1 idea. 1 match means the pattern is too narrow — use a concrete [reference] instead. `warn` — emit the row with severity `warning` and match count 1. `error` — emit the row with severity `error` and match count 1. `off` — omit the row. CLI: `--wildcard-one <warn|error|off>` ( ["../cli/cli_package.rq".commands] ). API: `AnalysisApi.check({ wildcardOne })`. Related: [check] [check_wildcard_sparse] [check_wildcard_zero] ["../language/imports.rq".wildcard_references] | 0.507 | |
| check_wildcard_zero | done | `check_references` flag `wildcard_zero` ( default `warn` ) controls a ["../reference_types.rq".wildcard_reference] that matches 0 ideas. 0 matches means the pattern hits nothing. `warn` — emit the row with severity `warning` and match count 0. `error` — emit the row with severity `error` and match count 0. `off` — omit the row. CLI: `--wildcard-zero <warn|error|off>` ( ["../cli/cli_package.rq".commands] ). API: `AnalysisApi.check({ wildcardZero })`. Related: [check] [check_wildcard_sparse] [check_wildcard_one] | 0.507 | |
| csv_export | done | CSV export writes `ideas.csv` with tags and non-status / tag attributes flattened into columns ( `attr:<key>` ), plus `references.csv` for inbound / outbound / unresolved edges. Shared base / scope / output / name and file filters apply. Pipeline: `exportCsv` / `writeCsvExport` ( [export_pipeline] ). Extension UI host: ["../extension/export/export.rq".export_webview]. | 0.055 | |
| export_pipeline | done | `@reqlan/analytical` owns export execution for every format. Shared contract: `ExportRequest` / progress callbacks / snapshot build, then format writers. Hosts ( extension webview, CLI ) assemble an `ExportRequest` and call `NativeAnalysisApi.exportHtml` / `exportMarkdown` / `exportJson` / `exportCsv` — they do not reimplement writers. Formats: ["./html_export.rq".html_export], [markdown_export], [json_export], [csv_export], [pdf_export]. Progress phases ( snapshot, then write completed / total ) are reported to hosts for loading UI. Consumed under [analysis_scope]. Rust port of snapshot + writers: ["./rust_port.rq".export_rust]. | 0.114 | |
| json_export | done | JSON export writes `export.json` for the selected base: ideas ( with attributes and reference lists ), files, clusters, attributes, and status / tag rollups — suitable for tooling and AI consumption. Shared base / scope / output / name and file filters apply. Pipeline: `exportJson` / `writeJsonExport` ( [export_pipeline] ). Extension UI host: ["../extension/export/export.rq".export_webview]. | 0.055 | |
| markdown_export | done | Markdown export writes a `README.md` index for the selected base ( counts, status / tag rollups, idea list, file list ) and optional per-idea `.md` pages under `ideas/` with attributes and inbound / outbound references as relative markdown links. When per-idea pages are disabled, idea bodies are inlined in the README. Shared base / scope / output / name and file filters apply; HTML-only page families ( graph, clusters, attributes, print ) are omitted. Pipeline: `exportMarkdown` / `writeMarkdownExport` using the same snapshot builder as HTML ( [export_pipeline] ). Extension UI host: ["../extension/export/export.rq".export_webview]. | 0.055 | |
| pdf_export | partial | PDF export prepares a print-oriented HTML report from the selected base so the user can Print → Save as PDF in the browser. Direct PDF binary rendering is not required yet; preserve links in the printable HTML ( ["./html_export.rq".html_export_printable_pages] ). PDF-specific options include file filters and print entry filename; shared base / scope / output / name apply. Extension UI host: ["../extension/export/export.rq".export_webview] ( not a separate QuickPick chain ). | 0.073 | |
| html_export | done | `@reqlan/analytical` builds documentation as HTML from the requirement graph ( ["./export.rq".export_pipeline], [analysis_scope] ). Html export should render ideas, attributes, references, and navigable structure suitable for sharing. Pipeline: `NativeAnalysisApi.exportHtml` / `AnalysisRuntime.export` → `reqlan-export` snapshot ( `build_export_snapshot` ) → multi-file static site ( `write_html_export` ). Single-file mode remains optional via [html_export_runtime_modes]. Interactive graph / search JS stays bundled static assets ( [html_export_graph_layout] ), not a second writer ( ["./rust_port.rq".export_rust] ). Thin hosts: extension UI ( ["../extension/export/export.rq".export_webview], ["../extension/export/html-export.rq".html_export_form], ["../extension/export/export.rq".export_html] ) and CLI ( `reqlan export` / ["../cli/cli_package.rq".commands] ). Export is scoped to a selected ["../bases/base.rq".base] ( not a merged multi-base workspace graph ). [html_export_multi_file] [html_export_internal_links] [html_export_idea_tooltips] [html_export_layout_cards] [html_export_heading_tooltips] [html_export_table_columns] [html_export_search] [html_export_list_views] [html_export_overview_links] [html_export_idea_pages] [html_export_file_pages] [html_export_code_reference_pages] [html_export_cluster_pages] [html_export_graph_page] [html_export_attributes_index] [html_export_attribute_pages] [html_export_printable_pages] [html_export_print_idea_cards] [html_export_print_body_whitespace] [html_export_print_in_page_anchors] [html_export_print_all_attributes] [html_export_print_button] [html_export_print_order_by] [html_export_runtime_modes] [html_export_scrollable_lists] [html_export_header_link] [html_export_url_base] [html_export_katz_column] | 0.201 | |
| contextual_search | done | Search string plus an optional context list of relative `.rq` paths, `path#idea` refs, or bare idea names. Runs [semantic_search], then re-ranks with min undirected hop distance from any resolved context idea and exponential decay ( [idea_graph_distance] ): `finalScore = textScore * 2^(-minHop)` ( unreachable floor = 8 hops ). Surfaces: [native_analysis_api] `searchRequirements(..., { context })` and CLI `reqlan search --context` ( [search_cli] ). Implements [search_with_context]. PageRank ( [pagerank] ) and full [context_scope_v2] ingestion remain future work. Default ranking does not use Katz. Opt in with [katz_search]. Complements [fuzzy_search] when neighbourhood / context should bias ranking. ["../cli/click.rq".click_input] ranks ambiguous click matches the same way, with session ideas as context. | 0.208 | |
| katz_search | done | Search can bias matches by inbound Katz centrality ( [katz_centrality] ). The bias is off unless the caller sets it. CLI flag: `reqlan search <query> --katz`. API field: `SearchRequirementsOptions.katz`. When the bias is on, the score is `textScore * (1 + katzScore)`. The match reasons include `katz:<score>`. Context hop decay runs first. The Katz multiplier runs second. When the bias is off, match order and scores stay on the text ranking. | 0.082 | |
| search | Search over the requirement graph — find ideas by name, body, tags, and related signals. Surfaces: [fuzzy_search], [file_search], [contextual_search], [semantic_search], [katz_search]. Consumed by CLI `reqlan search`, MCP / chat tools, Ideas Summary, and the activity-bar search pane. Rust ranking engine: ["./rust_port.rq".search_rust]. | 0.046 | ||
| semantic_search | Broader token / edge-label search over candidates through [native_analysis_api]. Prefer [fuzzy_search] for fast name-oriented lookup with separator-insensitive matching. | 0.092 | ||
| analysis_api_dispose | done | [analysis_runtime] `openAnalysisApi` dispose must close the native analysis runtime and drop its SQLite connection ( ideas index and click-sessions ). A no-op dispose is a defect. Extension commands use a short-lived `withAnalysisApi` ( open → run → dispose ) mediated by [analysis_runtime]; they must not cache `NativeAnalysisApi` for the session. | 0.040 | |
| sqlite_artifact_lifecycle | done | Base SQLite artifacts under `<base>/.reqlan/` ( [base_ownership] ) must not stay locked for the whole extension session. The host opens them only while work runs, then releases file handles so users can delete or replace the files. Aligns with [event_driven]: open and close are reactions to index or analysis events, not a permanent connection or a reconnect loop. Mediation: only [workspace_index] / [analysis_runtime] own SQLite connections. The extension adapter ( [editor_index_adapter] ) must not keep a second long-lived analysis runtime beside the index, and must not call native open without a matching dispose / release. Related: [index_sequencing], [idle_stale_check], [headless_consumers], [multi_base_environment]. | 0.052 | |
| katz_centrality | done | Score each idea by inbound Katz centrality on the citation graph. An idea scores higher when important ideas reference it. The score uses resolved reference edges and wildcard reference edges between ideas. The analysis package exposes the scores as `katzCentrality()`. The top score is 1. A graph with no citation edges gives every idea the score 1. Search can opt in through ["../core_analysis/search.rq".katz_search]. HTML export shows the score through ["../core_analysis/html_export.rq".html_export_katz_column]. | 0.061 | |
| markov_chain | graph traveral should be tracked to inform a markov chain model of the graph. | 0.040 | ||
| site | the / site folder contains a static Next. js App Router landing page for reqlan. should align with [brand] Copy modules: [copy] Document head: [meta_tags] | 0.040 | ||
| spec_html_export | done | The site static build exports the workspace requirement graph ( excluding `*.secret.rq` ) under `out/spec/` via `reqlan export`. It must pass [html_export.html_export_url_base] for `/spec` ( honouring `SITE_BASE_PATH`, e. g. `/reqlan/spec` in production ) so `/spec` loads with or without a trailing slash. It must pass [html_export.html_export_header_link] pointing at the marketing site home so readers can leave the embedded spec and return to the parent site. Embedded `/spec` graph pages inherit [html_export.html_export_graph_background_load] so large workspace graphs do not freeze the page while settling. Pipeline: ["../../site/scripts/build-static.mts"] → ["../../site/scripts/export-spec.mts"] → ["../../site/scripts/verify-static-export.mts"]. Host options come from [html_export.html_export] / CLI [cli_package.commands], including native CLI export via ["../core_analysis/rust_port.rq".native_bridge]. CI must build / stage host `reqlan-napi` before this pipeline ( [distribution_reqs.site_distribution] ); the loader probes repo-root `crates/target`, not `packages/crates`. | 0.142 |
Reference labels
"../../packages/analytical/src/native/native-analysis-api.ts", ../../../packages/analytical/src/native/native-analysis-api.ts, ../../packages/analytical/src/native/native-analysis-api.ts