From 9c3acf5fa7695a9e8bb33dcc07333c902aa37b4b Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Tue, 23 Apr 2024 11:55:27 -0400 Subject: [PATCH 1/5] add cspell dictionary, ts-expect-error in sandcastle --- .vscode/cspell.json | 72 +++++++++++++++++++++++++++++ .vscode/extensions.json | 3 +- Apps/Sandcastle/CesiumSandcastle.js | 1 + 3 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 .vscode/cspell.json diff --git a/.vscode/cspell.json b/.vscode/cspell.json new file mode 100644 index 000000000000..3cc66c0bddfd --- /dev/null +++ b/.vscode/cspell.json @@ -0,0 +1,72 @@ +// cSpell Settings +{ + "version": "0.2", + "language": "en", + "allowCompoundWords": true, + "caseSensitive": false, + "ignorePaths": [ + "node_modules/**" + ], + "useGitignore": true, + "dictionaries": [ + "typescript", + "node", + "html", + "css" + ], + "words": [ + "3DTILES", + "aabb", + "Amato", + "bathymetric", + "bitangent", + "bitangents", + "bivariate", + "Bourke", + "brdf", + "cartesians", + "cartographics", + "cesiumjs", + "comms", + "cyclomatic", + "czml", + "DONT", + "ecef", + "EPSG", + "fxaa", + "glsl", + "gltf", + "iframes", + "iife", + "lerp", + "MAXAR", + "minifiers", + "mipmapped", + "mipmaps", + "msaa", + "noaa", + "Occluder", + "occluders", + "octree", + "octrees", + "OITFS", + "pako", + "phong", + "pjcozzi", + "pnts", + "quantizations", + "reproject", + "tada", + "topo", + "topojson", + "Transitioner", + "tridiagonal", + "tweens", + "uncentered", + "unminified", + "unproject", + "voxel", + "WEBG", + "xdescribe" + ] +} diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 4fb4e7d6b1ff..dc51bec039d8 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -5,6 +5,7 @@ "slevesque.shader", "cesium.gltf-vscode", "bierner.github-markdown-preview", - "DavidAnson.vscode-markdownlint" + "DavidAnson.vscode-markdownlint", + "streetsidesoftware.code-spell-checker" ] } diff --git a/Apps/Sandcastle/CesiumSandcastle.js b/Apps/Sandcastle/CesiumSandcastle.js index 9f8d87e99120..0b4c051a996a 100644 --- a/Apps/Sandcastle/CesiumSandcastle.js +++ b/Apps/Sandcastle/CesiumSandcastle.js @@ -26,6 +26,7 @@ require({ location: "../Apps/Sandcastle/ThirdParty", }, ], + // @ts-expect-error }, [ "CodeMirror/lib/codemirror", "dijit/Dialog", From dd4020288da23b7cde77ce02029941cf853efc0f Mon Sep 17 00:00:00 2001 From: jjspace <8007967+jjspace@users.noreply.github.com> Date: Fri, 20 Sep 2024 14:28:52 -0400 Subject: [PATCH 2/5] add more configuration --- .vscode/.cspell/cspell-packages.txt | 90 ++++++++++++++++++++++++++ .vscode/.cspell/gen-cspell-packages.js | 33 ++++++++++ .vscode/cspell.json | 24 ++++++- package.json | 3 +- 4 files changed, 146 insertions(+), 4 deletions(-) create mode 100644 .vscode/.cspell/cspell-packages.txt create mode 100644 .vscode/.cspell/gen-cspell-packages.js diff --git a/.vscode/.cspell/cspell-packages.txt b/.vscode/.cspell/cspell-packages.txt new file mode 100644 index 000000000000..b0689cd396c0 --- /dev/null +++ b/.vscode/.cspell/cspell-packages.txt @@ -0,0 +1,90 @@ +cesium +engine +widgets +playwright +test +chokidar +cloc +compression +esbuild +eslint +config +plugin +html +express +globals +globby +glsl +strip +comments +gulp +clean +css +insert +rename +replace +tap +zip +husky +istanbul +lib +instrument +jasmine +core +jsdoc +karma +chrome +launcher +coverage +detect +browsers +edge +firefox +ie +longest +reporter +safari +sourcemap +loader +spec +markdownlint +cli +merge +stream +mkdirp +node +fetch +open +prettier +prismjs +request +rimraf +sinon +tsd +typescript +yargs +tweenjs +tween +autolinker +bitmap +sdf +dompurify +draco3d +earcut +grapheme +splitter +jsep +kdbush +ktx +parse +lerc +mersenne +twister +meshoptimizer +pako +protobufjs +rbush +topojson +client +urijs +nosleep \ No newline at end of file diff --git a/.vscode/.cspell/gen-cspell-packages.js b/.vscode/.cspell/gen-cspell-packages.js new file mode 100644 index 000000000000..7e14d51a8159 --- /dev/null +++ b/.vscode/.cspell/gen-cspell-packages.js @@ -0,0 +1,33 @@ +import { readFileSync, writeFileSync } from "fs"; +import path from "path"; +import { fileURLToPath } from "url"; + +// inspired by code in https://github.com/streetsidesoftware/cspell/issues/3215 +// this file just generates the word list file in this directory that contains +// all our dependecy package names + +const __filename = fileURLToPath(import.meta.url); // get the resolved path to the file +const __dirname = path.dirname(__filename); // get the name of the directory + +const packageJsons = [ + path.join(__dirname, "../package.json"), + path.join(__dirname, "../packages/engine/package.json"), + path.join(__dirname, "../packages/widgets/package.json"), +]; +const words = packageJsons.reduce((acc, packageJsonPath) => { + const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")); + const packageNames = Object.keys(packageJson.dependencies ?? {}).concat( + Object.keys(packageJson.devDependencies ?? {}) + ); + // remove the @ org symbol and dashes to get just words in package names + const setOfWords = packageNames + .flatMap((name) => name.replace(/[@]/g, "").split(/\/|\-/)) + .map((word) => word.replace(".js", "")); + setOfWords.forEach((word) => acc.add(word)); + return acc; +}, new Set()); + +// if https://github.com/streetsidesoftware/vscode-spell-checker/issues/3002 +// ever gets addressed this can be used to auto-generate the list of package names +// to pass to cspell directly. Right now it works in the CLI but not in the extension +writeFileSync("./cspell-packages.txt", Array.from(words).join("\n")); diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 3cc66c0bddfd..254ecfca67a5 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -1,18 +1,36 @@ -// cSpell Settings { "version": "0.2", "language": "en", "allowCompoundWords": true, "caseSensitive": false, + "files": [ + "**/*.js", + "**/*.html", + "**/*.css", + "**/*.md" + ], "ignorePaths": [ - "node_modules/**" + "node_modules/**", + "**/ThirdParty/**", + "**/Build/**", + "Source/**", + "CONTRIBUTORS.md", + "**/LICENSE.md" ], "useGitignore": true, "dictionaries": [ "typescript", "node", "html", - "css" + "css", + "packages" + ], + "dictionaryDefinitions": [ + { + "name": "packages", + "path": "./.cspell/cspell-packages.txt", + "addWords": false + } ], "words": [ "3DTILES", diff --git a/package.json b/package.json index 476a98470f69..16f0cf6f855e 100644 --- a/package.json +++ b/package.json @@ -140,7 +140,8 @@ "deploy-status": "gulp deployStatus", "deploy-set-version": "gulp deploySetVersion", "prettier": "prettier --write --no-config \"**/*\"", - "prettier-check": "prettier --check --no-config \"**/*\"" + "prettier-check": "prettier --check --no-config \"**/*\"", + "cspell": "npx cspell lint -c .vscode/cspell.json --unique --no-progress" }, "engines": { "node": ">=18.18.0" From 03654f486287f7f374fe2bb9ca62772b2315cf0d Mon Sep 17 00:00:00 2001 From: jjspace <8007967+jjspace@users.noreply.github.com> Date: Fri, 20 Sep 2024 14:29:10 -0400 Subject: [PATCH 3/5] some small spelling corrections --- .vscode/cspell.json | 8 ++++++++ packages/engine/Source/Core/BoundingSphere.js | 2 +- packages/engine/Source/Core/Color.js | 2 +- packages/engine/Source/Core/EllipseGeometry.js | 2 +- packages/engine/Source/Core/EllipsoidGeodesic.js | 2 +- packages/engine/Source/Core/FrustumGeometry.js | 2 +- .../engine/Source/Core/decodeGoogleEarthEnterpriseData.js | 2 +- .../Source/Workers/decodeGoogleEarthEnterprisePacket.js | 2 +- 8 files changed, 15 insertions(+), 7 deletions(-) diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 254ecfca67a5..4f3c6c7cb984 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -48,6 +48,10 @@ "comms", "cyclomatic", "czml", + "dequantize", + "dequantized", + "dequantizes", + "dijit", "DONT", "ecef", "EPSG", @@ -57,6 +61,7 @@ "iframes", "iife", "lerp", + "Lilli", "MAXAR", "minifiers", "mipmapped", @@ -81,8 +86,11 @@ "tridiagonal", "tweens", "uncentered", + "uncompress", "unminified", "unproject", + "unregisters", + "unrenderable", "voxel", "WEBG", "xdescribe" diff --git a/packages/engine/Source/Core/BoundingSphere.js b/packages/engine/Source/Core/BoundingSphere.js index 9ee58a40d09d..17e1a87ad472 100644 --- a/packages/engine/Source/Core/BoundingSphere.js +++ b/packages/engine/Source/Core/BoundingSphere.js @@ -1381,7 +1381,7 @@ BoundingSphere.projectTo2D = function (sphere, projection, result) { /** * Determines whether or not a sphere is hidden from view by the occluder. * - * @param {BoundingSphere} sphere The bounding sphere surrounding the occludee object. + * @param {BoundingSphere} sphere The bounding sphere surrounding the occluded object. * @param {Occluder} occluder The occluder. * @returns {boolean} true if the sphere is not visible; otherwise false. */ diff --git a/packages/engine/Source/Core/Color.js b/packages/engine/Source/Core/Color.js index 23683732133b..d3d13edde274 100644 --- a/packages/engine/Source/Core/Color.js +++ b/packages/engine/Source/Core/Color.js @@ -325,7 +325,7 @@ Color.fromRandom = function (options, result) { //>>includeStart('debug', pragmas.debug); Check.typeOf.number.lessThanOrEquals( - "minumumAlpha", + "minimumAlpha", minimumAlpha, maximumAlpha ); diff --git a/packages/engine/Source/Core/EllipseGeometry.js b/packages/engine/Source/Core/EllipseGeometry.js index 0a225fdca1fc..28c927fd0875 100644 --- a/packages/engine/Source/Core/EllipseGeometry.js +++ b/packages/engine/Source/Core/EllipseGeometry.js @@ -314,7 +314,7 @@ function computeTopBottomAttributes(positions, options, extrude) { function topIndices(numPts) { // numTriangles in half = 3 + 8 + 12 + ... = -1 + 4 + (4 + 4) + (4 + 4 + 4) + ... = -1 + 4 * (1 + 2 + 3 + ...) // = -1 + 4 * ((n * ( n + 1)) / 2) - // total triangles = 2 * numTrangles in half + // total triangles = 2 * numTriangles in half // indices = total triangles * 3; // Substitute numPts for n above diff --git a/packages/engine/Source/Core/EllipsoidGeodesic.js b/packages/engine/Source/Core/EllipsoidGeodesic.js index b15475b93bce..1cf1ac529f84 100644 --- a/packages/engine/Source/Core/EllipsoidGeodesic.js +++ b/packages/engine/Source/Core/EllipsoidGeodesic.js @@ -420,7 +420,7 @@ EllipsoidGeodesic.prototype.interpolateUsingFraction = function ( /** * Provides the location of a point at the indicated distance along the geodesic. * - * @param {number} distance The distance from the inital point to the point of interest along the geodesic + * @param {number} distance The distance from the initial point to the point of interest along the geodesic * @param {Cartographic} [result] The object in which to store the result. * @returns {Cartographic} The location of the point along the geodesic. * diff --git a/packages/engine/Source/Core/FrustumGeometry.js b/packages/engine/Source/Core/FrustumGeometry.js index 46fcb8cfb785..faa53ef8d8a1 100644 --- a/packages/engine/Source/Core/FrustumGeometry.js +++ b/packages/engine/Source/Core/FrustumGeometry.js @@ -45,7 +45,7 @@ function FrustumGeometry(options) { const vertexFormat = defaultValue(options.vertexFormat, VertexFormat.DEFAULT); // This is private because it is used by DebugCameraPrimitive to draw a multi-frustum by - // creating multiple FrustumGeometrys. This way the near plane of one frustum doesn't overlap + // creating multiple FrustumGeometry objects. This way the near plane of one frustum doesn't overlap // the far plane of another. const drawNearPlane = defaultValue(options._drawNearPlane, true); diff --git a/packages/engine/Source/Core/decodeGoogleEarthEnterpriseData.js b/packages/engine/Source/Core/decodeGoogleEarthEnterpriseData.js index 46d76894f5b9..fc52e91d6346 100644 --- a/packages/engine/Source/Core/decodeGoogleEarthEnterpriseData.js +++ b/packages/engine/Source/Core/decodeGoogleEarthEnterpriseData.js @@ -51,7 +51,7 @@ function decodeGoogleEarthEnterpriseData(key, data) { // while we have a full uint64 (8 bytes) left to do // assumes buffer is 64bit aligned (or processor doesn't care) while (dp < dpend64) { - // rotate the key each time through by using the offets 16,0,8,16,0,8,... + // rotate the key each time through by using the offsets 16,0,8,16,0,8,... off = (off + 8) % 24; kp = off; diff --git a/packages/engine/Source/Workers/decodeGoogleEarthEnterprisePacket.js b/packages/engine/Source/Workers/decodeGoogleEarthEnterprisePacket.js index 59ad933dbc6e..6471e4fafa8d 100644 --- a/packages/engine/Source/Workers/decodeGoogleEarthEnterprisePacket.js +++ b/packages/engine/Source/Workers/decodeGoogleEarthEnterprisePacket.js @@ -201,7 +201,7 @@ function processMetadata(buffer, totalSize, quadKey) { const numMeshesPerPacket = 5; const numSubMeshesPerMesh = 4; -// Each terrain packet will have 5 meshes - each containg 4 sub-meshes: +// Each terrain packet will have 5 meshes - each contain 4 sub-meshes: // 1 even level mesh and its 4 odd level children. // Any remaining bytes after the 20 sub-meshes contains water surface meshes, // which are ignored. From f803125277a31c382b169f3800b3b87115d99351 Mon Sep 17 00:00:00 2001 From: jjspace <8007967+jjspace@users.noreply.github.com> Date: Tue, 24 Sep 2024 16:55:01 -0400 Subject: [PATCH 4/5] add some documentation --- .../Contributors/CodingGuide/README.md | 8 ++++++++ .../Contributors/VSCodeGuide/README.md | 19 ++++++------------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/Documentation/Contributors/CodingGuide/README.md b/Documentation/Contributors/CodingGuide/README.md index 99ade2899769..e992ddb3d831 100644 --- a/Documentation/Contributors/CodingGuide/README.md +++ b/Documentation/Contributors/CodingGuide/README.md @@ -117,6 +117,14 @@ A few more naming conventions are introduced below along with their design patte - For HTML code, keep the existing style. Use double quotes. - Text files, end with a newline to minimize the noise in diffs. +## Spelling + +- We have a basic setup for `cspell` to spellcheck our files. This is currently not enforced but recommended to use and check while programming. This is especially true for JSDoc comments that well end up in our documentation or Readme files + - Run `npm run cspell` to check all files + - Run `npx cspell -c .vscode/cspell.json [file path]` to check a specific file +- If you are using VSCode you can use the [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) extension to highlight misspelled words and add them to our wordlist if they are valid. +- Using cspell optional while we build up the wordlist but may eventually be required as part of our git hooks and CI. See [this issue](https://github.com/CesiumGS/cesium/issues/11954) for an active status on that. + ## Linting For syntax and style guidelines, we use the ESLint recommended settings (the list of rules can be found [here](http://eslint.org/docs/rules/)) as a base and extend it with additional rules via a shared config Node module, [eslint-config-cesium](https://www.npmjs.com/package/eslint-config-cesium). This package is maintained as a part of the Cesium repository and is also used throughout the Cesium ecosystem. For an up to date list of which rules are enabled, look in [index.js](https://github.com/CesiumGS/eslint-config-cesium/blob/main/index.js), [browser.js](https://github.com/CesiumGS/eslint-config-cesium/blob/main/browser.js), and [node.js](https://github.com/CesiumGS/eslint-config-cesium/blob/main/node.js). Below are listed some specific rules to keep in mind diff --git a/Documentation/Contributors/VSCodeGuide/README.md b/Documentation/Contributors/VSCodeGuide/README.md index c15d66c4c355..c759beb8da91 100644 --- a/Documentation/Contributors/VSCodeGuide/README.md +++ b/Documentation/Contributors/VSCodeGuide/README.md @@ -36,22 +36,15 @@ higher installed, to get the correct integrated shell behavior. Click on the extensions icon, or press CTRL-SHIFT-X to see the list of installed VSCode extensions. While we don't officially endorse any particular 3rd-party -extension, there are some that appear to be quite useful to CesiumJS. Just enter +extension, there are some that we have found to be quite useful to CesiumJS. Just enter the desired extension name in the search box and click install. You will need to restart VSCode after you are done installing extensions. -- **[eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)** - by Dirk Baeumer -- This extension picks up on CesiumJS's own eslint settings, - and will warn of any violations. The CesiumJS main repository should pass eslint - using the CesiumJS eslint settings with no warnings and no errors. Proposed - contributions to CesiumJS that introduce eslint warnings will need to be corrected - before they are accepted. - -- **[Shader languages support for VS Code](https://marketplace.visualstudio.com/items?itemName=slevesque.shader)** - by slevesque -- This extension provides syntax highlighting for CesiumJS's shader code. - -- **[glTF Extension for VS Code](https://marketplace.visualstudio.com/items?itemName=cesium.gltf-vscode)** - by CesiumJS.org -- This extension adds features for previewing and editing 3D models in glTF files. +- Search for `@recommended` in the extensions panel to see a full list of "workspace recommendations" of extensions we suggest, the "other recommendations" is generated by VSCode and adding them is at your discression. +- **[eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)** by Dirk Baeumer - This extension picks up on CesiumJS's own eslint settings, and will warn of any violations. The CesiumJS main repository should pass eslint using the CesiumJS eslint settings with no warnings and no errors. Proposed contributions to CesiumJS that introduce eslint warnings will need to be corrected before they are accepted. +- **[prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)** - This will allow you to format your code automatically according to prettier which we enforce for consistency +- **[Shader languages support for VS Code](https://marketplace.visualstudio.com/items?itemName=slevesque.shader)** by slevesque - This extension provides syntax highlighting for CesiumJS's shader code. +- **[glTF Extension for VS Code](https://marketplace.visualstudio.com/items?itemName=cesium.gltf-vscode)** by CesiumJS.org - This extension adds features for previewing and editing 3D models in glTF files. ## VSCode Tasks and Files From 13e99017953c43723fc89705357555ed5c305e78 Mon Sep 17 00:00:00 2001 From: jjspace <8007967+jjspace@users.noreply.github.com> Date: Fri, 4 Oct 2024 16:20:02 -0400 Subject: [PATCH 5/5] adjust docs --- Documentation/Contributors/CodingGuide/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/Contributors/CodingGuide/README.md b/Documentation/Contributors/CodingGuide/README.md index e992ddb3d831..8d85f03bcfcd 100644 --- a/Documentation/Contributors/CodingGuide/README.md +++ b/Documentation/Contributors/CodingGuide/README.md @@ -17,6 +17,7 @@ To some extent, this guide can be summarized as _make new code similar to existi - [Coding Guide](#coding-guide) - [Naming](#naming) - [Formatting](#formatting) + - [Spelling](#spelling) - [Linting](#linting) - [Units](#units) - [Basic Code Construction](#basic-code-construction) @@ -123,7 +124,7 @@ A few more naming conventions are introduced below along with their design patte - Run `npm run cspell` to check all files - Run `npx cspell -c .vscode/cspell.json [file path]` to check a specific file - If you are using VSCode you can use the [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) extension to highlight misspelled words and add them to our wordlist if they are valid. -- Using cspell optional while we build up the wordlist but may eventually be required as part of our git hooks and CI. See [this issue](https://github.com/CesiumGS/cesium/issues/11954) for an active status on that. +- Using cspell is optional while we build up the wordlist but may eventually be required as part of our git hooks and CI. See [this issue](https://github.com/CesiumGS/cesium/issues/11954) for an active status on that. ## Linting @@ -189,7 +190,6 @@ Cartesian3.fromDegrees(); // Not Cartesin3.fromAngle() ```javascript "use strict"; - ``` - :speedboat: To avoid type coercion (implicit type conversion), test for equality with `===` and `!==`, e.g., @@ -377,7 +377,7 @@ function getTransform(node) { return Matrix4.fromTranslationQuaternionRotationScale( node.translation, node.rotation, - node.scale + node.scale, ); } } @@ -394,7 +394,7 @@ function getTransform(node) { return Matrix4.fromTranslationQuaternionRotationScale( node.translation, node.rotation, - node.scale + node.scale, ); } ``` @@ -452,7 +452,7 @@ Cartesian3.fromRadians = function (longitude, latitude, height) { ```javascript this._mapProjection = defaultValue( options.mapProjection, - new GeographicProjection() + new GeographicProjection(), ); ``` @@ -828,7 +828,7 @@ When the overhead of getter/setter functions is prohibitive or reference-type se ```javascript function Model(options) { this.modelMatrix = Matrix4.clone( - defaultValue(options.modelMatrix, Matrix4.IDENTITY) + defaultValue(options.modelMatrix, Matrix4.IDENTITY), ); this._modelMatrix = Matrix4.clone(this.modelMatrix); } @@ -930,7 +930,7 @@ A public identifier (class, function, property) should be deprecated before bein function Foo() { deprecationWarning( "Foo", - "Foo was deprecated in CesiumJS 1.01. It will be removed in 1.03. Use newFoo instead." + "Foo was deprecated in CesiumJS 1.01. It will be removed in 1.03. Use newFoo instead.", ); // ... }