Merge pull request #273 from marklogic/develop

Finish up 3.9.0

Author: BillFarber

.eslintrc.json

@@ -118,6 +118,8 @@
                 ]
             }
         ],
-        "eqeqeq": "error"
+        "eqeqeq": "error",
+        "@typescript-eslint/no-explicit-any": "warn",
+        "@typescript-eslint/no-unused-vars": "warn"
     }
 }

.gitignore

@@ -10,7 +10,9 @@ dist
 .gradle
 gradle-local.properties
 results/
+coverage/
 test-app/.gradle
 test-app/build
+test-app/docker
 
 test-app/src/main/ml-modules/root/MarkLogic

CHANGELOG.md

@@ -1,40 +1,53 @@
+## [3.9.0](https://github.com/marklogic/mlxprs/releases/tag/v3.9.0)
+
+- New MarkLogic icon in the Activity Bar that can be used to open an explorer view with high-level information about the currently connected MarkLogic server.
+- Can use new configuration options to connect to MarkLogic behind a proxy server or in MarkLogic Cloud.
+  * -restBasePath
+  * -manageBasePath
+  * -testBasePath
+  * -adminBasePath
+  * -apiKey
+  * -authType (now accepts "CLOUD")
+- [Improved user guide.](https://marklogic.github.io/mlxprs/)
+
+
 ## [3.8.0](https://github.com/marklogic/mlxprs/releases/tag/v3.8.0)
 
-- Run marklogic-unit-test modules in a MarkLogic server
-- Validate TDE Templates
-- Extract Nodes from data documents using a TDE Template
-- Submit a GraphQL Query to /v1/rows/graphql
-- Various updates to the README
+- Run marklogic-unit-test modules in a MarkLogic server.
+- Validate TDE Templates.
+- Extract Nodes from data documents using a TDE Template.
+- Submit a GraphQL Query to /v1/rows/graphql.
+- Various updates to the README.
 
 
 ## [3.7.0](https://github.com/marklogic/mlxprs/releases/tag/v3.7.0)
 
-- Submit an Optic DSL Query to /v1/rows and get back JSON
-- Submit Optic Query and get back XML or CSV
-- View "Connected" status information in bottom status line
-- Made the UX for attaching to a JS server match attaching to an XQY server, and sorted based on server name
-- Run Highlighted Code in editor windows (rather than the entire window)
-- Display "eval" results in a new tab in the bottom panel (use a setting to revert back to an editor tab)
-- Permit attaching to a remote request even if the current editor tab is not source code
+- Submit an Optic DSL Query to /v1/rows and get back JSON.
+- Submit Optic Query and get back XML or CSV.
+- View "Connected" status information in bottom status line.
+- Made the UX for attaching to a JS server match attaching to an XQY server, and sorted based on server name.
+- Run Highlighted Code in editor windows (rather than the entire window).
+- Display "eval" results in a new tab in the bottom panel (use a setting to revert back to an editor tab).
+- Permit attaching to a remote request even if the current editor tab is not source code.
 
 
 ## [3.6.2](https://github.com/marklogic/mlxprs/releases/tag/v3.6.2)
 
-- Fixed the icon used in the Visual Studio Marketplace 
+- Fixed the icon used in the Visual Studio Marketplace .
 
 ## [3.6.0](https://github.com/marklogic/mlxprs/releases/tag/v3.6.0)
 
-- [#116](https://github.com/marklogic/mlxprs/issues/116) Updated dependencies and fixed all known security vulnerabilities
-- [#119](https://github.com/marklogic/mlxprs/issues/119) Added SJS binding to JavaScript language
-- [#97](https://github.com/marklogic/mlxprs/issues/97) Added a configuration option for the MarkLogic Manage app server port (used for the SJS debug server port)
-- [#117](https://github.com/marklogic/mlxprs/issues/117) Fixed a bug with the first attempt to eval a JavaScript tab
-- [#109](https://github.com/marklogic/mlxprs/issues/109) Prevent the database param from being used in REST calls when the database setting is empty
+- [#116](https://github.com/marklogic/mlxprs/issues/116) Updated dependencies and fixed all known security vulnerabilities.
+- [#119](https://github.com/marklogic/mlxprs/issues/119) Added SJS binding to JavaScript language.
+- [#97](https://github.com/marklogic/mlxprs/issues/97) Added a configuration option for the MarkLogic Manage app server port (used for the SJS debug server port).
+- [#117](https://github.com/marklogic/mlxprs/issues/117) Fixed a bug with the first attempt to eval a JavaScript tab.
+- [#109](https://github.com/marklogic/mlxprs/issues/109) Prevent the database param from being used in REST calls when the database setting is empty.
 
 
 ## [3.5.1](https://github.com/mikrovvelle/mlxprs/tree/v3.5.1)
 
-- Fix [#92](https://github.com/mikrovvelle/mlxprs/issues/92), better error handling with XQuery debug launch failures
-- Added VS Code badges to Readme
+- Fix [#92](https://github.com/mikrovvelle/mlxprs/issues/92), better error handling with XQuery debug launch failures.
+- Added VS Code badges to Readme.
 
 ## [3.5.0](https://github.com/mikrovvelle/mlxprs/tree/v3.5.0)
 
@@ -56,116 +69,116 @@ Addressed off-by-one error in changelog.
 
 ## [3.1.0](https://github.com/mikrovvelle/mlxprs/tree/v3.1.0)
 
-- fixes: #70. SJS debugging now streams modules if they're not available locally
-- other SJS debugging improvements
+- fixes: #70. SJS debugging now streams modules if they're not available locally.
+- other SJS debugging improvements.
 
 ## [3.0.4](https://github.com/mikrovvelle/mlxprs/tree/v3.0.4)
 
-- bugfix: #69
+- bugfix: #69.
 
 ## [3.0.3](https://github.com/mikrovvelle/mlxprs/tree/v3.0.3)
 
-- add "MarkLogic: Show module" command
-- fixes: #68. XQuery debugging now streams modules if they're not available locally
+- add "MarkLogic: Show module" command.
+- fixes: #68. XQuery debugging now streams modules if they're not available locally.
 
 ## [3.0.2](https://github.com/mikrovvelle/mlxprs/tree/v3.0.2)
 
-- bugfix: #67
+- bugfix: #67.
 
 ## [3.0.1](https://github.com/mikrovvelle/mlxprs/tree/v3.0.1)
 
-- fix: #10 - make best effort to format XML and JSON query results
+- fix: #10 - make best effort to format XML and JSON query results.
 
 ## [3.0.0](https://github.com/mikrovvelle/mlxprs/tree/v3.0.0)
 
-- add XQuery debugging
+- add XQuery debugging.
 
 ## [2.0.0](https://github.com/mikrovvelle/mlxprs/tree/v2.0.0)
 
-- add JavaScript debugging
+- add JavaScript debugging.
 
 ## [1.2.2](https://github.com/mikrovvelle/mlxprs/tree/v1.2.2)
 
-- dependency upgrades under the hood
+- dependency upgrades under the hood.
 
 ## [1.2.1](https://github.com/mikrovvelle/mlxprs/tree/v1.2.1)
 
 - fix: #17
-- bugfix: empty results aren't 'pending'
+- bugfix: empty results aren't 'pending'.
 
 ## [1.2.0](https://github.com/mikrovvelle/mlxprs/tree/v1.2.0)
 
-- Added per-query client parameter override capability to XQuery (see README)
+- Added per-query client parameter override capability to XQuery (see README).
 
 ## [1.1.1](https://github.com/mikrovvelle/mlxprs/tree/v1.1.1)
 
-- Security fixes for npm dependencies
+- Security fixes for npm dependencies.
 
 ## [1.1.0](https://github.com/mikrovvelle/mlxprs/tree/v1.1.0)
 
-- Added per-query client parameter override capability SJS (see README)
+- Added per-query client parameter override capability SJS (see README).
 
 ## [1.0.0](https://github.com/mikrovvelle/mlxprs/tree/v1.0.0)
 
-- Working release
+- Working release.
 
 ## [0.7.7](https://github.com/mikrovvelle/mlxprs/tree/v0.7.5)
 
-- Security fixes for npm dependencies
+- Security fixes for npm dependencies.
 
 ## [0.7.5](https://github.com/mikrovvelle/mlxprs/tree/v0.7.5)
 
-- Cosmetic: branding in preparation for 1.0 release
+- Cosmetic: branding in preparation for 1.0 release.
 
 ## [0.7.2](https://github.com/mikrovvelle/mlxprs/tree/v0.7.2)
 
-- Security: update `js-yaml` dependency to fix vulnerability
+- Security: update `js-yaml` dependency to fix vulnerability.
 
 ## [0.7.1](https://github.com/mikrovvelle/mlxprs/tree/v0.7.1)
 
 - Bugfix: Javascript language mode wasn't activating the extension.
 
 ## [0.7.0](https://github.com/mikrovvelle/mlxprs/tree/v0.7.0)
 
-- Added SJS autocompletion based on MarkLogic SJS API
+- Added SJS autocompletion based on MarkLogic SJS API.
 
 ## [0.6.2](https://github.com/mikrovvelle/mlxprs/tree/v0.6.2)
 
-- Successfully built with webpack
+- Successfully built with webpack.
 
 ## 0.6.0 to 0.6.1 (broken)
 
-- Built with webpack
+- Built with webpack.
 
 ## [0.5.0](https://github.com/mikrovvelle/mlxprs/tree/0.5.0)
 
-- Added SSL capabilities to MarkLogic client: `ssl` and `pathToCa` settings
-- Exposed `authType` to marklogic settings (can pretty much leave set to DIGEST)
+- Added SSL capabilities to MarkLogic client: `ssl` and `pathToCa` settings.
+- Exposed `authType` to marklogic settings (can pretty much leave set to DIGEST).
 
 ## [0.4.0](https://github.com/mikrovvelle/mlxprs/tree/0.4.0)
 
-- Added code completion for MarkLogic XQuery API functions
+- Added code completion for MarkLogic XQuery API functions.
 
 ## [0.3.3](https://github.com/mikrovvelle/mlxprs/tree/0.3.3)
 
-- Bugfix: properly handle and display text responses to MarkLogic queries
+- Bugfix: properly handle and display text responses to MarkLogic queries.
 
 ## [0.3.2](https://github.com/mikrovvelle/mlxprs/tree/0.3.2)
 
-- License and copyright
+- License and copyright.
 
 ## [0.3.1](https://github.com/mikrovvelle/mlxprs/tree/0.3.1)
 
-- Handle and display text responses to MarkLogic queries
+- Handle and display text responses to MarkLogic queries.
 
 ## [0.3.0](https://github.com/mikrovvelle/mlxprs/tree/0.3.0)
 
-- Show error details as query results
+- Show error details as query results.
 
 ## [0.2.0](https://github.com/mikrovvelle/mlxprs/tree/0.2.0)
 
-- Give user feedback when empty results are returned from a query
+- Give user feedback when empty results are returned from a query.
 
 ## [0.1.0](https://github.com/mikrovvelle/mlxprs/tree/0.1.0)
 
-- Added XML formatting
+- Added XML formatting.

CONTRIBUTING.md

@@ -52,11 +52,17 @@ cd server
 npm install
 cd ..
 ```
+
 A shorthand script that does all of that for you is
 ```
 npm run installAll
 ```
 
+If you want to ensure a clean build, this command clears all transitory files
+```
+npm run cleanAll
+```
+
 ## Using the Extension from the Project (except the debugger)
 It is recommended to use VSCode as the editor for this package, as it can self-load a debug instance.
 
@@ -119,12 +125,40 @@ The project contains three test applications.
 
 ### Integration Testing Setup
 
-JavaScript debugger integration testing requires a running MarkLogic server where you have full admin rights. Ideally, you should use a dedicated MarkLogic instance for this purpose. The tests assume the existence of a "mlxprs-test" application server running on port 8055 using the "mlxprs-test-content" and "mlxprs-test-modules" databases. Those values are set in test-app/gradle.properties and the admin password should be set in test-app/gradle-local.properties. Then you can use the following commands to build and configure the databases and application servers.
+JavaScript debugger integration testing requires a running MarkLogic server where you have full admin rights. Ideally, you should use a dedicated MarkLogic instance for this purpose. The tests assume the existence of a "mlxprs-test" application server running on port 8055 using the "mlxprs-test-content" and "mlxprs-test-modules" databases. Those values are set in test-app/gradle.properties. Assuming you want the test application deployed locally, then in that gradle.properties file, ensure the "Local config" properties are uncommented and that the "Cloud config" properties are commented out.
+```
+# Local config
+mlRestAuthentication=basic
+mlHost=localhost
+mlUsername=admin
+mlPassword=changeme-in-gradle-local.properties
+```
+Additionally, the admin password should be set in test-app/gradle-local.properties. Then you can use the following commands to build and configure the databases and application servers.
 ```
 cd test-app
 ./gradlew mlDeploy
 ```
 
+Note that in order to facilitate testing the application with a proxy, the app-servers associated with the
+test-app are set to use basic authentication. That includes a version of the Manage app-server on port 8059.
+
+Once the app is deployed, ensure the workspace VSCode settings in test-app/.vscode/settings.json are set to
+use the non-proxy settings as below, and not the reverse-proxy or cloud settings.
+```
+    // Use these for non-proxy testing
+    "marklogic.host": "localhost",
+    "marklogic.ssl": false,
+    "marklogic.authType": "BASIC",
+    "marklogic.port": 8055,
+    "marklogic.restBasePath": "",
+    "marklogic.managePort": 8059,
+    "marklogic.manageBasePath": "",
+    "marklogic.testPort": 8054,
+    "marklogic.testBasePath": "",
+    "marklogic.adminPort": 8001,
+    "marklogic.adminBasePath": "",
+```
+
 ### Manual Integration Testing
 * Use the "Launch Extension (debug)" launch configuration in the "RUN AND DEBUG" window to open a new VS Code session.
 * Once the new window is open, use "File -> Open Folder ..." menu to open the "test-app" folder as a separate project.
@@ -166,18 +200,55 @@ Note that the order of priority for setting the property values in the test code
 
 
 ### Testing from the command line
-Run these two npm scripts from the command line in the root directory of the project to execute the tests. Note that VSCode must not be running while you run the tests.
+Run these three npm scripts from the command line in the root directory of the project to execute the tests. Note that VSCode must not be running while you run the tests.
+
 ```
-npm run installAll
 npm run test
 npm run testServer
-code --extensionDevelopmentPath=<mlxprs-project-dir>/client --extensionTestsPath=<mlxprs-project-dir>/dist/test/integration/index
+npm run testIntegration
 ```
-<mark>The final test (the integration tests), should not be run while VSCode is open.</mark>
 
-To ensure a clean build, you may also run this npm script before running the `installAll` script.
+Alternatively all tests may be run via the single command:
 ```
-npm run cleanAll
+npm run testAll
+```
+
+Additionally, test coverage reports may be generated with this command:
+```
+npm run coverageAll
+```
+
+### Proxy testing
+
+For testing the extension with a proxy server, it is recommended that you use the reverse
+proxy server included in the Java Client project for proxy testing. To start that server,
+simply run the following command in the root directory of the Java Client project. That
+command will start the reverse proxy server in blocking mode listening on port 8020. It
+will then forward requests to port 8020 based on the custom mappings.
+
+```
+./gradlew runBlockingReverseProxyServer
+```
+
+Node Client Test-App Reverse Proxy Mappings
+```
+"/mlxprs/manage" => port 8059
+"/mlxprs/rest"   => port 8055
+"/mlxprs/test"   => port 8054
+```
+
+Once the reverse proxy server is running, change the MLXPRS settings for your workspace
+to the following (in .vscode/settings.json):
+```
+    "marklogic.authType": "BASIC",
+    "marklogic.port": 8020,
+    "marklogic.restBasePath": "/mlxprs/rest",
+    "marklogic.managePort": 8020,
+    "marklogic.manageBasePath": "/mlxprs/manage",
+    "marklogic.adminPort": 8001,
+    "marklogic.adminBasePath": "",
+    "marklogic.testPort": 8020,
+    "marklogic.testBasePath": "/mlxprs/test",
 ```
 
 ## Building the artifact
@@ -227,4 +298,11 @@ Please try to develop, build, and test with the most recent stable releases of t
 - MarkLogic 9, 10, or 11
 
 ## Publishing the artifact
-See [Publishing Extensions](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) for more information
+See [Publishing Extensions](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) for more information
+
+## Documentation
+User documents designed to be published with GitHub Pages and are maintained in the /docs directory of the
+project. You must have Ruby installed. Additionally, there seems to be a bug with runing jekyll with Ruby 3.3.
+I have found that I need to run `chruby ruby-3.2.3` before I start the jekyll server. To start the jekyll
+server, cd into the /docs directory and run the command `bundle exec jekyll server`. This will start the
+server and the user documents will be available at http://127.0.0.1:4000/.

README.md

@@ -16,6 +16,7 @@ _Develop, run, and debug code for MarkLogic in the popular VS Code IDE_
 * View modules (read-only) in the editor
 * Run [marklogic-unit-test module](https://github.com/marklogic-community/marklogic-unit-test)
 * Validate TDE templates and test the templates with node extraction
+* View high-level information about the currently connected MarkLogic server
 
 _JavaScript debugging requires version 2.0.0+ of the MarkLogic extension and [MarkLogic 10.0-4+](https://developer.marklogic.com/products/marklogic-server/10.0)._