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..f719bc1000a7 --- /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 new file mode 100644 index 000000000000..4f3c6c7cb984 --- /dev/null +++ b/.vscode/cspell.json @@ -0,0 +1,98 @@ +{ + "version": "0.2", + "language": "en", + "allowCompoundWords": true, + "caseSensitive": false, + "files": [ + "**/*.js", + "**/*.html", + "**/*.css", + "**/*.md" + ], + "ignorePaths": [ + "node_modules/**", + "**/ThirdParty/**", + "**/Build/**", + "Source/**", + "CONTRIBUTORS.md", + "**/LICENSE.md" + ], + "useGitignore": true, + "dictionaries": [ + "typescript", + "node", + "html", + "css", + "packages" + ], + "dictionaryDefinitions": [ + { + "name": "packages", + "path": "./.cspell/cspell-packages.txt", + "addWords": false + } + ], + "words": [ + "3DTILES", + "aabb", + "Amato", + "bathymetric", + "bitangent", + "bitangents", + "bivariate", + "Bourke", + "brdf", + "cartesians", + "cartographics", + "cesiumjs", + "comms", + "cyclomatic", + "czml", + "dequantize", + "dequantized", + "dequantizes", + "dijit", + "DONT", + "ecef", + "EPSG", + "fxaa", + "glsl", + "gltf", + "iframes", + "iife", + "lerp", + "Lilli", + "MAXAR", + "minifiers", + "mipmapped", + "mipmaps", + "msaa", + "noaa", + "Occluder", + "occluders", + "octree", + "octrees", + "OITFS", + "pako", + "phong", + "pjcozzi", + "pnts", + "quantizations", + "reproject", + "tada", + "topo", + "topojson", + "Transitioner", + "tridiagonal", + "tweens", + "uncentered", + "uncompress", + "unminified", + "unproject", + "unregisters", + "unrenderable", + "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 ddce4d5e04f4..b7f4163fe29a 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", diff --git a/Documentation/Contributors/CodingGuide/README.md b/Documentation/Contributors/CodingGuide/README.md index 921781f393c2..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) @@ -117,6 +118,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 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 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 diff --git a/package.json b/package.json index 7be464bf072a..2e12af100580 100644 --- a/package.json +++ b/package.json @@ -139,7 +139,8 @@ "deploy-status": "gulp deployStatus", "deploy-set-version": "gulp deploySetVersion", "prettier": "prettier --write \"**/*\"", - "prettier-check": "prettier --check \"**/*\"" + "prettier-check": "prettier --check \"**/*\"", + "cspell": "npx cspell lint -c .vscode/cspell.json --unique --no-progress" }, "engines": { "node": ">=18.18.0" diff --git a/packages/engine/Source/Core/BoundingSphere.js b/packages/engine/Source/Core/BoundingSphere.js index e43530a8f8a9..4b9986b60416 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 ab6860c00d25..8fd5b033119f 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 1815080ded86..8908ddfa91a8 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 ef15944b1c25..ce3ce373b4b1 100644 --- a/packages/engine/Source/Core/EllipsoidGeodesic.js +++ b/packages/engine/Source/Core/EllipsoidGeodesic.js @@ -421,7 +421,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 ab6896739f8e..7b005fef26b6 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 d7286835e82c..f8549189211d 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 dff801ef29d2..2dce4702e2ff 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.