bimplus-webclient 0.1.68 → 0.1.69
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/JSDOC_MIGRATION_PLAN.md +200 -0
- package/README.md +4 -6
- package/eslint.config.mjs +6 -1
- package/package.json +8 -18
- package/vitest.config.mjs +16 -0
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# JSDoc Migration Plan
|
|
2
|
+
|
|
3
|
+
## Goal
|
|
4
|
+
|
|
5
|
+
Replace the `documentation` package with JSDoc tooling while preserving the existing documentation workflows:
|
|
6
|
+
|
|
7
|
+
- HTML documentation in `./documentation`
|
|
8
|
+
- Markdown API documentation in `./documentation/Bimplus_WebClient_doc.md`
|
|
9
|
+
- Confluence-compatible Markdown in `./documentation/Bimplus_WebClient_doc_confluence.md`
|
|
10
|
+
- The existing `build-doc*` npm script interface
|
|
11
|
+
|
|
12
|
+
The migration should also remove the vulnerable transitive `vue-template-compiler` dependency.
|
|
13
|
+
|
|
14
|
+
## Scope
|
|
15
|
+
|
|
16
|
+
Files expected to change:
|
|
17
|
+
|
|
18
|
+
- `package.json`
|
|
19
|
+
- `package-lock.json`
|
|
20
|
+
- New root-level `jsdoc.json` configuration
|
|
21
|
+
- `.github/documentation.instructions.md`
|
|
22
|
+
- Generated files under `documentation/`
|
|
23
|
+
|
|
24
|
+
The following should remain functionally unchanged:
|
|
25
|
+
|
|
26
|
+
- JSDoc comments in `src/*.js`
|
|
27
|
+
- `documentation/convert_to_confluence_md.py`
|
|
28
|
+
- Application source, build, and test configuration
|
|
29
|
+
|
|
30
|
+
## Implementation Steps
|
|
31
|
+
|
|
32
|
+
### 1. Replace development dependencies
|
|
33
|
+
|
|
34
|
+
Remove `documentation` from `devDependencies` and add:
|
|
35
|
+
|
|
36
|
+
- `jsdoc` for parsing source comments and generating HTML
|
|
37
|
+
- `jsdoc-to-markdown` for Markdown API output
|
|
38
|
+
|
|
39
|
+
Install the dependencies with:
|
|
40
|
+
|
|
41
|
+
```powershell
|
|
42
|
+
npm install --save-dev jsdoc jsdoc-to-markdown
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Do not run `npm audit fix --force`; it may apply a breaking downgrade and does not provide a patched version of the vulnerable Vue 2 package.
|
|
46
|
+
|
|
47
|
+
### 2. Add `jsdoc.json`
|
|
48
|
+
|
|
49
|
+
Create a root-level JSDoc configuration with these requirements:
|
|
50
|
+
|
|
51
|
+
- Include JavaScript files under `src/`
|
|
52
|
+
- Recurse through the source directory
|
|
53
|
+
- Parse ES module syntax
|
|
54
|
+
- Write HTML output to `./documentation`
|
|
55
|
+
- Use `README.md` as the documentation landing-page content when supported
|
|
56
|
+
- Enable Markdown processing and recursive source discovery
|
|
57
|
+
|
|
58
|
+
Proposed configuration:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"source": {
|
|
63
|
+
"include": ["src"],
|
|
64
|
+
"includePattern": ".*\\.js$",
|
|
65
|
+
"excludePattern": "(^|[\\\\/])node_modules[\\\\/]"
|
|
66
|
+
},
|
|
67
|
+
"opts": {
|
|
68
|
+
"destination": "./documentation",
|
|
69
|
+
"recurse": true,
|
|
70
|
+
"readme": "./README.md"
|
|
71
|
+
},
|
|
72
|
+
"templates": {
|
|
73
|
+
"cleverLinks": false,
|
|
74
|
+
"monospaceLinks": true
|
|
75
|
+
},
|
|
76
|
+
"plugins": [
|
|
77
|
+
"plugins/markdown",
|
|
78
|
+
"plugins/recurse"
|
|
79
|
+
]
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Validate the exact configuration against the installed JSDoc version before committing it.
|
|
84
|
+
|
|
85
|
+
### 3. Update npm scripts
|
|
86
|
+
|
|
87
|
+
Replace the current `documentation` commands with JSDoc equivalents while retaining the existing script names:
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"lint-doc": "jsdoc --pedantic --configure jsdoc.json --explain",
|
|
92
|
+
"build-doc": "npm run lint-doc && jsdoc --configure jsdoc.json",
|
|
93
|
+
"build-docMd": "npm run lint-doc && jsdoc2md --files \"src/*.js\" > documentation/Bimplus_WebClient_doc.md",
|
|
94
|
+
"build-docConf": "npm run build-docMd && cd ./documentation && python convert_to_confluence_md.py",
|
|
95
|
+
"build-docAll": "npm run build-doc && npm run build-docMd && npm run build-docConf"
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The `lint-doc` command should be tested with the installed JSDoc CLI. If JSDoc does not support the selected validation flags, replace it with the supported parse-only validation command while keeping the script name.
|
|
100
|
+
|
|
101
|
+
### 4. Regenerate documentation
|
|
102
|
+
|
|
103
|
+
Run the formats individually first:
|
|
104
|
+
|
|
105
|
+
```powershell
|
|
106
|
+
npm run lint-doc
|
|
107
|
+
npm run build-doc
|
|
108
|
+
npm run build-docMd
|
|
109
|
+
npm run build-docConf
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Then run the complete workflow:
|
|
113
|
+
|
|
114
|
+
```powershell
|
|
115
|
+
npm run build-docAll
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The Confluence converter should continue reading the generated Markdown from its current location. No Python changes are expected unless the new Markdown headings or anchors expose a compatibility issue.
|
|
119
|
+
|
|
120
|
+
### 5. Review generated output
|
|
121
|
+
|
|
122
|
+
Check the following:
|
|
123
|
+
|
|
124
|
+
- `documentation/index.html` opens successfully
|
|
125
|
+
- HTML assets load without missing-file errors
|
|
126
|
+
- All public classes, methods, namespaces, callbacks, parameters, and return values are represented
|
|
127
|
+
- Markdown headings and links are readable
|
|
128
|
+
- Confluence anchors contain the expected `WebClientApidescription-` prefix
|
|
129
|
+
- No stale files from the previous generator remain in the generated output
|
|
130
|
+
|
|
131
|
+
JSDoc will produce a different HTML structure and may use different anchor names than documentation.js. This is expected, but no public API should disappear.
|
|
132
|
+
|
|
133
|
+
### 6. Update repository guidance
|
|
134
|
+
|
|
135
|
+
Update `.github/documentation.instructions.md` to describe:
|
|
136
|
+
|
|
137
|
+
- `jsdoc.json`
|
|
138
|
+
- `jsdoc` and `jsdoc-to-markdown`
|
|
139
|
+
- The revised npm scripts
|
|
140
|
+
- The new HTML output structure
|
|
141
|
+
- The continued Markdown-to-Confluence conversion
|
|
142
|
+
- The fact that generated output must be regenerated after source JSDoc changes
|
|
143
|
+
|
|
144
|
+
### 7. Remove obsolete dependency output
|
|
145
|
+
|
|
146
|
+
After a successful install, verify that the old packages are gone:
|
|
147
|
+
|
|
148
|
+
```powershell
|
|
149
|
+
npm ls documentation vue-template-compiler
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The command should report that neither package is installed, or that they are not found in the dependency tree.
|
|
153
|
+
|
|
154
|
+
Review `package-lock.json` for removal of the obsolete dependency chain. Do not remove unrelated lockfile changes produced by the package manager.
|
|
155
|
+
|
|
156
|
+
## Verification Checklist
|
|
157
|
+
|
|
158
|
+
Run the documentation workflow and existing project checks:
|
|
159
|
+
|
|
160
|
+
```powershell
|
|
161
|
+
npm install
|
|
162
|
+
npm run lint-doc
|
|
163
|
+
npm run build-docAll
|
|
164
|
+
npm run build
|
|
165
|
+
npm test
|
|
166
|
+
npm audit
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Expected results:
|
|
170
|
+
|
|
171
|
+
- Documentation commands complete successfully
|
|
172
|
+
- Generated HTML, Markdown, and Confluence files exist
|
|
173
|
+
- The application build remains successful
|
|
174
|
+
- Existing tests remain successful
|
|
175
|
+
- The `vue-template-compiler` audit finding is no longer introduced by this documentation toolchain
|
|
176
|
+
|
|
177
|
+
`npm audit` may still report unrelated vulnerabilities. Record those separately instead of applying a forced dependency downgrade.
|
|
178
|
+
|
|
179
|
+
## Rollback
|
|
180
|
+
|
|
181
|
+
If the generated output loses API content or the Confluence conversion cannot be adapted safely:
|
|
182
|
+
|
|
183
|
+
1. Restore the previous `package.json` and `package-lock.json` documentation dependencies.
|
|
184
|
+
2. Remove `jsdoc.json`.
|
|
185
|
+
3. Restore the previous generated `documentation/` output.
|
|
186
|
+
4. Reassess the JSDoc configuration and Markdown template before retrying.
|
|
187
|
+
|
|
188
|
+
Do not modify application source code as part of rollback.
|
|
189
|
+
|
|
190
|
+
## Acceptance Criteria
|
|
191
|
+
|
|
192
|
+
The migration is complete when:
|
|
193
|
+
|
|
194
|
+
- `documentation` is no longer a development dependency
|
|
195
|
+
- JSDoc generates readable HTML from `src/*.js`
|
|
196
|
+
- `jsdoc-to-markdown` generates the API Markdown file
|
|
197
|
+
- The existing Confluence conversion succeeds
|
|
198
|
+
- `build-doc`, `build-docMd`, `build-docConf`, and `build-docAll` all work
|
|
199
|
+
- Generated documentation is reviewed and committed
|
|
200
|
+
- Application build and tests remain unaffected
|
package/README.md
CHANGED
|
@@ -74,15 +74,13 @@ goto your application folder which uses the webclient
|
|
|
74
74
|
npm install
|
|
75
75
|
|
|
76
76
|
### Unit testing
|
|
77
|
-
|
|
77
|
+
The unit tests run with Vitest and jsdom. Run them with coverage using:
|
|
78
78
|
|
|
79
|
-
npm
|
|
80
|
-
|
|
81
|
-
Run test in headleass mode
|
|
79
|
+
npm test
|
|
82
80
|
|
|
83
|
-
|
|
81
|
+
Run Vitest in watch mode during development with:
|
|
84
82
|
|
|
85
|
-
|
|
83
|
+
npm run test-watch
|
|
86
84
|
|
|
87
85
|
### Documentation
|
|
88
86
|
Bimplus webclient uses npm documentation plugin for easy documentation generation.
|
package/eslint.config.mjs
CHANGED
|
@@ -16,7 +16,6 @@ export default [
|
|
|
16
16
|
sourceType: "module",
|
|
17
17
|
globals: {
|
|
18
18
|
...globals.browser,
|
|
19
|
-
QUnit: true,
|
|
20
19
|
// needed for webpack files
|
|
21
20
|
define: true,
|
|
22
21
|
require: true,
|
|
@@ -27,4 +26,10 @@ export default [
|
|
|
27
26
|
plugins: {},
|
|
28
27
|
rules: {},
|
|
29
28
|
},
|
|
29
|
+
{
|
|
30
|
+
files: ["test/**/*"],
|
|
31
|
+
languageOptions: {
|
|
32
|
+
globals: globals.vitest,
|
|
33
|
+
},
|
|
34
|
+
},
|
|
30
35
|
];
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "bimplus-webclient",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.69",
|
|
4
4
|
"description": "bim+ web client",
|
|
5
5
|
"types": "types/bimplus-webclient.d.ts",
|
|
6
6
|
"keywords": [
|
|
@@ -29,31 +29,21 @@
|
|
|
29
29
|
"build-docMd": "npm run lint-doc && documentation build ./src/*.js -f md -o ./documentation/Bimplus_WebClient_doc.md",
|
|
30
30
|
"build-docConf": "npm run build-docMd && cd ./documentation && python convert_to_confluence_md.py",
|
|
31
31
|
"build-docAll": "npm run build-doc && npm run build-docConf && npm run build-docMd && npm run build-doc",
|
|
32
|
-
"test": "
|
|
33
|
-
"test-
|
|
34
|
-
"test-chrome-headless": "npm run test -- --single-run=true --browsers ChromeHeadless karma.conf.js",
|
|
35
|
-
"test-firefox": "npm run test -- --single-run=true --browsers Firefox karma.conf.js",
|
|
36
|
-
"test-firefox-headless": "npm run test -- --single-run=true --browsers FirefoxHeadless karma.conf.js",
|
|
37
|
-
"test-watch": "npm run test -- --browsers=ChromeExt --single-run=false --auto-watch"
|
|
32
|
+
"test": "vitest run --coverage",
|
|
33
|
+
"test-watch": "vitest"
|
|
38
34
|
},
|
|
39
35
|
"devDependencies": {
|
|
40
36
|
"@babel/core": "^8.0.6",
|
|
41
37
|
"@babel/preset-env": "^8.0.6",
|
|
42
38
|
"@eslint/js": "^10.0.1",
|
|
39
|
+
"@vitest/coverage-v8": "^5.0.3",
|
|
43
40
|
"babel-loader": "^10.1.1",
|
|
44
|
-
"clean-webpack-plugin": "^4.0.0",
|
|
45
|
-
"coverage-istanbul-loader": "^3.0.5",
|
|
46
41
|
"documentation": "^14.0.3",
|
|
47
|
-
"eslint": "^10.
|
|
48
|
-
"globals": "17.
|
|
49
|
-
"
|
|
50
|
-
"karma-chrome-launcher": "^3.2.0",
|
|
51
|
-
"karma-coverage-istanbul-reporter": "^3.0.2",
|
|
52
|
-
"karma-firefox-launcher": "^2.1.3",
|
|
53
|
-
"karma-qunit": "^4.2.1",
|
|
54
|
-
"karma-webpack": "5.0.1",
|
|
55
|
-
"qunit": "^2.26.0",
|
|
42
|
+
"eslint": "^10.12.0",
|
|
43
|
+
"globals": "17.13.0",
|
|
44
|
+
"jsdom": "^30.1.2",
|
|
56
45
|
"terser-webpack-plugin": "^5.6.1",
|
|
46
|
+
"vitest": "^5.0.3",
|
|
57
47
|
"webpack": "^5.111.1",
|
|
58
48
|
"webpack-cli": "^7.2.3",
|
|
59
49
|
"webpack-merge": "^6.0.1"
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { defineConfig } from 'vitest/config';
|
|
2
|
+
|
|
3
|
+
export default defineConfig({
|
|
4
|
+
test: {
|
|
5
|
+
include: ['test/**/*Tests.js'],
|
|
6
|
+
environment: 'jsdom',
|
|
7
|
+
globals: true,
|
|
8
|
+
silent: 'passed-only',
|
|
9
|
+
restoreMocks: true,
|
|
10
|
+
setupFiles: ['./test/vitest.setup.js'],
|
|
11
|
+
coverage: {
|
|
12
|
+
reporter: ['html', 'lcovonly', 'text-summary'],
|
|
13
|
+
reportsDirectory: 'coverage',
|
|
14
|
+
},
|
|
15
|
+
},
|
|
16
|
+
});
|