spec - native-analysis-api.ts

Referenced by7

Labels7

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
click_session	done		Click sessions live in SQLite under [application_memory] as `click-sessions.sqlite` ( sibling of `ideas-index.sqlite`; not deleted by ideas-index rebuild ). Each session has a stable `sessionKey`. Sessions are keyed against ideas. Each surfaced idea stores a fingerprint of its name, summary, status, and tags. When that fingerprint changes, the idea may resurface on the next click. Record clicked centres ( unique or revisit targets ) separately from names that were only listed. When the target is a centre already clicked in this session, return the content of the connected nodes ( outbound, backlinks, and siblings that the first click listed ), capped by [click_max_detail]. Do not repeat the centre body. Do not return an empty suppressed slice. Skip a connected body that this session already showed as content, unless its fingerprint changed. Session cache size is [click_session_limit]. Eviction uses last-touched order: when the store exceeds the limit, drop the least recently touched sessions first. Touch the active session on every successful click. Path helper: ["../../packages/analytical/src/core/application-memory.ts"] / [click_sessions_rust]. Layout: ["../indexer/sidecars.rq".reqlan_directory_layout].	0.225
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
diff_verbosity	done		Three levels. The default is summary. CLI: `--verbosity summary\|references\|text`, or `-v` / `-vv`. MCP and [diff_webview] use the same three values. - summary — change kind, idea name, and file. `fromFile` only for moved. - references — summary, plus [idea_reference] targets added on the right and removed from the left. Order each list by name. Omit a target that is on both sides. - text — summary, plus the body and attributes before and after. Created shows the right side. Deleted shows the left side. Modified shows both. Moved has no text change. Do not list reference names at this level. Attributes stay inside modified. The references level does not print attribute text. The text level prints body lines, then attribute lines as `@name` / `@name value`. `--json` omits `references` and `text` at summary. It adds `references` at references only. It adds `text` at text only.	0.071

Reference labels

agent_advisory, click, click_ambiguity, click_output, click_session, diff, diff_verbosity