Create VS Code extension for AML (#333)

.dockerignore

@@ -104,9 +104,9 @@ backend/priv/static/elm/**/dist
 backend/priv/static/elm/**/script.js
 backend/priv/static/elm/**/script.js.map
 
-# flyctl launch added from browser-extension/.gitignore
-browser-extension/**/dist
-browser-extension/**/node_modules
+# flyctl launch added from extensions/browser-extension/.gitignore
+extensions/browser-extension/**/dist
+extensions/browser-extension/**/node_modules
 
 # flyctl launch added from frontend/.gitignore
 frontend/.coverage

.gitignore

@@ -8,6 +8,6 @@ addon-manifest.json
 addon-manifest-prod.json
 addon-manifest-staging.json
 addon-clevercloud.json
-.vscode/
+/.vscode
 charts/azimutt/charts/
 charts/azimutt/Chart.lock

.pre-commit-config.yaml

@@ -189,8 +189,8 @@ repos:
       pass_filenames: false
       files: cli/.*\.ts*$
 
-    # No test or build for browser-extension
-    # No test or build for desktop
+    # No test or build for extensions/browser-extension
+    # No test or build for extensions/desktop
 
 - repo: https://github.com/commitizen-tools/commitizen
   rev: v2.32.2

backend/.gitignore

@@ -35,3 +35,4 @@ npm-debug.log
 /priv/static/swagger*.json
 /assets/js/*.js
 /uploads
+/.vscode

backend/lib/azimutt_web/templates/website/docs/create-your-project.html.heex

@@ -2,8 +2,8 @@
 
 <%= doc_prose do %>
     <p class="lead">
-        Azimutt explorer has several ways to import your schema. The suggested one being the <a href="#from-database">database connection</a>
-        as it's more reliable and offer more features (see below) but you have many other options if you prefer.
+        Azimutt explorer has several ways to import your database schema. The suggested one is the <a href="#from-database">database connection</a>
+        as it's more reliable and offers more features (see below) but you have many other options if you prefer.
         <img src={Routes.static_path(@conn, "/images/doc/new-project.png")} alt="New Azimutt project">
     </p>
 
@@ -21,7 +21,7 @@
         Quite awesome if you ask me 😉
     </p>
     <p>
-        For more details, you can have a look at the connectors to see exactly what and how its being done, here are the scripts for
+        For more details, you can have a <a href={Routes.website_path(@conn, :connectors)}>look at the connectors</a> to see exactly what and how its being done, here are the scripts for
         <a href="https://github.com/azimuttapp/azimutt/blob/main/libs/connector-postgres/src/postgres.ts" target="_blank">PostgreSQL</a>,
         <a href="https://github.com/azimuttapp/azimutt/blob/main/libs/connector-mysql/src/mysql.ts" target="_blank">MySQL</a> and
         <a href="https://github.com/azimuttapp/azimutt/blob/main/libs/connector-mongodb/src/mongodb.ts" target="_blank">MongoDB</a>.
@@ -36,7 +36,7 @@
     <p>
         If you just want to explore your database schema, you can upload it as SQL statements (CREATE TABLE, CREATE INDEX, COMMENTS and others).
         You can do it safely as <strong>nothing will be sent to Azimutt servers</strong>,
-        the parsing is made on the frontend and your schema is shown with no business data being sent to Azimutt server.
+        the parsing is made on the frontend and your schema is shown with no business data sent to Azimutt.
         <img src={Routes.static_path(@conn, "/images/doc/new-project-sql.png")} alt="New Azimutt project with SQL file">
     </p>
     <p>
@@ -45,15 +45,15 @@
 
     <%= render "docs/_h2.html", title: "From Prisma" %>
     <p>
-        <a href="https://www.prisma.io" target="_blank" rel="noopener noreferrer" class="underline">Prisma</a> is a Node.jS and TypeScript ORM
+        <a href="https://www.prisma.io" target="_blank" rel="noopener noreferrer" class="underline">Prisma</a> is a Node.js and TypeScript ORM
         that use its own <a href="https://www.prisma.io/docs/orm/prisma-schema" target="_blank" rel="noopener noreferrer" class="underline">schema syntax</a>.
         Same as SQL, you can import the file in Azimutt, local or remote.
     </p>
 
     <%= render "docs/_h2.html", title: "From JSON" %>
     <p>
         If you have a database that is not supported yet by Azimutt,
-        you can <a href="https://github.com/azimuttapp/azimutt/issues" target="_blank" rel="noopener noreferrer">create an issue</a> (or vote on the existing one),
+        you can <a href="https://github.com/azimuttapp/azimutt/issues" target="_blank" rel="noopener noreferrer">create an issue</a> (or vote on the existing ones),
         send a Pull Request (look at <a href="https://github.com/azimuttapp/azimutt/tree/main/libs" target="_blank" rel="noopener noreferrer">other connectors</a>) or
         extract its schema on your own and <a href={"#{Routes.elm_path(@conn, :new)}?json"} target="_blank" rel="noopener noreferrer">import it as JSON</a> in Azimutt.
         You just have to format it according to the JSON Schema below the import section.

backend/lib/azimutt_web/templates/website/docs/getting-started.html.heex

@@ -1,2 +1,9 @@
 <%= render "docs/_header.html", conn: @conn, page: @page %>
+
+<%= doc_prose do %>
+    <p class="lead">
+        Now let's dig into the main Azimutt topics.
+    </p>
+<% end %>
+
 <%= render "docs/_footer.html", conn: @conn, page: @page, prev: @prev, next: @next %>

backend/lib/azimutt_web/templates/website/docs/what-is-azimutt.html.heex

@@ -2,8 +2,8 @@
 
 <%= doc_prose do %>
     <p class="lead">
-        Azimutt goal is to make databases way more accessible for everyone who want or need to understand them.
-        For that we have built several tools, the biggest one being the <a href="#azimutt-explorer">explorer</a>,
+        Azimutt goal is to make databases way more accessible for everyone who need or want to understand them.
+        For that we have built several tools, the main one being the <a href="#azimutt-explorer">explorer</a>,
         but there is also other interesting ones like the <a href="#azimutt-cli">CLI</a> and <a href="#azimutt-converters">converters</a>.
     </p>
 
@@ -17,6 +17,7 @@
         The Gateway is the central piece allowing Azimutt to connect to any database.
         It's a simple Node.js server with all the databases connector allowing Azimutt editor frontend to access databases.
         It can be launched locally using <code>npx azimutt@latest gateway</code>, hosted in your infrastructure or using the Azimutt one if your database is accessible over internet.
+        <a href={Routes.website_path(@conn, :doc, ["gateway"])}>Learn more</a> about it.
     </p>
 
     <%= render "docs/_h2.html", title: "Azimutt CLI" %>
@@ -30,11 +31,13 @@
             <li>Analyze your database</li>
             <li>More to come soon...</li>
         </ul>
+        <a href={Routes.website_path(@conn, :doc, ["cli"])}>Learn more</a> about it.
     </p>
 
     <%= render "docs/_h2.html", title: "Azimutt converters" %>
     <p>Azimutt is doing a lot of work around database schemas. We took this opportunity to build these <a href={Routes.website_path(@conn, :convert, "aml", "postgres")}>standalone converters</a> to be easily accessible:</p>
     <img src={Routes.static_path(@conn, "/images/doc/converter-aml-to-postgresql.png")} alt="Azimutt converter from AML to PostgreSQL">
+    <p><a href={Routes.website_path(@conn, :doc, ["converters"])}>Learn more</a> about them.</p>
 <% end %>
 
 <%= render "docs/_footer.html", conn: @conn, page: @page, prev: @prev, next: @next %>

browser-extension/package.json → extensions/browser-extension/package.json

@@ -13,7 +13,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/azimuttapp/azimutt.git",
-    "directory": "browser-extension"
+    "directory": "extensions/browser-extension"
   },
   "scripts": {
     "start": "./build.watch.js",

desktop/package.json → extensions/desktop/package.json

@@ -17,7 +17,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/azimuttapp/azimutt.git",
-    "directory": "desktop"
+    "directory": "extensions/desktop"
   },
   "main": ".webpack/main",
   "scripts": {

extensions/vscode-aml/.gitignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+*.vsix

extensions/vscode-aml/.npmrc

@@ -0,0 +1 @@
+enable-pre-post-scripts = true

extensions/vscode-aml/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+	// See http://go.microsoft.com/fwlink/?LinkId=827846
+	// for the documentation about the extensions.json format
+	"recommendations": [
+		"dbaeumer.vscode-eslint",
+		"connor4312.esbuild-problem-matchers",
+		"ms-vscode.extension-test-runner"
+	]
+}

extensions/vscode-aml/.vscode/launch.json

@@ -0,0 +1,38 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Run Web Extension ",
+			"type": "extensionHost",
+			"debugWebWorkerHost": true,
+			"request": "launch",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}",
+				"--extensionDevelopmentKind=web"
+			],
+			"outFiles": [
+				"${workspaceFolder}/dist/web/**/*.js"
+			],
+			"preLaunchTask": "${defaultBuildTask}"
+		},
+		{
+			"name": "Extension Tests",
+			"type": "extensionHost",
+			"debugWebWorkerHost": true,
+			"request": "launch",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}",
+				"--extensionDevelopmentKind=web",
+				"--extensionTestsPath=${workspaceFolder}/dist/web/test/suite/extensionTests"
+			],
+			"outFiles": [
+				"${workspaceFolder}/dist/web/**/*.js"
+			],
+			"preLaunchTask": "${defaultBuildTask}"
+		}
+	]
+}

