bimplus-renderer 1.8.38 → 1.8.40-webifc1.0

package/JSDOC_MIGRATION_PLAN.md

@@ -0,0 +1,244 @@
+# JSDoc Migration Plan
+
+## Goal
+
+Replace the `documentation` package with JSDoc tooling while preserving the existing documentation workflows:
+
+- HTML documentation in `./documentation`
+- Markdown API documentation in `./documentation/Bimplus_Renderer_doc.md`
+- Confluence-compatible Markdown in `./documentation/Bimplus_Renderer_doc_confluence.md`
+- The existing `build-doc*` npm script interface
+
+The migration should also remove the vulnerable transitive `vue-template-compiler` dependency.
+
+## Scope
+
+Files expected to change:
+
+- `package.json`
+- `package-lock.json`
+- New root-level `jsdoc.json` configuration
+- Existing `scripts/generate-api-markdown.js` renderer
+- `eslint.config.mjs` for scoped Node.js globals when linting the renderer
+- `README.md`
+- `documentation/Bimplus Renderer basics.md` as the HTML landing-page source
+- `documentation/convert_to_confluence_md.py`
+- Remove obsolete `doc_config.yml`
+- Generated files under `documentation/`
+
+The following should remain functionally unchanged:
+
+- JSDoc comments in `src/*.js`
+- Application source, build, and test configuration
+
+## Porting This Plan to Other Projects
+
+Use this file as a migration template for each repository, not as a blind file-copy checklist. Before implementation, record the current source glob, generated output paths, existing `build-doc*` script names, Markdown heading/anchor conventions, and any downstream Confluence or publishing workflow. Preserve established output names and script interfaces when consumers depend on them; adapt paths and symbol grouping to that repository's JSDoc conventions.
+
+The reference custom renderer in [scripts/generate-api-markdown.js](scripts/generate-api-markdown.js) is the implementation model. Copy it only after checking that the other repository's doclets use compatible `kind`, `memberof`, `scope`, and `longname` values. Add project-specific filters or display rules only when required by its documented public API.
+
+## Implementation Steps
+
+### 1. Replace development dependencies
+
+Remove `documentation` from `devDependencies` and add:
+
+- `jsdoc` for parsing source comments and generating HTML
+- A repository-owned Markdown renderer using JSDoc's structured doclets
+
+Remove any old generator dependencies and install JSDoc:
+
+```powershell
+npm uninstall documentation jsdoc-to-markdown
+npm install --save-dev jsdoc
+```
+
+Do not add a third-party Markdown generator. `scripts/generate-api-markdown.js` renders JSDoc doclets directly and validates symbol anchors.
+
+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.
+
+### 2. Add `jsdoc.json`
+
+Create a root-level JSDoc configuration with these requirements:
+
+- Include JavaScript files under `src/`
+- Recurse through the source directory
+- Parse ES module syntax
+- Write HTML output to `./documentation`
+- Use `documentation/Bimplus Renderer basics.md` as the documentation landing-page content when supported
+- Enable JSDoc's Markdown plugin and recursive source discovery
+
+Proposed configuration:
+
+```json
+{
+  "source": {
+    "include": ["src"],
+    "includePattern": ".*\\.js$",
+    "excludePattern": "(^|[\\\\/])node_modules[\\\\/]"
+  },
+  "opts": {
+    "destination": "./documentation",
+    "recurse": true,
+    "readme": "./documentation/Bimplus Renderer basics.md"
+  },
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": true
+  },
+  "plugins": [
+    "plugins/markdown"
+  ]
+}
+```
+
+`opts.recurse: true` includes deeper source directories than the previous shallow globs. Review the additional doclets and exclude non-public implementation modules as needed. Do not add `plugins/recurse`: it is not shipped by JSDoc 4 and makes the command fail with "Unable to find the plugin". Validate the configuration against the installed JSDoc version.
+
+### 3. Update npm scripts
+
+Replace the current `documentation` commands with JSDoc equivalents while retaining the existing script names:
+
+```json
+{
+  "lint-doc": "jsdoc --configure jsdoc.json --explain",
+  "build-doc": "npm run lint-doc && jsdoc --configure jsdoc.json",
+  "build-docMd": "npm run lint-doc && node scripts/generate-api-markdown.js",
+  "build-docConf": "npm run build-docMd && cd ./documentation && python convert_to_confluence_md.py",
+  "build-docAll": "npm run build-doc && npm run build-docConf"
+}
+```
+
+`scripts/generate-api-markdown.js` replaces `jsdoc2md`; do not add a third-party Markdown renderer. The renderer should:
+
+1. Invoke the installed JSDoc CLI with `process.execPath`, the local `node_modules/jsdoc/jsdoc.js` entrypoint, `--configure jsdoc.json`, and `--explain`. Run with the repository root as `cwd`, capture stdout/stderr, and fail clearly on a non-zero exit or invalid JSON.
+2. Parse the JSON doclets and include documented public classes, modules, namespaces, and supported API doclets only. Exclude undocumented, private, anonymous, and implementation-only symbols. Deduplicate repeated doclets by `longname`; group members by `memberof`; retain documented global functions.
+3. Render the information present on doclets: container parameters, method signatures, descriptions, parameter tables, return values, callbacks/properties, types/defaults, deprecation/since/throws/see tags, and examples where present. Preserve the Markdown/HTML descriptions produced by JSDoc.
+4. Emit both a useful API index and a section for each documented symbol. Escape values placed in code or Markdown tables without altering trusted JSDoc description markup.
+5. Emit explicit `<a id="…" name="…"></a>` targets. Keep each fragment used in a Markdown link identical to an emitted ID. Normalize instance-method `#` separators to the existing `+` anchor form; preserve dots for static members/callbacks. For example, `BimExplorer#getUrl` maps to `BimExplorer+getUrl`, while `BimExplorer.this.onObjectSelected` keeps its dotted name. Handle nested names such as `BimExplorer.BimObjectProperties#load` explicitly.
+6. Before writing the file, fail if a rendered API symbol has no anchor or if any generated `](#target)` link has no matching anchor ID. Create the destination directory if needed and write UTF-8.
+
+The checks in the renderer protect the source Markdown structure. They do not replace rendering the Markdown and testing real click navigation in the target preview/browser.
+
+The `lint-doc` command should be tested with the installed JSDoc CLI. Existing `@private` tags with values warn under JSDoc; do not use `--pedantic` unless those source comments are corrected. `--explain` emits a large doclet JSON report; suppress or capture that output in automated logs if it becomes unwieldy, while preserving the command's exit status.
+
+### 4. Regenerate documentation
+
+Run the formats individually first:
+
+```powershell
+npm run lint-doc
+npm run build-doc
+npm run build-docMd
+npm run build-docConf
+```
+
+Then run the complete workflow:
+
+```powershell
+npm run build-docAll
+```
+
+The Confluence converter should continue reading `Bimplus_Renderer_doc.md` from `documentation/` and writing `Bimplus_Renderer_doc_confluence.md`. It must:
+
+- Read and write UTF-8 explicitly so Unicode output works on Windows.
+- Rewrite links case-insensitively when JSDoc preserves case in fragments.
+- When rewriting a target to `RendererApidescription-{fragment}`, emit a matching `<a id="RendererApidescription-{fragment}" name="RendererApidescription-{fragment}"></a>` alias. Rewriting links without creating matching targets leaves the converted document's links dead.
+- Validate every converted internal Markdown link against an emitted ID before writing the final Confluence file.
+
+Keep the raw Markdown IDs and Confluence aliases separate: the raw file uses the API fragments; only the Confluence variant uses the required `RendererApidescription-` prefix.
+
+### 5. Review generated output
+
+Check the following:
+
+- `documentation/index.html` opens successfully
+- HTML assets load without missing-file errors
+- All documented public classes, modules, namespaces, methods, callbacks, parameters, and return values are represented
+- Every rendered API symbol has a generated Markdown anchor, and internal Markdown links resolve
+- Markdown headings and links are readable
+- Confluence anchors contain the expected `RendererApidescription-` prefix
+- Confluence-prefixed links have matching prefixed target IDs
+- No stale files from the previous generator remain in the generated output
+
+Do not treat matching fragment strings in source files as proof of working links. Render both Markdown files with the parser/preview used by their consumers, inspect the resulting `href` and `id` values, and click representative links: a class/module, an instance method containing `+`, a dotted member, and a nested method. If the consumer is VS Code Markdown Preview, test there; if the Confluence Markdown is pasted into Confluence, verify links in Confluence's preview/page because its anchor generation rules differ from local Markdown renderers.
+
+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.
+
+### 6. Update repository guidance
+
+Update `README.md` to describe:
+
+- `jsdoc.json`
+- `jsdoc` and the repository-owned Markdown renderer
+- The revised npm scripts
+- The new HTML output structure
+- The continued Markdown-to-Confluence conversion
+- The fact that generated output must be regenerated after source JSDoc changes
+- The repository-owned Markdown renderer and its symbol/link validation
+- The distinction between raw Markdown IDs and Confluence-prefixed alias IDs
+
+### 7. Remove obsolete dependency output
+
+After a successful install, verify that the old packages are gone:
+
+```powershell
+npm ls documentation jsdoc-to-markdown vue-template-compiler
+```
+
+The command should report that none of these packages is installed, or that they are not found in the dependency tree. Search scripts, READMEs, and the lockfile for stale `jsdoc2md`/`jsdoc-to-markdown` references; the removal-check command in this plan may name the package intentionally.
+
+Review `package-lock.json` for removal of the obsolete dependency chain. Do not remove unrelated lockfile changes produced by the package manager.
+
+## Verification Checklist
+
+Run the documentation workflow and existing project checks:
+
+```powershell
+npm install
+npm run lint-doc
+npm run build-docAll
+npm run build
+npm test
+npm audit
+```
+
+Also lint the renderer directly if the repository ESLint script does not include it:
+
+```powershell
+npx eslint scripts/generate-api-markdown.js
+```
+
+Expected results:
+
+- Documentation commands complete successfully
+- Generated HTML, Markdown, and Confluence files exist
+- The application build remains successful
+- Existing tests remain successful
+- The `vue-template-compiler` audit finding is no longer introduced by this documentation toolchain
+- `jsdoc-to-markdown` is absent from the manifest, lockfile dependency tree, and generation scripts
+- Rendered raw Markdown and Confluence Markdown links navigate to their intended targets in their actual consumers
+
+`npm audit` may still report unrelated vulnerabilities. Record those separately instead of applying a forced dependency downgrade.
+
+## Rollback
+
+If the generated output loses API content or the Confluence conversion cannot be adapted safely:
+
+1. Restore the previous `package.json` and `package-lock.json` documentation dependencies.
+2. Remove `jsdoc.json` and restore `scripts/generate-api-markdown.js` to its pre-migration contents if rollback is required.
+3. Restore the previous generated `documentation/` output.
+4. Reassess the JSDoc configuration and renderer before retrying.
+
+Do not modify application source code as part of rollback.
+
+## Acceptance Criteria
+
+The migration is complete when:
+
+- `documentation` is no longer a development dependency
+- JSDoc generates readable HTML from the reviewed JavaScript files under `src/`
+- The repository-owned renderer generates the API Markdown file
+- The existing Confluence conversion succeeds
+- `build-doc`, `build-docMd`, `build-docConf`, and `build-docAll` all work
+- Generated documentation is reviewed and committed
+- Application build and tests remain unaffected

