diff --git a/docs/appmap-docs.md b/docs/appmap-docs.md index 9e1324f027..8770218ab8 100644 --- a/docs/appmap-docs.md +++ b/docs/appmap-docs.md @@ -18,7 +18,7 @@ By using AppMap data, Navie is the first AI code architect with the context to u Over 90,000 software developers are using the [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) and the [AppMap plugin for JetBrains](https://plugins.jetbrains.com/plugin/16701-appmap). -Get Started +Get Started Troubleshooting ![AppMap Navie with Sequence diagram in Visual Studio Code](/assets/img/docs/vscode-with-navie-prompt.webp) _AppMap Navie with Sequence diagram in Visual Studio Code_ diff --git a/docs/get-started-with-appmap/navie-ai-quickstart.md b/docs/get-started-with-appmap/navie-ai-quickstart.md index 26aef3f500..fd961c2907 100644 --- a/docs/get-started-with-appmap/navie-ai-quickstart.md +++ b/docs/get-started-with-appmap/navie-ai-quickstart.md @@ -29,7 +29,7 @@ After you complete the installation of AppMap for your code editor. Open the Nav To open the Navie Chat, open the AppMap plugin in the sidebar menu for your code editor, and select the `New Navie Chat` option. -![Open Navie](/assets/img/open-navie.webp) +![Open Navie](/assets/img/open-navie.png) ## Ask Navie about your App @@ -65,6 +65,24 @@ The Navie UI includes a standard chat window, and a context panel which will inc ![Navie Context Window](/assets/img/navie-context-window.webp) +## Review Your Code + +You can also use Navie to review your code. This is a great way to get an overview of your codebase, identify potential issues, and improve the quality of your code. +Navie uses the same types of data to perform code review as it does for answering questions, including code snippets, sequence diagrams, traces, and other I/O data. + +To start a code review, click the `Review Your Code` button in the Navie sidebar. This will generate a list of suggested improvements for your codebase, including: + +![Review Your Code](/assets/img/review_your_code_button.png) + +- Potential bugs +- SQL query optimizations +- HTTP request optimizations +- Security vulnerabilities +- Performance improvements +- Code design improvements and anti-patterns + +... and more. Because Navie uses AppMap Data, it can provide more accurate and relevant suggestions than other code review tools. + ## Improve Navie AI Responses with AppMap Data Generate AppMap Data and you will greatly improve the quality of your Navie AI responses. With AppMap Data for your project, you can now ask much deeper architectural questions about your application. This is possible because of the additional context from AppMap Data and the higher accuracy and relevance of the code snippets which are relevant to your question. diff --git a/docs/reference/appmap-airgapped-install.md b/docs/reference/appmap-airgapped-install.md index fd9ef2be6c..a92dfdf033 100644 --- a/docs/reference/appmap-airgapped-install.md +++ b/docs/reference/appmap-airgapped-install.md @@ -345,6 +345,13 @@ To open the Output window, on the menu bar, choose View > Output, or in Windows ![Open View in VS Code](/assets/img/docs/vscode-output-1.webp) +When reviewing logs, pay attention to startup errors that might indicate: +- System compatibility issues (e.g., GLIBC version requirements on Linux) +- Permission problems (especially on Windows) +- Temporary directory access restrictions + +For detailed information about common error patterns and their solutions, see our [VS Code troubleshooting guide](/docs/troubleshooting/vscode). + Click on the output log dropdown in the right corner to view a list of all the available output logs. ![Open Output logs list](/assets/img/docs/vscode-output-2.webp) @@ -369,10 +376,18 @@ Next, open `Help` > `Show Log...` will open the IDE log file. ## Support -For help with your offline install of AppMap Navie, please open a new support request by emailing [support@appmap.io](mailto:support@appmap.io) +If you encounter startup issues with the VS Code extension, first check our [troubleshooting guide](/docs/troubleshooting/vscode) for solutions to common problems like: +- Linux GLIBC version compatibility requirements +- Windows temporary directory permissions +- Extension startup failures -Include the following information in your support request. +If you're still experiencing issues with your offline installation of AppMap Navie, please open a new support request by emailing [support@appmap.io](mailto:support@appmap.io) +Include the following information in your support request: +- Any error messages from the VS Code Output panel (AppMap: Services channel) +- Your operating system version and details: + - For Linux: output of `ldd --version` + - For Windows: OS build number and whether VS Code is running as administrator - Company Name - Code editor name and version (e.g. VS Code or JetBrains) - AppMap binary version diff --git a/docs/reference/appmap-mcp.md b/docs/reference/appmap-mcp.md new file mode 100644 index 0000000000..d7d4c18f2f --- /dev/null +++ b/docs/reference/appmap-mcp.md @@ -0,0 +1,158 @@ +--- +layout: docs +title: Docs - Reference +description: "Reference for the AppMap MCP server, which exposes recorded AppMap Data to AI assistants as read-only query tools over the Model Context Protocol." +toc: true +reference: true +step: 12 +name: AppMap MCP Server +--- + +# AppMap MCP Server + +- [AppMap MCP Server](#appmap-mcp-server) + - [Overview](#overview) + - [Prerequisites](#prerequisites) + - [Install the AppMap CLI](#install-the-appmap-cli) + - [Build the query index](#build-the-query-index) + - [Starting the server](#starting-the-server) + - [Options](#options) + - [Configuring an MCP client](#configuring-an-mcp-client) + - [Tools](#tools) + - [Common filters](#common-filters) + - [Orientation and ranking](#orientation-and-ranking) + - [Finding records](#finding-records) + - [Analyzing recordings](#analyzing-recordings) + - [Resources](#resources) + - [GitHub repository](#github-repository) + +## Overview + +The AppMap MCP server exposes recorded [AppMap Data](/docs/reference) to AI assistants as a set of read-only query tools over the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-capable client — for example an AI coding assistant or chat client — can connect to the server and ask questions about how your application actually ran: which endpoints are slow, where time is spent, what SQL was issued, what exceptions occurred, and how a single request executed end to end. + +The server reads from a pre-built query database that AppMap maintains from your recorded AppMap Data. It never modifies your AppMap Data or your application — it only answers queries. + +The MCP server is part of the [AppMap CLI](/docs/reference/appmap-client-cli) and is started with the `appmap query mcp` command. It communicates over standard input and output (stdio) using newline-delimited [JSON-RPC 2.0](https://www.jsonrpc.org/specification) messages, which is the standard MCP stdio transport. + +## Prerequisites + +### Install the AppMap CLI + +The MCP server ships with the AppMap CLI. Install the `appmap` binary by following the instructions in the [AppMap CLI reference](/docs/reference/appmap-client-cli#prerequisites). + +### Build the query index + +The MCP server reads from a query database (`query.db`) that is derived from your recorded AppMap Data. Build or refresh this index by running the `index` command in your project: + +```console +$ appmap index +``` +{: .example-code} + +If the query database has not been built, the MCP server reports that the query DB was not found and instructs you to run `appmap index` first. Re-run `appmap index` after recording new AppMap Data so the server queries the latest results. + +
+If you use the AppMap plugin for Visual Studio Code or JetBrains, you do not need to run appmap index yourself. The plugin runs the index command automatically in --watch mode for every appmap.yml file it finds in your project, keeping the query database up to date as you record new AppMap Data. +
+ +## Starting the server + +Run the MCP server from the root of your project: + +```console +$ appmap query mcp +``` +{: .example-code} + +The server reads JSON-RPC requests from standard input and writes responses to standard output, one JSON object per line. All logging is written to standard error so that it does not corrupt the protocol stream — on startup the server prints `appmap mcp listening on stdio` to standard error. + +In normal use you do not run this command by hand. Instead, you configure your MCP client to launch it (see [Configuring an MCP client](#configuring-an-mcp-client)). + +### Options + +| Option | Description | +| ------ | ----------- | +| `-d`, `--directory` | Program working directory. | +| `--appmap-dir` | Directory containing AppMap Data. | +| `--query-db` | Path to the `query.db` file, overriding the default location. | + +## Configuring an MCP client + +MCP clients launch the server as a stdio subprocess. Most clients accept a JSON configuration that names the command to run and the directory to run it in. The exact file and field names vary by client, but the configuration follows this shape: + +```json +{ + "mcpServers": { + "appmap": { + "command": "appmap", + "args": ["query", "mcp"] + } + } +} +``` + +By default the server queries the project in the client's working directory. To query a different project, pass `--directory` in `args`. Use the `--appmap-dir` or `--query-db` options if your AppMap Data or query database lives in a non-default location. Make sure the `appmap` binary is on the `PATH` available to the client, or use an absolute path for `command`. + +
+The query database must already exist before the client connects. Run appmap index in the project first, and re-run it whenever you record new AppMap Data. +
+ +## Tools + +The server exposes the following tools. Every list tool returns a paged result of the form `{ rows, total, limit, offset }`, and every tool returns its result as JSON. When orienting against an unfamiliar project, start with `list_endpoints` to see the available routes and where time and errors are concentrated. + +### Common filters + +Most tools accept a shared set of optional filters to narrow results: + +| Filter | Description | +| ------ | ----------- | +| `route` | Limit to a specific HTTP route (for example `GET /users/:id`). | +| `status` | Limit to a specific HTTP status code. | +| `duration` | Limit to records at or above a minimum elapsed time. | +| `branch` | Limit to recordings captured on a git branch. | +| `commit` | Limit to recordings captured at a git commit. | +| `since`, `until` | Limit to a time range. | +| `appmap` | Limit to a single recording, identified by its canonical path. | +| `limit`, `offset` | Page through results. | + +### Orientation and ranking + +| Tool | Description | +| ---- | ----------- | +| `list_endpoints` | Per-route summary table with request count, average and p95 latency, and error rate. The recommended first call when exploring a project. Sort by `count`, `avg`, `p95`, or `err`. | +| `function_hotspots` | Functions ranked by total elapsed time across recordings, with a representative source path, line number, and fully-qualified id. Filter by `route` or `class`. | +| `sql_hotspots` | SQL queries ranked by total elapsed time, deduplicated by query text, with call count and average latency. | +| `list_labels` | AppMap [labels](/docs/reference/analysis-labels) ranked by usage, with a sample function id for each label. | + +### Finding records + +| Tool | Description | +| ---- | ----------- | +| `find_recordings` | Recording-level rows (one per AppMap recording), with a canonical `path` and a `kind` of `junit`, `request`, or `other`. Use the returned `path` as the `appmap` argument to other tools. | +| `find_requests` | Individual HTTP server requests, with method, route, status code, elapsed time, and branch. | +| `find_queries` | Individual SQL queries, with query text, elapsed time, and the calling class and method. Filter by `table`, `class`, or `method`. | +| `find_calls` | Individual function calls, including captured parameters and return values. Filter by `class`, `method`, `label`, or exact `event_id`s. When a class or method matches nothing, the result includes a "did you mean" suggestion. | +| `find_logs` | Application log lines captured during recordings. Filter by `message` or `logger`. | +| `find_exceptions` | Exceptions raised during recordings. Use `with_logs` to attach the most recent preceding log lines to each exception. | + +### Analyzing recordings + +| Tool | Description | +| ---- | ----------- | +| `get_call_tree` | The call tree of a single recording (identified by its `appmap` path). Focus on a function, SQL query, or HTTP request with `focus_type` and `focus_value`; control breadth with `parent_depth`, `child_depth`, and `min_elapsed_ms`. Returns a byte-budgeted text tree by default, or full JSON nodes with `format: json`. | +| `find_related` | Recordings ranked by similarity to a source recording, scoring shared routes, SQL tables, and classes. Useful for finding other recordings that exercise the same code. | +| `compare_branches` | Per-route p95 latency for two branches (`branch_a` and `branch_b`) with the delta between them. Sort by `delta`, `p95-a`, or `p95-b`. | + +## Resources + +In addition to tools, the server exposes the following MCP resources: + +| Resource | Description | +| -------- | ----------- | +| `appmap://endpoints` | All HTTP endpoints with request count, average latency, p95 latency, and error rate, as JSON. | +| `appmap://recording/{ref}/logs` | All log lines for a single recording, where `{ref}` is the URL-encoded canonical path of the recording. | + +## GitHub repository + +[https://github.com/getappmap/appmap-js/tree/main/packages/cli](https://github.com/getappmap/appmap-js/tree/main/packages/cli) diff --git a/docs/reference/index.md b/docs/reference/index.md index d75907c432..82062fd57b 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -19,6 +19,7 @@ redirect_from: [/docs/reference/browser-extension] - [AppMap for Java – Gradle Plugin](/docs/reference/appmap-gradle-plugin) - [AppMap Command line interface (CLI)](/docs/reference/appmap-client-cli.html) - [Remote recording API](/docs/reference/remote-recording-api) +- [AppMap MCP Server](/docs/reference/appmap-mcp) - [Analysis Rules](/docs/reference/analysis-rules) - [Analysis Labels](/docs/reference/analysis-labels) - [License Key Installation](/docs/reference/license-key-install) diff --git a/docs/reference/jetbrains.md b/docs/reference/jetbrains.md index b67b82d48e..b6ee5f89f9 100644 --- a/docs/reference/jetbrains.md +++ b/docs/reference/jetbrains.md @@ -120,6 +120,8 @@ When you run a Java application with the AppMap agent, [remote recording](/docs/ You can make a [remote recording](../recording-methods#remote-recording) from within the JetBrains IDE. +**Security Warning**: Remote recording should only be enabled in non-production environments. Enabling it in other environments is a security risk as the recording endpoints may be accessible to anyone who can reach the application server. You can ensure that remote recording is not enabled by ensuring that the `appmap` Java agent is not loaded by the JVM. + 1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already. 2. Start your application with remote recording enabled. For Java, [run your Java application with AppMap](#running-a-java-application-with-appmap). For other languages, consult the [agent reference](/docs/reference) for details. 3. To start a recording, click the remote recording button, or use the command **Start AppMap recording**. @@ -133,9 +135,22 @@ You can make a [remote recording](../recording-methods#remote-recording) from wi For more details about remote recording, see: -- [Recording methods > Remote recording](/docs/recording-methods) +- [Recording methods > Remote recording](/docs/get-started-with-appmap/making-appmap-data#with-remote-application-recording) - [Remote recording API](../reference/remote-recording-api) +## Requests recording + +You can configure AppMap to record HTTP requests and responses in your Java application. This is useful for understanding how your application interacts with external services. + +1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already. +2. Start your application with the `appmap` Java agent enabled. For Java, [run your Java application with AppMap](#running-a-java-application-with-appmap). For other languages, consult the [agent reference](/docs/reference) for details. +3. Interact with your application through its UI or API. +4. AppMap will automatically record HTTP requests and responses. The recorded requests will be saved as AppMap data files in the project AppMap directory (`tmp/appmap` by default). + +For more details about requests recording, see: + +- [Recording methods > Requests recording](/docs/get-started-with-appmap/making-appmap-data#with-api-request-recording) + ## AppMap Plugin actions To open the list of AppMap plugin actions, press `CTRL+SHIFT+A` on Windows and Linux, or `COMMAND+SHIFT+A` on macOS, and type `AppMap`. You can also find these actions at `Tools > AppMap` of the main menu. diff --git a/docs/reference/vscode.md b/docs/reference/vscode.md index 1198eb55e7..5109863b6b 100644 --- a/docs/reference/vscode.md +++ b/docs/reference/vscode.md @@ -131,6 +131,7 @@ To open the list of AppMap extension actions, press `CTRL+SHIFT+P` or `COMMAND+S Most of the command names should be self-explanatory. Here are a few commands which are a bit more complicated: +- **AppMap: Review Your Code** Starts a code review using AppMap Navie. This command analyzes your code changes and provides a comprehensive report to help you improve code quality, security, and performance by providing specific, actionable suggestions. - **AppMap: Filter/Find AppMap by name** Opens the AppMap side bar view and the filter/find text field - **AppMap: Login**, **AppMap: Logout** Some extension functionality requires you to login to the AppMap Server. You'll be prompted to do this when you setup AppMap for the first time. You can also login and logout using the built-in `Accounts` feature of VSCode. - **AppMap: Touch Out-of-Date Test Files** If you have AppMap Diagrams generated from test cases, this command will determine which tests need to be re-run in order to bring the AppMap Data up-to-date. It will then "touch" (update the modified date) of each out-of-date test case. You can use a file watching trigger program like `Guard` (Ruby), `grunt` or `gulp` (JS) to re-run the test cases as they are touched. @@ -175,3 +176,9 @@ After [recording AppMap Data](/docs/recording-methods.html) for your project, op ## GitHub repository [https://github.com/getappmap/vscode-appland](https://github.com/getappmap/vscode-appland) + +## Troubleshooting + +If you encounter issues with the AppMap VS Code extension, particularly during startup, please check the Output panel +(`View -> Output`, select "AppMap: Services") for error messages. Common startup issues and their solutions are documented +in our [troubleshooting guide](/docs/troubleshooting/vscode). diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md new file mode 100644 index 0000000000..c2e0a85191 --- /dev/null +++ b/docs/troubleshooting/index.md @@ -0,0 +1,53 @@ +--- +layout: docs +title: Troubleshooting AppMap +description: "Find solutions to common AppMap issues and get help with installation, configuration, and usage problems" +toc: true +name: Troubleshooting +step: 1 +--- + +# Troubleshooting AppMap + +This guide helps you find solutions to common AppMap issues. Select the appropriate section based on your problem area: + +## IDE Integration Issues + +### VS Code Extension + +Having problems with the AppMap VS Code extension? Check our detailed [VS Code troubleshooting guide](/docs/troubleshooting/vscode) for solutions to common issues like: + +- GLIBC version compatibility on Linux +- Windows permission and temporary file errors +- Extension startup problems + +### JetBrains Plugin + +For JetBrains IDE plugin issues, refer to our [air-gapped installation guide](/docs/reference/appmap-airgapped-install#jetbrains) which covers: + +- Plugin installation problems +- Binary compatibility issues +- Installation in restricted environments + +## Environment-Specific Issues + +### Docker Integration + +If you're using AppMap with Docker, see our [Docker troubleshooting guide](/docs/reference/integrations/docker#troubleshooting-appmap-and-docker) for help with: + +- Container configuration +- Volume mounting +- Performance optimization + +## Getting Help + +If you can't find a solution to your problem: + +1. Check the logs: + + - [VS Code logs](/docs/troubleshooting/vscode#accessing-error-logs) + - [JetBrains logs](/docs/reference/appmap-airgapped-install#accessing-navie-logs) + +2. Contact Support: + - Email: [support@appmap.io](mailto:support@appmap.io) + - GitHub Issues: [AppMap VS Code Extension](https://github.com/getappmap/vscode-appland/issues) diff --git a/docs/troubleshooting/vscode.md b/docs/troubleshooting/vscode.md new file mode 100644 index 0000000000..7f7c478728 --- /dev/null +++ b/docs/troubleshooting/vscode.md @@ -0,0 +1,121 @@ +--- +layout: docs +title: Troubleshooting VS Code Extension +description: "Find solutions to common AppMap VS Code extension issues" +toc: true +troubleshooting: true +--- + +# Troubleshooting AppMap VS Code Extension + +This guide helps you diagnose and resolve common startup issues with the AppMap VS Code extension. + +## Accessing Error Logs + +When the AppMap VS Code extension encounters problems, error messages and stack traces are logged to VS Code's Output panel: + +1. Open VS Code's Output panel using `View -> Output` +2. Select "AppMap: Services" from the dropdown menu in the Output panel +3. Look for error messages and stack traces that can help identify the issue + +## Common Startup Issues + +### Linux GLIBC Version Compatibility + +**Symptom:** +The AppMap services fail to start with an error message about missing GLIBC version 2.29 or newer. + +**Example Error:** + +``` +Error: /lib/x86_64-linux-gnu/libm.so.6: version `GLIBC_2.29' not found +(required by /tmp/pkg/.../better-sqlite3/build/Release/better_sqlite3.node) +``` + +**Solution:** +This error occurs on older Linux distributions that use a GLIBC version older than 2.29. To resolve this: + +1. Check your current GLIBC version: + ```console + $ ldd --version + ``` +2. Update your Linux distribution to a newer version that includes GLIBC 2.29 or later. Common distributions with GLIBC 2.29+: + - Ubuntu 20.04 or newer + - Debian 11 or newer + - RHEL 8 or newer + - Fedora 32 or newer + +### Windows Permission and Temporary File Errors + +**Symptom:** +AppMap services fail to start with permission errors when trying to create directories in the Windows temp folder. + +**Example Error:** + +``` +Error: EPERM: operation not permitted, mkdir 'C:\WINDOWS\TEMP\pkg\...' +``` + +**Common Causes:** + +- Running VS Code as administrator +- Antivirus software interference +- Restricted system temporary directory permissions +- Misconfigured TEMP environment variable + +**Solutions:** + +1. Configure a user-writable temporary directory: + + - Open VS Code Settings (`Ctrl+,`) + - Search for "AppMap: Command Line Environment" + - Add a new environment variable: `TEMP=C:\Users\\.appmap\temp` + - Restart VS Code + +2. Check antivirus settings: + + - Add VS Code and the AppMap temporary directory to your antivirus exclusions + - Temporarily disable real-time scanning to test if it's causing the issue + +3. Review VS Code privileges: + - Avoid running VS Code as administrator unless necessary + - Ensure your user account has write permissions to the temporary directory + +## Advanced Troubleshooting + +If the above solutions don't resolve your issue: + +1. Enable detailed logging: + + - Open VS Code Settings + - Search for "App Map: Command Line Verbose" + - Enable verbose output + - Restart VS Code + - Check the Output panel for additional diagnostic information + +2. Check system requirements: + + - Verify you have adequate disk space + - Ensure your system meets the [minimum requirements](/docs/reference) for AppMap + - Check for VS Code updates + +3. Clean installation: + - Uninstall the AppMap extension + - Delete the AppMap data directory: + - Windows: `%USERPROFILE%\.appmap` + - Linux/macOS: `~/.appmap` + - Reinstall the extension + +## Getting Help + +If you continue to experience issues: + +1. Gather the following information: + + - VS Code version + - AppMap extension version + - Operating system and version + - Error messages from the Output panel + - Steps to reproduce the issue + +2. [Open an issue](https://github.com/getappmap/vscode-appland/issues) on our GitHub repository. diff --git a/docs/using-navie-ai/index.md b/docs/using-navie-ai/index.md index c9bbf392c0..48587b8891 100644 --- a/docs/using-navie-ai/index.md +++ b/docs/using-navie-ai/index.md @@ -9,15 +9,16 @@ redirect_from: [/docs/navie] # Using Navie -- [Opening Navie](./navie-opening) -- [Choosing an LLM Provider](./choose-llm-provider) -- [Navie Commands](./navie-commands) -- [Navie Command Workflow](./navie-workflow) -- [Navie Options](./navie-options) -- [Accessing Navie Logs](./navie-accessing-logs) -- [Navie Architecture](./navie-architecture) -- [Navie User Interface](./navie-user-interface) +- [Opening Navie](/docs/using-navie-ai/navie-opening) +- [Choosing an LLM Provider](/docs/using-navie-ai/choose-llm-provider) +- [Navie Commands](/docs/using-navie-ai/navie-commands) +- [Review Your Code](/docs/using-navie-ai/navie-review) +- [Navie Command Workflow](/docs/using-navie-ai/navie-workflow) +- [Navie Options](/docs/using-navie-ai/navie-options) +- [Accessing Navie Logs](/docs/using-navie-ai/navie-accessing-logs) +- [Navie Architecture](/docs/using-navie-ai/navie-architecture) +- [Navie Chat User Interface](/docs/using-navie-ai/navie-chat-user-interface) **Install AppMap for your preferred code editor to get started.** -Get AppMap +Get AppMap diff --git a/docs/using-navie-ai/navie-accessing-logs.md b/docs/using-navie-ai/navie-accessing-logs.md index 6faa00ee72..63da11d23f 100644 --- a/docs/using-navie-ai/navie-accessing-logs.md +++ b/docs/using-navie-ai/navie-accessing-logs.md @@ -3,7 +3,7 @@ layout: docs title: Docs - Reference name: Accessing Navie Logs toc: true -step: 6 +step: 7 navie: true description: "Reference Guide to AppMap Navie AI, how-to guide for accessing logs." --- diff --git a/docs/using-navie-ai/navie-architecture.md b/docs/using-navie-ai/navie-architecture.md index 3e6c97ff8a..81548a486d 100644 --- a/docs/using-navie-ai/navie-architecture.md +++ b/docs/using-navie-ai/navie-architecture.md @@ -4,7 +4,7 @@ title: Docs - AppMap Navie description: "Reference Guide to AppMap Navie AI, architectural overview of AppMap Navie AI." name: Navie Architecture navie: true -step: 7 +step: 8 toc: true --- diff --git a/docs/using-navie-ai/navie-chat-user-interface.md b/docs/using-navie-ai/navie-chat-user-interface.md new file mode 100644 index 0000000000..ce1ef070a2 --- /dev/null +++ b/docs/using-navie-ai/navie-chat-user-interface.md @@ -0,0 +1,32 @@ +--- +layout: docs +title: Docs - Reference +name: Navie Chat User Interface +step: 9 +navie: true +description: "Reference Guide to AppMap Navie Chat UI, describing the user interface." +--- + +## User Interface + +AppMap Navie AI is an AI assistant that enables you to ask architectural level questions about your code base. Navie is also able to help you generate new code that can span across your entire project. The primary user interface for Navie is within your VS Code or JetBrains code editor. + +![Navie User Interface](/assets/img/docs/appmap-navie-user-interface.webp) + +### Basic Layout + +The Navie user interface consists of 5 key areas. + +
    +
  1. AppMap Data Status Panel
    2.  + This panel will list the current status of the AppMap Data that has been created for your project. AppMap Data are your application runtime traces which include things like HTTP and SQL requests, data flows, class and function level instrumentation, and more. Without AppMap Data created for your project, Navie can search through your static source code in your workspace for relevant code snippets. +
  2. Navie Context Window
    3.  + Upon asking a question to Navie it will search through your AppMap Data (if exists) and the source code in your open workspace to locate all the relevant context for your question. This area will reflect the information that Navie is aware of when answering. You can use this information to better understand how Navie is responding. +
  3. LLM Model Config Button
    4.  + You can configure Navie to use your own OpenAI API key or bring your own LLM model running locally or within another provider. Clicking the gear icon will open the configuration modal for the bring your own model settings. +
  4. Active LLM Model
    5.  + This panel will display the currently configured LLM model in use with Navie. The LLM details are displayed in the following format: Model: <Model Name> (<location>). When using the default Navie backend, the location will be listed as default. When using your own OpenAI API key the location will be listed as via OpenAI. When using your own model or key, + the location will be the value of the OPENAI_BASE_URL environment variable. +
  5. Navie Chat Window
    6.  + This is your primary location for interacting with Navie. Here you can ask Navie questions about how your application works, ask Navie to generate code or test cases, and you can even have Navie create a pull request based on your changes. To learn more about specific Navie commands refer to the Navie Commands section. +
diff --git a/docs/using-navie-ai/navie-commands.md b/docs/using-navie-ai/navie-commands.md index be872f368d..29aac1b50f 100644 --- a/docs/using-navie-ai/navie-commands.md +++ b/docs/using-navie-ai/navie-commands.md @@ -11,18 +11,19 @@ step: 3 # Navie Commands You can ask free-form questions, or start your question with one of these commands: + - [`@explain`](#explain) - [`@diagram`](#diagram) - [`@search`](#search) - [`@plan`](#plan) - [`@generate`](#generate) - [`@test`](#test) -- [`@review`](#review) - [`@help`](#help) +- [`@review`](#review) ## @explain -The `@explain` command prefix within Navie serves as a default option focused on helping you learn more about your project. Using the `@explain` prefix will focus the Navie AI response to be more explanatory and will dive into architectural level questions across your entire code base. You can also use this to ask for ways to improve the performance of a feature as well. +The `@explain` command prefix within Navie serves as a default option focused on helping you learn more about your project. Using the `@explain` prefix will focus the Navie AI response to be more explanatory and will dive into architectural level questions across your entire code base. You can also use this to ask for ways to improve the performance of a feature as well. #### Examples @@ -32,7 +33,7 @@ The `@explain` command prefix within Navie serves as a default option focused on ## @diagram -The `@diagram` command prefix within Navie focuses the AI response to generate Mermaid compatible diagrams. [Mermaid](https://mermaid.js.org/) is an open source diagramming and charting utility with wide support across tools such as GitHub, Atlassian, and more. Use the `@diagram` command, and Navie will create and render a Mermaid compatible diagram within the Navie chat window. You can open this diagram in the [Mermaid Live Editor](https://mermaid.live), copy the Mermaid Definitions to your clipboard, save to disk, or expand a full window view. Save the Mermaid diagram into any supported tool such as GitHub Issues, Atlassian Confluence, and more. +The `@diagram` command prefix within Navie focuses the AI response to generate Mermaid compatible diagrams. [Mermaid](https://mermaid.js.org/) is an open source diagramming and charting utility with wide support across tools such as GitHub, Atlassian, and more. Use the `@diagram` command, and Navie will create and render a Mermaid compatible diagram within the Navie chat window. You can open this diagram in the [Mermaid Live Editor](https://mermaid.live), copy the Mermaid Definitions to your clipboard, save to disk, or expand a full window view. Save the Mermaid diagram into any supported tool such as GitHub Issues, Atlassian Confluence, and more. Navie generates the following types of diagrams: @@ -49,42 +50,46 @@ Navie generates the following types of diagrams: #### Sequence Diagram -##### Why Use a Sequence Diagram: +##### Why Use a Sequence Diagram: + 1. **Enhanced Understanding:** Sequence diagrams offer a clear visualization of an application's runtime behavior, making it easier for developers to analyze and understand complex workflows and interactions within the codebase. 2. **Refactoring and Debugging:** These diagrams assist in identifying code smells and help developers refactor messy code into more logical patterns. 3. **Documentation:** They act as living documentation, helping maintain up-to-date insights into the system's architecture and facilitating easier onboarding for new team members. -##### Why Share with Team Members: +##### Why Share with Team Members: + 1. **Collaboration:** Sharing sequence diagrams helps facilitate discussions during design or planning meetings, as everyone can see the same visualization of the application's behavior. 2. **Knowledge Sharing:** By embedding these diagrams into documentation or presentations, team members gain a better understanding of the system, which is particularly useful when passing on knowledge or updating team members on recent changes. 3. **Improved Communication:** The diagrams can be shared to ensure all team members, regardless of their experience level or familiarity with the project, have a clear and consistent understanding of the code's execution flow. -##### Example Questions +##### Example Questions - **Interaction Flow**: How can the sequence diagram illustrate the interaction flow between objects or components during a user login process? - **Message Passing**: What messages are exchanged between system components, and how are they ordered and timed within the sequence diagram? - **Method Invocation Details**: How does the diagram represent method invocations and the sequence of method calls required to execute a payment transaction? - **Complex Workflow Mapping**: What steps are involved in a complex workflow, such as order processing, and how are they sequenced and interrelated? - **Error Handling in Sequences**: How are errors or exceptions captured and managed within the sequence flow, especially during external API calls? -- **User Interaction Viewpoint**: From a user's perspective, how does the sequence diagram outline the steps taken and responses received when interacting with a specific feature or service? +- **User Interaction Viewpoint**: From a user's perspective, how does the sequence diagram outline the steps taken and responses received when interacting with a specific feature or service? - + Sequence Diagram Video Demo -#### Entity Relationship Diagram (ERD) +#### Entity Relationship Diagram (ERD) + +##### Why Use an Entity Relationship Diagram: -##### Why Use an Entity Relationship Diagram: 1. **Data Structure Visualization:** ERDs provide a clear graphical representation of the database structure, illustrating entities, attributes, and relationships. This helps developers understand the organization of data within the system. 2. **Database Design:** ERDs are instrumental in designing databases by helping identify what tables are needed and how they interrelate. They ensure a well-structured and efficient database design process. 3. **Analysis and Modeling:** ERDs assist in the logical analysis and modeling of data requirements, ensuring that the database structure aligns with business processes and rules. -##### Why Share with Team Members: +##### Why Share with Team Members: + 1. **Collaboration on Design:** Sharing ERDs among team members fosters collaboration on database design, as individuals can discuss and provide input on the data model. 2. **Knowledge Sharing:** Team members can use ERDs to better understand the database schema, especially useful for new developers onboarding or when transferring a project. 3. **Improved Communication:** ERDs serve as an effective communication tool among developers, database administrators, and stakeholders, providing a common understanding of how data is structured and accessed. -##### Example Questions +##### Example Questions - **Entity Relationships**: How are the entities related to each other, and what types of relationships (e.g., one-to-one, one-to-many) exist between them? - **Key Attributes Identification**: What are the key attributes of each entity, and how are they represented to define the unique aspects of each entity? @@ -93,23 +98,25 @@ Navie generates the following types of diagrams: - **Cardinality and Participation**: How are cardinality (e.g., zero, one, many) and participation (e.g., optional, mandatory) represented in the relationships? - **Domain Modeling**: How does the ERD represent domain-specific models by aligning real-world entities with their database counterparts? - + Entity Relationship Diagram Video Demo -#### Flow Chart +#### Flow Chart + +##### Why Use a Software Process Flow Chart: -##### Why Use a Software Process Flow Chart: 1. **Visualizing Processes:** Flowcharts provide a straightforward and visual method for representing complex processes, making it easier to understand workflows, decision points, and sequences of operations within a system. 2. **Identifying Inefficiencies:** By visualizing the entire process, flowcharts can highlight bottlenecks or inefficiencies, aiding in process optimization and improvement efforts. 3. **Ensuring Consistency:** They help ensure that processes are consistently applied and adhered to by providing a visual guideline or standard operating procedure. -##### Why Share with Team Members: +##### Why Share with Team Members: + 1. **Facilitating Collaboration:** Sharing flowcharts supports collaborative efforts by giving all team members a clear understanding of the process, enabling them to align their efforts and make informed suggestions for improvements. 2. **Knowledge Sharing and Onboarding:** Flowcharts can be utilized to educate new team members on existing processes, ensuring that knowledge about workflows is easily communicated and retained. 3. **Unified Communication:** They provide a unified view that can be shared across different teams or departments, ensuring that everyone has the same understanding of the process and eliminating misunderstandings. -##### Example Questions +##### Example Questions - **Process Visualization**: How can the flowchart depict the overall process of user registration, including decision points and sequential actions? - **Efficiency Identification**: What are the potential bottlenecks or inefficiencies within the process, and how can they be identified through the flowchart? @@ -117,24 +124,26 @@ Navie generates the following types of diagrams: - **Conditional Logic**: What conditional logic is included in the decision-making process, and how is it represented in the flowchart? - **Sequential Operations**: How does the flowchart outline the step-by-step operations necessary to complete a specific business task or feature within the application? - **Cross-Departmental Workflows**: How does the flowchart illustrate the interaction between different departments or teams in a multi-step process? - - + + Flow Chart Video Demo -#### Class Diagram +#### Class Diagram + +##### Why Use a Class Diagram: -##### Why Use a Class Diagram: 1. **Blueprint of System Structure:** Class diagrams provide a blueprint of the system's structure by showing classes, their attributes, methods, and the relationships between them. This aids in visualizing how the system is organized at a glance. 2. **Design and Refactoring:** They support the design phase by allowing architects and developers to plan class structures and relationships. They are also useful in refactoring efforts by providing a clear view of dependencies. 3. **Documentation:** Class diagrams act as precise documentation of the system's architecture, capturing detailed design choices that can be referred to throughout the development lifecycle. -##### Why Share with Team Members: +##### Why Share with Team Members: + 1. **Collaborative Design:** Sharing class diagrams enables collaborative design and decision-making, allowing team members to propose improvements or identify the best design patterns collectively. 2. **Onboarding and Knowledge Transfer:** New team members can quickly get up to speed with the system's architecture through class diagrams, facilitating efficient onboarding and knowledge transfer among team members. 3. **Unified Understanding:** By providing a common representation of the system's architecture, class diagrams ensure that all stakeholders, including developers, designers, and management, have a unified understanding of the system. -##### Example Questions +##### Example Questions - **Primary Class Identification**: What are the primary classes involved in the core functionality of the application, such as authentication or user management? - **Class Interactions**: How do specific classes interact with each other, and what are the dependencies that exist between them within the application? @@ -144,23 +153,25 @@ Navie generates the following types of diagrams: - **Design Pattern Implementation**: What design patterns are applied to the class structures, and how do these patterns enhance or streamline the application's functionality? These questions will guide the creation of a class diagram that illuminates the organizational structure of the system, helping to understand both the high-level and detailed design choices. - + Class Diagram Video Demo -#### State Diagram +#### State Diagram + +##### Why Use a State Diagram: -##### Why Use a State Diagram: 1. **Understanding State Transitions:** State diagrams are excellent for visualizing the various states an object or system can be in and the transitions between these states, which helps in understanding dynamic behavior. 2. **Designing Complex Workflows:** By outlining states and transitions, developers can map out complex workflows, ensuring that all possible scenarios are accounted for and logically sequenced. 3. **Debugging and Error Handling:** State diagrams aid in identifying and handling errors by illustrating how the system should respond to various inputs or events, thereby enhancing robustness. -##### Why Share with Team Members: +##### Why Share with Team Members: + 1. **Facilitating Collaboration:** Sharing state diagrams helps align team understanding on how the system should behave in various states, fostering more effective collaboration in design and implementation. 2. **Knowledge Transfer and Onboarding:** New team members can use state diagrams to quickly get up to speed with the system's operational flow, facilitating easier onboarding and knowledge transfer. 3. **Unified Understanding:** They provide a cohesive view of how components or systems behave, ensuring that all stakeholders, including developers and business analysts, have a unified understanding of the system's behavior. -##### Example Questions +##### Example Questions - **Authentication Flow States**: How does the authentication flow handle different states of a user session, such as logged in, logged out, or session expired? - **Request Lifecycle**: What are the different states a request goes through from when it is received until it is fully processed or fails? @@ -169,15 +180,14 @@ These questions will guide the creation of a class diagram that illuminates the - **State Transitions in Business Logic**: What are the state transitions involved in specific business processes, such as order processing or data validation? - **Resource State Transitions**: How do resources change states in response to different events, such as a database update or a successful API call? - - + State Diagram Video Demo #### Example Diagram Projects -Below are a series of open source projects you can use to try out the `@diagram` feature using -prebuilt AppMap data in a sample project. Simply clone one of the following projects, open +Below are a series of open source projects you can use to try out the `@diagram` feature using +prebuilt AppMap data in a sample project. Simply clone one of the following projects, open into your code editor with the AppMap extension installed, and ask Navie to generate diagrams. - [Sample Python Project](https://github.com/land-of-apps/python-diagram-example/blob/master/README.md) @@ -189,25 +199,27 @@ into your code editor with the AppMap extension installed, and ask Navie to gene The `@search` command in Navie is a powerful tool for navigating complex codebases with ease. By leveraging smart search capabilities, you can locate specific code elements, relevant modules, or examples directly within the AppMap environment. -#### Key Features +#### Key Features + - **Intelligent Query Processing**: The `@search` command uses a smart agent to interpret queries, identifying and retrieving relevant code segments based on context. - **Formatted Results**: Search results are organized into clickable Markdown links, enabling direct access to pertinent code files or sections. - **Customizable Display Options**: Output can be tailored to user preferences, allowing flexible formatting options for improved readability. -#### Using @search +#### Using @search + 1. **Start a Search**: Type the `@search` command followed by your query. 2. **Specify Context**: Provide descriptive keywords or phrases to refine the search, improving accuracy and relevance of results. 3. **Review and Navigate**: The command returns a list of links, each accompanied by a brief summary to help users quickly identify and access the most relevant files. ## @plan -The `@plan` command prefix within Navie focuses the AI response on building a detailed implementation plan for the relevant query. This will focus Navie on only understanding the problem and the application to generate a step-by-step plan. This will generally not respond with code implementation details, consider using the `@generate` command which can implement code based on the plan. +The `@plan` command prefix within Navie focuses the AI response on building a detailed implementation plan for the relevant query. This will focus Navie on only understanding the problem and the application to generate a step-by-step plan. This will generally not respond with code implementation details, consider using the `@generate` command which can implement code based on the plan. #### Examples -- @plan improve the performance of my slow product listing page. -- @plan implement a cache key for my user posting on my social media application. -- @plan migrate the /users/setting API endpoint from SQL to MongoDB. +- @plan improve the performance of my slow product listing page. +- @plan implement a cache key for my user posting on my social media application. +- @plan migrate the /users/setting API endpoint from SQL to MongoDB. #### `@plan` Video Demo @@ -215,7 +227,7 @@ The `@plan` command prefix within Navie focuses the AI response on building a de ## @generate -The `@generate` prefix will focus the Navie AI response to optimize for new code creation. This is useful when you want the Navie AI to respond with code implementations across your entire code base. This will reduce the amount of code explanation and generally the AI will respond only with the specific files and functions that need to be changed in order to implement a specific plan. +The `@generate` prefix will focus the Navie AI response to optimize for new code creation. This is useful when you want the Navie AI to respond with code implementations across your entire code base. This will reduce the amount of code explanation and generally the AI will respond only with the specific files and functions that need to be changed in order to implement a specific plan. #### Examples @@ -229,24 +241,40 @@ The `@generate` prefix will focus the Navie AI response to optimize for new code ## @test -The `@test` command prefix will focus the Navie AI response to optimize for test case creation, such as unit testing or integration testing. This prefix will understand how your tests are currently written and provide updated tests based on features or code that is provided. You can use this command along with the `@generate` command to create tests cases for newly generated code. +The `@test` command prefix will focus the Navie AI response to optimize for test case creation, such as unit testing or integration testing. This prefix will understand how your tests are currently written and provide updated tests based on features or code that is provided. You can use this command along with the `@generate` command to create tests cases for newly generated code. + +#### Examples + +- @test create integration test cases for the user setting page that is migrated to mongodb. +- @test create unit and integration tests that fully support the updated cache key functionality. +- @test provide detailed test cases examples for testing the updated user billing settings dashboard. + +## @help + +Navie will help you setup AppMap, including generating AppMap recordings and diagrams. This prefix will focus the Navie AI response to be more specific towards help with using AppMap products and features. This will leverage the [AppMap documentation](https://appmap.io/docs) as part of the context related to your question and provide guidance for using AppMap features or diving into advanced AppMap topics. #### Examples -- @test create integration test cases for the user setting page that is migrated to mongodb. -- @test create unit and integration tests that fully support the updated cache key functionality. -- @test provide detailed test cases examples for testing the updated user billing settings dashboard. +- @help how do I setup process recording for my node.js project? +- @help how can I reduce the size of my large AppMap Data recordings? +- @help how can i export my AppMap data to atlassian confluence? ## @review +**Usage Note:** While the `@review` command can be run in the Navie chat window, it is recommended to use the "Review Your Code" button in the Navie sidebar for a more streamlined experience. + +**`review1` and `review2`:** The `@review` command currently supports two versions of review, named `review1` and `review2`. The `review1` format works only within the Navie Chat UI, and so it is being phased out in favor of the `review2` format, which is designed to work with the "Review Your Code" button in the Navie sidebar. The `review2` format provides a more structured and user-friendly experience, integrating seamlessly with the Navie interface. `review1` format is still the default in the Navie chat window, so when running the `@review` command in a Navie chat session, we recommend that you add the `/review2` option to use the new format. + The `@review` command is designed to facilitate thorough code change analysis, leveraging Large Language Models (LLMs) to generate a code diff review that aligns with recognized software engineering standards. This command provides actionable insights on various aspects of code, ensuring alignment with best practices in areas such as code quality, security, and maintainability. Additionally, it allows users to enhance the review by pinning context specific architectural guidelines or design documentation relevant to their project. Navie structures each aspect of the review into actionable sections, clearly highlighting areas of improvement and best practice recommendations.
Navie by default will compare the main branch of your repository with the current HEAD of your branch. If your source branch is a different name, adjust the review command using the /base command. Example: @review /base=master
-#### Key Features +#### Key Features + - **Automated Code Diff Generation**: The `@review` command automatically generates a `git diff` for your code changes, preparing them for a detailed, AI-driven review. - **Comprehensive Standards Check**: The review encompasses critical software engineering principles, including: + - **Correctness**: Ensuring logical accuracy and reliability of the code. - **Code Quality**: Reviewing syntax, structure, and adherence to best coding practices. - **Performance**: Highlighting areas that could impact performance and suggesting optimizations. @@ -258,7 +286,7 @@ Example: @review /base=master - **Custom Contextualization**: Users can pin internal architectural choices or specific design documents to guide Navie's understanding, ensuring that feedback aligns with unique project requirements. -#### How to Use +#### How to Use
  1. @@ -275,15 +303,4 @@ Example: @review /base=master
- - - -## @help - -Navie will help you setup AppMap, including generating AppMap recordings and diagrams. This prefix will focus the Navie AI response to be more specific towards help with using AppMap products and features. This will leverage the [AppMap documentation](https://appmap.io/docs) as part of the context related to your question and provide guidance for using AppMap features or diving into advanced AppMap topics. - -#### Examples - -- @help how do I setup process recording for my node.js project? -- @help how can I reduce the size of my large AppMap Data recordings? -- @help how can i export my AppMap data to atlassian confluence? + diff --git a/docs/using-navie-ai/navie-opening.md b/docs/using-navie-ai/navie-opening.md index 6d24d0f21d..47fe8d5ecf 100644 --- a/docs/using-navie-ai/navie-opening.md +++ b/docs/using-navie-ai/navie-opening.md @@ -19,31 +19,24 @@ redirect_from: [/docs/using-navie-ai/using-navie.html#how-to-open-navie, /docs/n ### In the VS Code Sidebar -You can open Navie in the VSCode sidebar by expanding (if necessary) the Navie section and select the `New Navie Chat` button. +You can open Navie in the VSCode sidebar by expanding (if necessary) the Navie section and selecting the `New Navie Chat` button. - - -### In the AppMap Plugin Instructions Section - -You can Ask Navie by opening the AppMap Instructions drop down and select on the "Ask AppMap Navie". - - + ### Via the VS Code Command Palette You can open the VS Code Command Palette - - Mac: `Cmd + Shift + P` - - Windows/Linux: `Ctrl + Shift + P` -And search for `Navie` +- Mac: `Cmd + Shift + P` +- Windows/Linux: `Ctrl + Shift + P` - +Search for `AppMap Navie` to open a chat, or `AppMap Review` to start a code review. ### Select a code block and use the lightbulb Finally you can open Navie by selecting a block of text and using the lightbulb to ask Navie about your code. - + ## In JetBrains @@ -51,19 +44,19 @@ Finally you can open Navie by selecting a block of text and using the lightbulb You can open the AppMap plugin in your sidebar. - + Then select `New Navie Chat` from Navie menu option. - + ### Via the JetBrains Tools menu option -You can open Navie by clicking on the JetBrains menu option `Tools` -> `AppMap`. From there you can select `Explain with AppMap Navie` +You can open Navie by clicking on the JetBrains menu option `Tools` -> `AppMap`. From there you can select `Explain with AppMap Navie` -AppMap Navie will open as a new tab in your JetBrains editor. +AppMap Navie will open as a new tab in your JetBrains editor. @@ -73,6 +66,6 @@ Normally when asking Navie about your application, AppMap will search through th -**NOTE**: When you "Ask Navie from within an AppMap your questions' context will only include the single AppMap. You can opt to search the entire workspace by selecting the option to "Include the whole workspace". +**NOTE**: When you "Ask Navie from within an AppMap your questions' context will only include the single AppMap. You can opt to search the entire workspace by selecting the option to "Include the whole workspace". - \ No newline at end of file + diff --git a/docs/using-navie-ai/navie-options.md b/docs/using-navie-ai/navie-options.md index 394a846616..b859667189 100644 --- a/docs/using-navie-ai/navie-options.md +++ b/docs/using-navie-ai/navie-options.md @@ -4,7 +4,7 @@ title: Docs - AppMap Navie description: "Reference Guide to AppMap Navie AI, a complete list of options available in AppMap Navie AI." name: Navie Options navie: true -step: 5 +step: 6 toc: true --- diff --git a/docs/using-navie-ai/navie-review.md b/docs/using-navie-ai/navie-review.md new file mode 100644 index 0000000000..e66724e635 --- /dev/null +++ b/docs/using-navie-ai/navie-review.md @@ -0,0 +1,71 @@ +--- +layout: docs +title: Docs - Navie +name: Review Your Code +step: 4 +navie: true +description: Use AppMap Navie to review your code. The Review Your Code command analyzes your code changes and provides a comprehensive report to help you improve code quality, security, and performance. +--- + +# Review Your Code + +The `Review Your Code` command analyzes your code changes and provides a comprehensive report to help you improve code quality, security, and performance. This document describes the output of the command and how you can interact with it. + +## Starting a Review + +To start a review, open the Navie sidebar and click the `Review Your Code` button. You can also start a review using the command palette or command menu. + +### VSCode + +Command Palette: `Cmd + Shift + P` (Mac) or `Ctrl + Shift + P` (Windows/Linux), followed by typing `AppMap: Review Your Code`. + + + +### JetBrains + +From the menu, navigate to `Tools` → `AppMap` → `Review Your Code`. + +## Suggestions Overview + +The core of the review provides specific, actionable suggestions for improving the code. Suggestions are grouped by category (e.g., `Security`, `Performance`, `SQL`, `HTTP`) and prioritized as `high`, `medium`, or `low`. + +Each suggestion includes: + +- **Category:** The type of suggestion (e.g., `Security`, `Performance`, `SQL`, `HTTP`). +- **Priority:** The urgency of the suggestion, which can be `high`, `medium`, or `low`. +- **Description:** A short summary of the suggestion (e.g., "N+1 query detected"). +- **Location:** The file and line number where the suggestion applies. +- **Code Snippet:** The relevant lines of code for context. +- **AppMap References:** When a suggestion is derived from runtime analysis, it will include links to the AppMap sequence diagrams that provide evidence for the suggestion. + +## Triage Actions + +After receiving a review, you can perform triage on the reported suggestions and features to manage the feedback and integrate it into your workflow. + +### Interacting with Suggestions + +Each suggestion is an individual item that you can act upon. The following actions are available: + +- **Fix:** Use this action to launch a Navie window that will automatically run a sequence of commands to fix the issue. +- **Mark as Done:** Once you have implemented a suggestion, you can mark it as Done. +- **Dismiss:** If a suggestion is not applicable or you do not wish to act on it, you can dismiss it. This helps the tool refine its analysis and avoid suggesting the same item in future reviews. + +## Command-Line Usage + +To perform this review using the command line, you can use the following command: + +```bash +appmap navie "@review /review2 /base= /format=" +``` + +**base** + +The base branch is optional, and defaults to `main`, `master`, or `develop`, depending on the Git history of the current project. The base branch can be any name that Git recognizes, such as a tag or a specific commit hash. + +**format** + +The command can produce output in several formats: + +- **`text` (Default):** A human-readable Markdown report, suitable for viewing in a terminal or a text editor. +- **`json`:** A single JSON object that contains the complete review report. This is useful for programmatic analysis. +- **`jsonl`:** A stream of newline-delimited JSON objects. This format is ideal for processing results incrementally. diff --git a/docs/using-navie-ai/navie-workflow.md b/docs/using-navie-ai/navie-workflow.md index c0e528f14e..8765104722 100644 --- a/docs/using-navie-ai/navie-workflow.md +++ b/docs/using-navie-ai/navie-workflow.md @@ -3,11 +3,12 @@ layout: docs title: Docs - AppMap Navie description: "Learn how to use AppMap Navie to provide personalized code analysis. Generate AppMap Data, ask Navie questions, analyze code, and iterate for optimal results." name: Navie Command Workflow -step: 4 +step: 5 navie: true toc: true redirect_from: [/docs/guides/navie-best-practices, /docs/navie/using-navie] --- + # Navie Command Workflow AppMap Navie is designed to help you solve issues and add features in your codebase by leveraging runtime data and AI-driven commands. By following a structured workflow, you can maximize Navie’s capabilities to plan, generate, and verify your code changes with precision. This guide outlines the recommended workflow and provides an overview of the key command modes used throughout the process. @@ -22,7 +23,7 @@ To achieve the highest quality results when using Navie, we suggest using the fo The @explain command helps you learn more about your project. It prompts Navie to be more explanatory and dive into architectural level questions pulling information from across your entire code base. 2. **@diagram** -The @diagram command prompts Navie to create visual diagrams such as sequence diagrams, class diagrams, and flow charts. These diagrams are based on the code and runtime data associated with the issue or feature. Navie diagrams are exportable, compatible with Mermaid, and can be used to enhance technical documentation or shared with team members. + The @diagram command prompts Navie to create visual diagrams such as sequence diagrams, class diagrams, and flow charts. These diagrams are based on the code and runtime data associated with the issue or feature. Navie diagrams are exportable, compatible with Mermaid, and can be used to enhance technical documentation or shared with team members. 3. **@plan** The @plan command helps you generate a step-by-step, multi-file plan that aligns with your application's design. Based on the issue you are working on, Navie will propose a solution with code snippets, flow charts, and runtime context to ensure accuracy. @@ -33,22 +34,21 @@ The @diagram command prompts Navie to create visual diagrams such as sequence di 5. **@test** Navie can also assist in generating and refining test cases. The @test command is used to generate tests for both new and existing code to ensure functionality and catch breaking behaviors. -6. **@review** - Finally, the @review command allows you to compare the newly generated code with your existing codebase, ensuring that the changes are in line with the desired functionality and do not introduce regressions. - +6. **Review Your Code** + Use the `Review Your Code` feature to analyze your code changes and receive a comprehensive report. This feature helps you improve code quality, security, and performance by providing specific, actionable suggestions. You can find the `Review Your Code` button in the Navie sidebar, or you can use the command palette (VSCode) or AppMap menu (JetBrains) to start a review. #### Step-by-Step Example of Solving an Issue with Navie -The Navie command modes are available to be used in any sequence at any time. However, building up understanding through the iteration of the following process has proven to maximize the quality and consistency of positive results. - -{% include vimeo.html id='1012769182' %} +The Navie command modes are available to be used in any sequence at any time. However, building up understanding through the iteration of the following process has proven to maximize the quality and consistency of positive results. +{% include vimeo.html id='1102292990' %} ##### Step 1: Collect Data and Plan the Solution + Copy the details of your issue, including the steps to reproduce it, into Navie using the `@plan` command. ```plaintext -@plan +@plan ``` @@ -71,27 +71,30 @@ When you ask Navie a question, the default mode is `@explain`, which you can use Supported diagram types include sequence diagram, flow chart, entity-relationship, and class diagram. ```plaintext -@diagram +@diagram ``` + If AppMap data is available for the issue you're working on, Navie will have a deep understanding of your application's architecture. This enhances the quality of insights you receive when asking questions. Navie can search through your AppMap data to pinpoint the files, methods, and external services involved in processes like user registration. Navie can also provide **comparative analysis and recommendations** based on patterns in your existing codebase. ##### Step 3: Generating Code + Once the plan is confirmed, use the `@generate` command to produce the necessary code changes. ```plaintext -@generate +@generate ``` Navie will generate code based on the approved plan, updating multiple files if needed. The changes will be consistent with your project’s architecture and runtime context. ##### Step 4: Testing the Changes -The `@test` command helps you generate test cases. It works best when you specify the code that you want to test. You can do this by selecting the relevant code directly or by indicating the files to be tested in your conversation with Navie. +The `@test` command helps you generate test cases. It works best when you specify the code that you want to test. You can do this by selecting the relevant code directly or by indicating the files to be tested in your conversation with Navie. To guide Navie, you can: + - Pin files containing the code you want to test in the Navie context window - Select code and use the lightbulb icon in your editor (VS Code or JetBrains) to add it to the conversation. @@ -103,6 +106,10 @@ This way, Navie knows exactly what to focus on and can generate precise, relevan After Navie generates test cases, insert them into your project’s test suite and run them using your test framework. Navie ensures that all test cases pass successfully. +##### Step 5: Review + +By creating and running test cases, you've generated AppMap runtime data that can be used in the code review process. Use the `Review Your Code` feature to analyze your code changes and receive a comprehensive report. This feature helps you improve code quality, security, and performance by providing specific, actionable suggestions. + --- AppMap Navie empowers developers to solve issues and implement features efficiently by combining runtime data, AI planning, and code generation. Using commands like `@explain`, `@plan`, `@generate`, `@test`, and `@diagram`, Navie offers a streamlined approach to addressing codebase changes with minimal manual intervention. Follow the recommended workflow and utilize these powerful commands to improve your development process while maintaining high-quality code.