extensions/vscode-aml/.vscode/settings.json

@@ -0,0 +1,11 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+	"files.exclude": {
+		"dist": false // set this to true to hide the "dist" folder with the compiled JS files
+	},
+	"search.exclude": {
+		"dist": true // set this to false to include "dist" folder in search results
+	},
+	// Turn off tsc task auto detection since we have the necessary tasks as npm scripts
+	"typescript.tsc.autoDetect": "off"
+}

extensions/vscode-aml/.vscode/tasks.json

@@ -0,0 +1,54 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"label": "watch-web",
+			"dependsOn": [
+				"npm: watch-web:tsc",
+				"npm: watch-web:esbuild"
+			],
+			"presentation": {
+				"reveal": "never"
+			},
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			}
+		},
+		{
+			"type": "npm",
+			"script": "watch-web:esbuild",
+			"group": "build",
+			"problemMatcher": "$esbuild-watch",
+			"isBackground": true,
+			"label": "npm: watch-web:esbuild",
+			"presentation": {
+				"group": "watch",
+				"reveal": "never"
+			}
+		},
+		{
+			"type": "npm",
+			"script": "watch-web:tsc",
+			"group": "build",
+			"problemMatcher": "$tsc-watch",
+			"isBackground": true,
+			"label": "npm: watch-web:tsc",
+			"presentation": {
+				"group": "watch",
+				"reveal": "never"
+			}
+		},
+		{
+			"label": "compile",
+			"type": "npm",
+			"script": "compile-web",
+			"problemMatcher": [
+				"$tsc",
+				"$esbuild"
+			]
+		}
+	]
+}