package/README.md

@@ -79,7 +79,7 @@ goto your application folder which uses the renderer
   npm install
 
 ### Unit testing
-Run tests from the renderer root. Vitest is the only installed test runner; the
+Run tests from the renderer root. Vitest runs the unit and geometry DDT suites; the
 test files import Vitest APIs directly. Browser globals, fixtures, and
 test-only dependencies are initialized in `test/setup/vitestBrowser.setup.js`.
 
@@ -144,6 +144,75 @@ npm run test-vitest-modelviewer-chrome
 npm run test-vitest-modelviewer-chrome-long
 ```
 
+### Modelviewer image comparison (Playwright Test)
+
+The standalone Playwright suite loads each IFC into the real renderer, checks
+viewport diagnostics, fits a fixed perspective view without camera animation,
+and compares the 1000 x 700 viewport against a PNG baseline. It uses the same
+Vite shader/asset configuration and viewer helpers as the geometry DDT, without
+reading or changing `Results.db` or requiring the DDT server.
+
+```sh
+npx playwright install firefox chromium
+npm run test-modelviewer-ddt-visual
+npm run test-modelviewer-ddt-visual-long
+npx playwright test --project=chromium
+npx playwright test --project=chromium-long
+```
+
+The IFC datasets must be present locally (use `sync-modelviewer-ddt` or
+`sync-modelviewer-ddt-long` if needed). Only the selected dataset is required.
+To run only one model, use Playwright's title filter:
+
+```sh
+npm run test-modelviewer-ddt-visual -- --grep "BasicProject.ifc"
+```
+
+Missing baselines fail normal runs. To create only missing baselines without
+replacing existing images:
+
+```sh
+npm run test-modelviewer-ddt-visual-init
+npm run test-modelviewer-ddt-visual-long-init
+```
+
+To explicitly replace baselines after reviewing an intentional rendering change:
+
+```sh
+npm run test-modelviewer-ddt-visual -- --update-snapshots
+npm run test-modelviewer-ddt-visual-long -- --update-snapshots
+```
+
+Review the images before committing them under
+`modelviewer-data-driven-tests/playwright/snapshots/`. Baselines are separated
+by browser, dataset, and OS; generate and compare using the same OS and GPU
+environment. The included Windows Firefox baselines cover both datasets;
+other browser/OS combinations need their own initial baseline generation.
+The per-test timeout is 100 minutes and includes IFC loading; the separate
+15-second screenshot timeout starts only after loading and camera setup finish.
+An `A snapshot doesn't exist` error means a baseline is missing, not that
+loading timed out. Use the initialization command above in that case.
+Comparisons allow a per-pixel color
+threshold of 0.2 but no differing pixels above that threshold. Playwright waits for consecutive stable
+screenshots rather than using a fixed sleep. Failures produce expected, actual,
+and diff images under `test-results/modelviewer-visual/`; the HTML report is
+in `playwright-report/`, with JUnit output in
+`test-results/playwright-modelviewer-visual.xml`.
+
+The HTML reporter uses hashed filenames internally. Actual comparison images
+from failed comparisons are also copied directly to
+`playwright-report/data/named/`, using the baseline filename without the
+`-actual` suffix, for example `BasicProject-ifc.png`.
+The filename comes from the matching baseline, preserving the full name even
+when Playwright shortens the failure artifact's filename with a hash.
+There are no subfolders, expected images, diff images, or full-page failure
+screenshots in this folder.
+If multiple browsers, repeats, or retries produce the same filename, the last
+result in report order replaces the earlier copy; run one browser at a time
+to keep its images separate. The internal hashed files are retained so the
+HTML report's image viewer continues to work, including expected and diff
+images. Both sets of report images are regenerated on each run.
+
 Vitest writes JUnit output under `test-results/`. Firefox Istanbul coverage is
 written under `coverage/`, including `coverage/lcov.info` for CI artifact
 collection. Coverage instruments renderer source under `src/`, excluding
@@ -154,10 +223,9 @@ update reference data automatically. See
 [the migration plan](KARMA_TO_VITEST_MIGRATION_PLAN.md) for remaining gates.
 
 ### Documentation
-Bimplus WebSDK uses npm documentation plugin for easy documentation generation.
-To generate a documentation please install documentation plugin via npm :
+Bimplus Renderer documentation is generated with the local JSDoc dependency and the repository-owned API Markdown renderer. Install the project dependencies with `npm install` before running the documentation scripts.
 
-npm install -g documentation
+JSDoc source discovery and HTML output are configured in `jsdoc.json`; `scripts/generate-api-markdown.js` renders the API doclets and checks Markdown anchors. Regenerate the documentation after changing source JSDoc comments. Raw Markdown uses API anchors, while the Confluence output adds matching `RendererApidescription-` aliases.
 
 To create documentation in html format go to your renderer folder and run :