@appland/appmap 3.133.0 → 3.134.0

package/built/docs/navie/bring-your-own-key.md

@@ -0,0 +1,98 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+name: Bring Your Own Key
+step: 4
+navie: true
+toc: true
+---
+
+# Bring Your Own Key (BYOK)
+
+By default, when asking a question to Navie, your code editor will interact with the AppMap hosted proxy for OpenAI.  If you have a requirement to bring your own key or otherwise use your own OpenAI account you can follow these steps to update the OpenAI key.  Refer to the Navie Docs for more details about [Navie technical architecture](/docs/navie/how-navie-works).
+
+- [Add a new OpenAI Key](#add-a-new-openai-key)
+- [Delete a configured OpenAI Key](#delete-a-configured-openai-key)
+- [Check the status of your OpenAI key](#check-the-status-of-your-openai-key)
+- [FAQs](#faqs)
+  - [How is my API key saved securely?](#how-is-my-api-key-saved-securely)
+
+## Add a new OpenAI Key
+
+In VS Code, open the Command Palette.
+
+You can use a hotkey to open the VS Code Command Palette
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+Or you can select `View` -> `Command Palette`
+
+<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
+
+Search for `AppMap Set OpenAPI Key`
+
+<img class="video-screenshot" src="/assets/img/product/byok-search.webp"/> 
+
+Paste your key into the new field and hit enter.
+
+You'll get a notification in VS Code that your key is set. 
+
+**NOTE:** You will need to reload your window for the setting to take effect. Use the Command Palette `Developer: Reload Window`
+
+<img class="video-screenshot" src="/assets/img/product/byok-key-set.webp"/> 
+
+## Delete a configured OpenAI Key
+
+To delete your key, simply open the Command Palette
+
+You can use a hotkey to open
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+Or you can select `View` -> `Command Palette`
+
+<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
+
+Search for `AppMap Set OpenAPI Key`
+
+<img class="video-screenshot" src="/assets/img/product/byok-search.webp"/> 
+
+And simply hit enter with the field blank.  VS Code will notify you that the key has been unset.
+
+**NOTE:** You will need to reload your window for the setting to take effect. Use the Command Palette `Developer: Reload Window`
+
+<img class="video-screenshot" src="/assets/img/product/byok-key-erased.webp"/> 
+
+## Check the status of your OpenAI key
+
+To check if you are using the AppMap hosted proxy or your own API Key open the Command Palette.
+
+You can use a hotkey to open
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+Or you can select `View` -> `Command Palette`
+
+<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
+
+Search for `Check Key Status`
+
+<img class="video-screenshot" src="/assets/img/product/byok-check-status.webp"/> 
+
+Select `Check OpenAI API Key Status`
+
+The code editor will respond a notifiction in the bottom corner with your latest status.
+
+<img class="video-screenshot" src="/assets/img/product/byok-check-status-resp.webp"/> 
+
+
+# FAQs
+
+## How is my API key saved securely?
+
+For secure storage of API key secrets within AppMap, we use the default VS Code secreat storage which leverages  Electron's safeStorage API to ensure the confidentiality of sensitive information. Upon encryption, secrets are stored within the user data directory in a SQLite database, alongside other VS Code state information. This encryption process involves generating a unique encryption key, which, on macOS, is securely stored within Keychain Access under "Code Safe Storage" or "Code - Insiders Safe Storage," depending on the version. This method provides a robust layer of protection, preventing unauthorized access by other applications or users with full disk access. The safeStorage API, accessible in the main process, supports operations such as checking encryption availability, encrypting and decrypting strings, and selecting storage backends on Linux. This approach ensures that your secrets are securely encrypted and stored, safeguarding them from potential threats while maintaining application integrity.
+
+
+
+
+

package/built/docs/navie/demo.md

@@ -0,0 +1,49 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+name: Demo
+step: 5
+navie: true
+---
+
+# Video Demo
+
+**In this video**
+
+We use Navie to learn how to add a custom offline captcha to a Django powered web store.  We will generate AppMaps of our user registration process, and then ask Navie for where and how to add this feature. By using Retrieval-Augmented Generation, our answers from the Generative AI are highly specific to our codebase and how it operates allowing me to quicking find exactly where to add a new feature even while having little previous knowledge of this code base. 
+
+{% include vimeo.html id='915670906' %}
+
+## Follow Along
+
+I'm here today to show you how to use the new AppMap Navie. AppMap Navie isn't just another AI code assistant, it's the missing link that improves the power of AI code completers and code assistants. Leveraging the unique ability that AppMap has to understand your code's execution at runtime, Navie transforms this data into a powerhouse of hyper-personalized context-aware insights for AI-assisted coding. That means you're not just working with static analysis anymore, and you're not looking at just individual files or functions. You're stepping into a realm where Navie can understand the entire codebase at an architectural level, how it behaves and executes, and provide much more detailed answers to your software questions.
+
+So in this example, I'm a software engineer working on a Django-powered web store. I've been tasked with adding a captcha for the registration page here. I've got AppMap installed with my project already, which means as I interact with my registration page, it will generate AppMaps automatically for my service. You can also use tests to interact with any part of your application to generate AppMaps. You can see here navigating these AppMaps, I can see this API request all the way down to the database and all the code in between.
+
+<img class="video-screenshot" src="/assets/img/docs/navie-demo-1.webp"/> 
+
+So now I can use this data to ask AppMap Navie what areas of my codebase are involved in the new user registration service because I want to find the files so that I can add an offline captcha. AppMap Navie will now search through all of my AppMaps and provide the detailed runtime sequence diagrams as additional context to the generative AI. You can use the AppMap-provided GPT-4 models or bring your own API keys. I can search through my AppMap data based on my request and send this data along to the generative AI service to get a much clearer view into exactly what files I need to find and edit.
+
+<img class="video-screenshot" src="/assets/img/docs/navie-demo-2.webp"/> 
+
+If I was using an AI-powered code autocompleter, I would need to already know what files or functions that this request hits. I would actually need to be in the function to make this code change. AppMap sees how my code executes and Navie provides the AI with the context. I get very clear and direct insight into exactly where I need to make this code change.
+
+<img class="video-screenshot" src="/assets/img/docs/navie-demo-3.webp"/> 
+
+Now that Navie has summarized how this feature works and walked me through the code interactions, I'm going to ask for more specific information on how to implement this change. Let's review what it recommended. First, it's going to want me to install the Django Simple Captcha service, which we'll do here. Then we're going to add the application to our settings file. 
+
+Next, we're going to update this line here in our urls.py file. In the next step, we need to update the registration form at forms.py. We'll go open that file here and add the first line to import the package. In the next section, we need to add the Captcha to the form, but it didn't tell us which specific function we need to add that in. Looking through this code, I'm really not sure where I need to add this, so I think it's time we ask another question.
+
+We'll ask Navie about this specific library, giving it this additional context, and you'll see a simple example on where we can add this feature will be given back to us. Upon asking this question with more specific context, you'll notice that Navie is telling us to add this to the email user creation form.
+
+<img class="video-screenshot" src="/assets/img/docs/navie-demo-4.webp"/> 
+
+Now, let's go back to that file and search for that function. And now we can see right here is where we'll add the Captcha in the right location. So we've already added it to our installed apps, but we have not yet run a database migration, so I'm going to do that now. With our database migration executed, we can continue the steps and update the HTML template for the registration page, which I can search for here.
+
+Using this registration template, we can copy the code over from Navie and paste it into this section above the submit button. Let's refresh our page now and head over to the registration portal, and you'll see this new Captcha field has been created. So let's test this out. We'll fill this form out and complete the Captcha correctly, and the user account gets created. 
+
+<img class="video-screenshot" src="/assets/img/docs/navie-demo-5.webp"/> 
+
+Now we'll do that one more time, but we'll register our account with an invalid Captcha. You'll see that registration has failed and the user was notified that the Captcha was incorrect.
+
+Now you can see how AppMap improves the AI coding experience across your entire application.  If you asked asked similar questions to a standard AI assistant you would only get generic answers based on existing public knowledge. Without knowledge of your code, these generic reponses will leave you continuing to hunt and search thru a complex code base.  With AppMap able to see all of your codes runtime behavior, it can now provide context-aware insights to power these hyper-personalized responses to your software questions in your code editor.  

package/built/docs/navie/how-navie-works.md

@@ -0,0 +1,26 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+name: How Navie Works
+step: 2
+navie: true
+---
+
+# How Navie Works
+
+Navie uses your existing AppMap data to improve the accuracy and reliability of Generative AI models using Retrieval-Augmented Generation (RAG). When a question is asked to the Navie chat interface, AppMap will search through your locally stored AppMaps to identify the most relevant maps related to your question. Then Navie will use these maps to identify the relevant code snippets related to the question.  This corpus of data becomes the context provided to the Generative AI service which includes your original question. 
+
+This powerful technique provides the AI with many valuable pieces of information:  
+1) Runtime sequence diagram information of your application
+2) Relevant source code files and snippets involved or related to your question.  
+3) Granular application tracing data.
+4) Detailed insights into data flows, SQL queries, and other database interactions.
+
+
+## Navie Technical Architecture
+
+Navie integrates seamlessly into your existing AppMap enabled project.  Once you have the AppMap software libraries installed into your project, interact with your application or run tests to automatically generate AppMap data. All of your code and AppMap data will stay locally in your environment until you ask Navie a question.  After asking a question to Navie, the relevant AppMaps and code snippets are located locally by the AppMap search and explain API, then this data is sent to OpenAI (available option to bring your own LLM), and the response is returned to the user. 
+
+<img class="video-screenshot" src="/assets/img/product/navie-architecture.webp"/> 
+
+For more details about the privacy and security of your AppMap data, refer to the [AppMap Security FAQ](https://appmap.io/security)

package/built/docs/navie/how-to-use-navie.md

@@ -0,0 +1,152 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+name: How to use Navie
+step: 3
+navie: true
+toc: true
+---
+
+# How to Use Navie
+
+When you ask a question to Navie, it will search through all your AppMaps created for your project to pull in relevant traces, sequence diagrams, and code snippets for analysis.  It will then send these code snippets and runtime code sequence diagrams to the Generative AI service along with your question.  By sending this valuable context to the AI interface, your answers will be much more personal and specific to your codebase, files, and functions. Additionally, the Generative AI will be able to understand how your code works at runtime and will be able to make architectural level recommendations across your entire application. 
+
+- [How to Open Navie](#how-to-open-navie)
+  - [In VS Code](#in-vs-code)
+  - [In JetBrains](#in-jetbrains)
+- [How to Generate the Highest Quality Answers](#how-to-generate-the-highest-quality-answers)
+  - [Create AppMaps](#create-appmaps)
+  - [Ask Navie](#ask-navie)
+  - [Write Code](#write-code)
+  - [Repeat](#repeat)
+- [Next Steps](#next-steps)
+
+## How to Open Navie
+
+There are three ways to access Navie in your code editor:
+- [How to Open Navie](#how-to-open-navie)
+  - [In VS Code](#in-vs-code)
+    - [In the AppMap Plugin Instructions Section](#in-the-appmap-plugin-instructions-section)
+    - [Via the VS Code Command Palette](#via-the-vs-code-command-palette)
+    - [Select a code block and use the lightbulb](#select-a-code-block-and-use-the-lightbulb)
+  - [In JetBrains](#in-jetbrains)
+    - [In the AppMap Sidebar Plugin](#in-the-appmap-sidebar-plugin)
+    - [Via the JetBrains Tools menu option](#via-the-jetbrains-tools-menu-option)
+- [How to Generate the Highest Quality Answers](#how-to-generate-the-highest-quality-answers)
+  - [Create AppMaps](#create-appmaps)
+  - [Ask Navie](#ask-navie)
+  - [Write Code](#write-code)
+  - [Repeat](#repeat)
+- [Next Steps](#next-steps)
+
+### In VS Code
+
+#### In the AppMap Plugin Instructions Section
+
+You can Ask Navie by opening the AppMap Instructions drop down and select on the "Ask AppMap Navie AI".
+
+<img class="video-screenshot" src="/assets/img/product/navie-navigation.webp"/> 
+
+#### 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`
+
+<img class="video-screenshot" src="/assets/img/product/command-palette-navie.webp"/> 
+
+#### 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.
+
+<img class="video-screenshot" src="/assets/img/product/lightbulb.webp"/> 
+
+### In JetBrains
+
+#### In the AppMap Sidebar Plugin
+
+You can open the AppMap plugin in your sidebar.
+
+<img class="video-screenshot" src="/assets/img/product/appmap-sidebar.webp"/> 
+
+Then select Ask AppMap Navie AI from the Instructions section.
+
+<img class="video-screenshot" src="/assets/img/product/ask-navie-vscode.webp"/>
+
+#### 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 AI`
+
+<img class="video-screenshot" src="/assets/img/product/tools-appmap-vscode.webp"/>
+
+AppMap Navie will open as a new tab in your JetBrains editor. 
+
+<img class="video-screenshot" src="/assets/img/product/ask-navie-vscode-window.webp"/>
+
+## How to Generate the Highest Quality Answers
+
+To generate the highest quality responses from Navie, we recommend the following approach. 
+  
+- [Create AppMaps](#create-appmaps)
+- [Ask Navie](#ask-navie)
+- [Write Code](#write-code)
+- [Repeat](#repeat)
+
+### Create AppMaps
+
+We recommend creating maps that are most relevant to the question or area of the application you are going to be working with. For example, if i wanted to understand how my new user registration flow worked I could [create a remote recording](/docs/setup-appmap-in-your-code-editor/generate-appmaps-with-remote-recording) of a new user registration flow. Alternatively, I could [run all the test cases](/docs/setup-appmap-in-your-code-editor/generate-appmaps-from-tests) related to new user creation, registration, and adjacent areas. 
+
+Depending on your language and framework there [are up to 5 different ways](/docs/setup-appmap-in-your-code-editor/how-appmap-works.html#recording-methods) that you can record AppMaps for your application.
+
+1. **[Test Case Recording](/docs/setup-appmap-in-your-code-editor/generate-appmaps-from-tests.html)**: This method is particularly useful for automated testing environments. AppMap integrates with numerous testing frameworks, creating individual AppMaps for each test case run. These AppMaps include detailed information such as the test framework, test case names, and their outcomes, enabling a comprehensive overview of test coverage and facilitating easier debugging and performance optimization.
+
+2. **[Requests Recording](/docs/setup-appmap-in-your-code-editor/generate-appmaps-with-request-recording)**: Ideal for web applications, this method records each HTTP request processed by your application. By simply running your application with the AppMap agent and interacting with it—either manually or through automated scripts—you can generate a rich dataset of AppMaps that capture the full scope of your application's request handling.
+
+3. **[Remote Recording](https://appmap-io-pr-1253.onrender.com/docs/setup-appmap-in-your-code-editor/generate-appmaps-with-remote-recording)**: Similar to request recording but offering more control over the recording session. You initiate and stop recording via HTTP commands, allowing the inclusion of multiple requests and other non-HTTP activities within a single AppMap. This method is particularly suited for capturing detailed interactions within web applications, including background jobs and other processes.
+
+4. **Code Block Recording**: Provides the highest level of control, enabling you to specify exactly which blocks of code to record by inserting simple code snippets. This method requires source code access and is a powerful option for targeting specific functionalities or debugging complex issues. (Code Block recording is language specific, refer to [the language reference docs for examples](/docs/reference)).
+
+5. **Process Recording**: A broader approach that records all activity within the configured scope of your application, from startup to shutdown. This method is useful when other methods are not applicable or when you need a comprehensive capture of your application's behavior. (Process recording is language specific, refer to [the language reference docs for examples](/docs/reference)).
+
+Each of these methods generates AppMaps in JSON format, which are then visualized through interactive diagrams in your code editor. This visualization supports a deep understanding of your application's architecture, dependencies, and runtime behavior, facilitating enhanced code quality and performance optimization.
+
+### Ask Navie
+
+Navie, can address a wide range of questions about your application, extending beyond what static analysis AI assistants can provide, to understand dynamic interactions, dependencies, and performance bottlenecks to help your developers design and deliver solutions faster for a host of complex issues.
+
+AppMap includes Dynamic Code Analysis rules which can be customized to flag specific code issues. Refer [to the AppMap rules reference](/docs/reference/analysis-rules) for a complete list of issues that can be identified.
+
+**Examples of good questions to ask Navie.**
+
+* Why is `behavior X` happening in dev and not in production?
+* Why did the `feature x` return a 500 error?
+* How can I make `feature x` use the database more efficiently?
+* What can I do to optimize the queries on this page?
+* Where does user registration happens in my code base? 
+* Provide a solution to add Google OAuth login support for my user login pages. 
+* Explain what functions or files are involved when a user logs into my service. 
+* Loading the "products" view page is slow in production, provide suggested guidance with relevant code changes I can make to improve the speed.
+
+### Write Code
+
+Navie can do more than just provide code implementation details, you can talk to Navie about a variety of other topics as you are updating your application based on it's recommendations. 
+
+1. **Identifying Components**: Navie can search through your AppMaps to highlight the files, methods, and external services interacting during the registration process, offering runtime sequence diagrams for clarity.
+
+2. **Implementation Guidance**: After identifying the areas of interest, you might need specific implementation advice. For instance, where and how to integrate third-party libraries into your existing codebase. Navie can provide detailed instructions on modifying settings files, updating URL configurations, and extending forms with new functionalities.
+
+3. **Debugging and Optimization**: Beyond initial implementation, Navie can assist in debugging by pointing out potential sources of errors or inefficiencies in the code paths triggered during user interactions.
+
+4. **Comparative Analysis and Recommendations**: By analyzing the runtime behavior and execution flow, Navie can offer recommendations to enhance performance, improve security, or reduce technical debt, backed by the rich data context of your application's actual operations.
+
+5. **Custom Queries**: Tailor your questions to fit unique development needs—whether you're troubleshooting a specific error, seeking optimization opportunities, or curious about the interactions between various components of your application.
+
+### Repeat
+
+Continue to ask follow-up question to Navie as you are making code changes or when you need additional details or more specific advice.  Additionally, as you make changes to your application, continue recording AppMaps of the updated code interactions and start new conversations with Navie to dive deeper into your feature implementation. 
+
+## Next Steps
+
+Watch: [Demo of using AppMap Navie to add a new feature to a complex application.](/docs/navie/demo)

package/built/docs/navie/index.md

@@ -0,0 +1,20 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+name: index
+step: 1
+---
+
+# AppMap Navie
+
+AppMap Navie is the missing link that improves the power of AI code completers and code assistants. Leveraging the unique ability that AppMap has to understand your code's execution at runtime, Navie transforms this data into a powerhouse of hyper-personalized context-aware insights for AI-assisted coding. 
+
+That means you're not just working with static analysis anymore, and you're not looking at just individual files or functions. With Navie, you can understand the entire codebase at an architectural level, how it behaves and executes, and provide much more detailed answers to your software questions.
+
+- [How Navie Works](/docs/navie/how-navie-works)
+- [How to use Navie](/docs/navie/how-to-use-navie)
+- [Video Demo](/docs/navie/demo)
+
+**Install AppMap for your preferred code editor to get started.**
+
+<a class="btn btn-primary btn-lg" href="https://appmap.io/get-appmap">Get AppMap</a>

package/built/docs/reference/analysis-labels.md

@@ -0,0 +1,48 @@
+---
+layout: docs
+title: Docs - Reference
+name: Analysis Labels
+step: 14
+reference: true
+redirect_from: [/docs/analysis/labels-reference]
+---
+
+# Label Reference
+<ul class="toc">
+{% for analysis_label in site.analysis_labels %}
+  <li>
+    <a href="#{{ analysis_label.name }}">{{analysis_label.name }}</a>
+  </li>
+{% endfor %}
+</ul>
+
+
+<ul class="analysis-doc-list label">
+  {% for analysis_label in site.analysis_labels %}
+    <li class="analysis-label" id="{{ analysis_label.name }}">
+      <h2>
+        {{ analysis_label.name }}
+      </h2>
+
+      <div class="analysis-metrics">
+        <ul>
+          <li class="name">Rules</li>
+          <li class="value">
+            {% for rule in analysis_label.rules %}
+              <a href="./analysis-rules.html#{{rule}}">
+                {{ rule }}
+              </a>
+              <br/>
+            {% endfor %}
+          </li>
+        </ul>
+      </div>
+
+      {{ analysis_label.content | markdownify }}
+    </li>
+    <hr/>
+{% endfor %}
+</ul>  
+
+
+

package/built/docs/reference/analysis-rules.md

@@ -0,0 +1,60 @@
+---
+layout: docs
+title: Docs - Reference
+name: Analysis Rules
+step: 13
+reference: true
+---
+
+# Rules Reference
+<ul class="toc">
+{% for analysis_rule in site.analysis_rules %}
+  <li>
+    <a href="#{{ analysis_rule.rule }}">{{analysis_rule.name }}</a>
+  </li>
+{% endfor %}
+</ul>
+
+<ul class="analysis-doc-list">
+{% for analysis_rule in site.analysis_rules %}
+  <li class="analysis-rule" id="{{ analysis_rule.rule }}">
+    <h2>
+      {{ analysis_rule.name }}
+    </h2>
+
+    <div class="analysis-metrics">
+      <ul>
+        <li class="name">Id</li>
+        <li class="value">{{ analysis_rule.rule }}</li>
+      </ul>
+      <ul>
+        <li class="name">Impact Domain</li>
+        <li class="value">{{ analysis_rule.impactDomain }}</li>
+      </ul>
+      <ul>
+        <li class="name">Scope</li>
+        <li class="value">{{ analysis_rule.scope }}</li>
+      </ul>
+      <ul>
+        <li class="name">Labels</li>
+        <li class="value">
+          {% for label in analysis_rule.labels %}
+            <a href="./analysis-rules.html#{{ label }}">{{ label }}</a>
+            <br/>
+          {% endfor %}
+        </li>
+      </ul>
+      <ul>
+        <li class="name">References</li>
+        <li class="value">
+          {% for reference in analysis_rule.references %}
+            <a href="{{ reference[1] }}" target="_blank">{{ reference[0] }}</a>
+          {% endfor %}
+        </li>
+      </ul>
+    </div>
+    {{ analysis_rule.content | markdownify }}
+  </li>
+  <hr/>
+{% endfor %}
+</ul>