extensions/vscode-aml/.vscodeignore

@@ -0,0 +1,17 @@
+.vscode/**
+.vscode-test-web/**
+resources/**
+src/**
+out/**
+node_modules/**
+dist/test/**
+.gitignore
+vsc-extension-quickstart.md
+webpack.config.js
+esbuild.js
+.yarnrc
+**/tsconfig.json
+**/eslint.config.mjs
+**/*.map
+**/*.ts
+**/.vscode-test.*

extensions/vscode-aml/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Change Log
+
+All notable changes to the "vscode-aml" extension will be documented in this file.
+
+Check [Keep a Changelog](http://keepachangelog.com) for recommendations on how to structure this file.
+
+## [Unreleased]
+
+
+## 0.1.0
+
+### Added
+
+- AML syntax highlighting
+- AML suggestions via snippets
+- AML symbol navigation
+- Create AML file with sample content

extensions/vscode-aml/README.md

@@ -0,0 +1,90 @@
+# AML Support for VS Code
+
+[![VS Code Marketplace](https://img.shields.io/vscode-marketplace/v/azimutt.vscode-aml.svg?label=vscode%20marketplace&style=flat-square&color=007ec6)](https://marketplace.visualstudio.com/items?itemName=azimutt.vscode-aml)
+[![Star Azimutt on GitHub](https://img.shields.io/github/stars/azimuttapp/azimutt)](https://github.com/azimuttapp/azimutt)
+[![Follow @azimuttapp on Twitter](https://img.shields.io/twitter/follow/azimuttapp.svg?style=social)](https://twitter.com/intent/follow?screen_name=azimuttapp)
+
+A VS Code extension to design database schemas with [AML](https://azimutt.app/aml), a simple DSL that speed your design by 2x ✨
+
+![AML in VS Code](https://raw.githubusercontent.com/azimuttapp/azimutt/refs/heads/main/extensions/vscode-aml/assets/screenshot.png)
+
+## Features
+
+- Syntax highlight and suggestions for AML code (`.aml` files)
+- Symbol navigation in AML
+
+
+## Usage
+
+1. Create an empty `.aml` file or use `AML: New database schema (ERD)` command
+2. Write your schema using AML, check [documentation](https://azimutt.app/docs/aml) is needed
+
+Here is how AML looks like:
+
+```aml
+users
+  id uuid pk
+  name varchar index
+  email varchar unique
+  role user_role(admin, guest)=guest
+
+posts | store all posts
+  id uuid pk
+  title varchar
+  content text | allow markdown formatting
+  author uuid -> users(id) # inline relation
+  created_at timestamp=`now()`
+```
+
+## Roadmap
+
+- diagram preview + open in Azimutt
+- convert AML to PostgreSQL, JSON, DOT, Mermaid, Markdown (Command Palette)
+- convert SQL and JSON to AML (Command Palette)
+- Add parsing errors ([createDiagnosticCollection](https://code.visualstudio.com/api/references/vscode-api#languages.createDiagnosticCollection)?)
+- auto-complete (cf [registerCompletionItemProvider](https://microsoft.github.io/monaco-editor/typedoc/functions/languages.registerCompletionItemProvider.html))
+- rename (cf [registerRenameProvider](https://microsoft.github.io/monaco-editor/typedoc/functions/languages.registerRenameProvider.html))
+- hover infos (cf [registerHoverProvider](https://microsoft.github.io/monaco-editor/typedoc/functions/languages.registerHoverProvider.html))
+- go-to-definition (cf [registerDefinitionProvider](https://microsoft.github.io/monaco-editor/typedoc/functions/languages.registerDefinitionProvider.html) and [registerImplementationProvider](https://microsoft.github.io/monaco-editor/typedoc/functions/languages.registerImplementationProvider.html))
+- quick-fixes (cf [registerCodeActionProvider](https://microsoft.github.io/monaco-editor/typedoc/functions/languages.registerCodeActionProvider.html))
+- hints with actions (cf [registerCodeLensProvider](https://microsoft.github.io/monaco-editor/typedoc/functions/languages.registerCodeLensProvider.html))
+- AML support in Markdown
+- Connect to a database
+
+
+## Issues & Contributing
+
+If you have any issue or bug, please [create an issue](https://github.com/azimuttapp/azimutt/issues).
+
+If you want to improve this extension, feel free to reach out or submit a pull request.
+
+
+## Development
+
+VS Code language extensions are made of several and quite independent part.
+For general knowledge, look at the [extension documentation](https://code.visualstudio.com/api) and more specifically the [language extension overview](https://code.visualstudio.com/api/language-extensions/overview).
+
+Here are the different parts of this extension:
+
+- [language-configuration.json](language-configuration.json) for language behavior like brackets, comments and folding (cf [doc](https://code.visualstudio.com/api/language-extensions/language-configuration-guide))
+- [syntaxes/aml.tmLanguage.json](syntaxes/aml.tmLanguage.json) for basic syntax highlighting (cf [doc](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide)) and, later, [Semantic Highlighting](https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide) in [src/web/extension.ts](src/web/extension.ts)
+- [snippets.json](snippets.json) for basic language suggestions (cf [extension doc](https://code.visualstudio.com/api/language-extensions/snippet-guide) and [snippet doc](https://code.visualstudio.com/docs/editor/userdefinedsnippets))
+- [package.json](package.json) and [src/web/extension.ts](src/web/extension.ts) for defining commands and more advanced behaviors
+  - [AmlDocumentSymbolProvider](src/web/extension.ts) for symbol detection
+  - [previewAml](src/web/extension.ts) for AML preview
+
+Tips:
+
+- Debug extension via F5 (Run Web Extension)
+- Relaunch the extension from the debug toolbar after changing code in `src/web/extension.ts`
+- Reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes
+
+## Publication
+
+[Publish your extension](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) on the VS Code extension marketplace.
+
+- Get Personal Access Token from [azimutt](https://dev.azure.com/azimutt)
+- Manage extension from the [marketplace](https://marketplace.visualstudio.com/manage/publishers/azimutt)
+- package the extension: `vsce package`
+- publish the extension: `vsce publish`
+- if needed, install vsce: `npm install -g @vscode/vsce`