@datapos/datapos-development 0.3.331 → 0.3.345

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/README.md CHANGED
@@ -5,231 +5,116 @@
5
5
  [![npm version](https://img.shields.io/npm/v/@datapos/datapos-development.svg)](https://www.npmjs.com/package/@datapos/datapos-development)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
7
7
 
8
- A library of utilities used to manage Data Positioning repositories.
8
+ <!-- SUMMARY_START -->
9
+
10
+ A collection of utilities for managing Data Positioning projects.
11
+
12
+ <!-- SUMMARY_END -->
9
13
 
10
14
  ## Installation
11
15
 
12
- Install as a development (dev) dependency:
16
+ Install as a development dependency:
13
17
 
14
18
  ```bash
15
19
  npm install --save-dev @datapos/datapos-development
16
20
  ```
17
21
 
18
- Ensure your local `.env` file contains the following variables:
19
-
20
- ```bash
21
- GITHUB_DOWNLOAD_LICENSE_API_TOKEN="<GITHUB_API_TOKEN>"
22
- NPM_TOKEN="<NPM_TOKEN>"
23
- OWASP_NVD_API_KEY="<NVD_API_KEY>"
24
- ```
22
+ > See the Data Positioning security documentation for additional initialization requirements.
25
23
 
26
24
  ## Utilities
27
25
 
28
- The `src/index.ts' file exposes the following utilities:
26
+ The library implements the following utilities:
27
+
28
+ | Name | Notes |
29
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
30
+ | auditDependencies | Audit the project's dependencies for known security vulnerabilities. uses the owasp-dependency-check module to perform the checks. Updates the OWASP badge(s) at the top of this page. Also runs the 'npm outdated`command. |
31
+ | buildDirectoryIndex | Build an index for the specified directory path. |
32
+ | buildProject | Builds the package using Vite. Output to '/dist' directory. Wrangler for api. Nuxt for app-nuxt. Builds bundle analysis reports. |
33
+ | checkDependencies | Identifies outdated dependencies using npm `outdated` and `npm-check-updates` with option to automatically install latest versions. |
34
+ | documentDependencies | Identify licenses of the project's production and peer dependencies. Updates the table in the **Dependency Licenses** section of this page and summary files licenses.json and licenseTree.json in th licenses directory of this repository. Also downloads a copy of dependency license to `licenses/downloads'.. |
35
+ | formatCode | Uses `prettier` to enforce formatting style rules. |
36
+ | lintCode | Uses `eslint` to check the code for potential errors and enforces coding style rules. |
37
+ | releaseProject | Bump version, builds config, builds project, synchronise with `GitHub` and publish to `npm` or Cloudflare. |
38
+ | syncProjectWithGitHub | Synchronise the local repository with the main GitHub repository. |
39
+ | testProject | ❌ Not implemented. |
40
+ | updateDataPosDependencies | Install the latest version of the specified Data Positioning dependencies. |
29
41
 
30
- | Name | Notes |
31
- | ------------------------- | ----------------------------------------------------------------- |
32
- | auditDependencies | |
33
- | buildDirectoryIndex | Build an index for a given directory. |
34
- | buildProject | |
35
- | checkDependencies | |
36
- | documentDependencies | |
37
- | formatCode | |
38
- | lintCode | |
39
- | releaseProject | |
40
- | syncProjectWithGitHub | Synchronise the local repository with the main GitHub repository. |
41
- | testProject | |
42
- | updateDataPosDependencies | |
42
+ ### Usage
43
43
 
44
- All of the above utilities are designed to be run from `package.json` scripts and assume that the repository follows the standard Data Positioning directory structure and includes a `config.json` file in the root directory.
44
+ All utilities are designed to be run from `package.json` scripts and assume that the project follows the standard Data Positioning directory structure and that it includes a `config.json` file in the root directory.
45
45
 
46
46
  ```json
47
47
  {
48
48
  ...
49
49
  "scripts": {
50
- ...
51
- "build": "node -e \"import('@datapos/datapos-development').then(m => m.buildProject())\""
52
- ...
50
+ "audit": "node -e \"import('@datapos/datapos-development').then(m => m.auditDependencies())\"",
51
+ "build": "node -e \"import('@datapos/datapos-development').then(m => m.buildProject())\"",
52
+ "check": "node -e \"import('@datapos/datapos-development').then(m => m.checkDependencies())\"",
53
+ "document": "node -e \"import('@datapos/datapos-development').then(m => m.documentDependencies(['MIT']))\"",
54
+ "format": "node -e \"import('@datapos/datapos-development').then(m => m.formatCode())\"",
55
+ "lint": "node -e \"import('@datapos/datapos-development').then(m => m.lintCode())\"",
56
+ "release": "node -e \"import('@datapos/datapos-development').then(m => m.releaseProject())\"",
57
+ "sync": "node -e \"import('@datapos/datapos-development').then(m => m.syncProjectWithGitHub())\"",
58
+ "test": "node -e \"import('@datapos/datapos-development').then(m => m.testProject())\"",
59
+ "update": "node -e \"import('@datapos/datapos-development').then(m => m.updateDataPosDependencies(['development']))\""
53
60
  }
54
61
  ...
55
62
  }
56
63
  ```
57
64
 
58
- ## Reports & Compliance
65
+ ## Bundle Analysis Reports
66
+
67
+ The Bundle Analysis Report provides a detailed breakdown of the bundle’s composition and module sizes, helping identify which modules contribute most to the final build. It is generated automatically on each release using the `npm` package [rollup-plugin-visualizer](https://www.npmjs.com/package/rollup-plugin-visualizer).
68
+
69
+ [View the Bundle Analysis Report](https://data-positioning.github.io/datapos-development/bundle-analysis-reports/rollup-visualiser/index.html) created by the **rollup visualiser** plugin.
59
70
 
60
- ### Dependency Check Report
71
+ [View the Bundle Analysis Report](https://data-positioning.github.io/datapos-development/bundle-analysis-reports/sonda/index.html) created by the **sonda** plugin.
72
+
73
+ ## Dependency Check Report
61
74
 
62
75
  The OWASP Dependency Check Report identifies known vulnerabilities in project dependencies. It is generated automatically on each release using the `npm` package [owasp-dependency-check](https://dependency-check.github.io/DependencyCheck/index.html).
63
76
 
64
77
  [View the OWASP Dependency Check Report](https://data-positioning.github.io/datapos-development/dependency-check-report.html)
65
78
 
66
- ### Dependency Licenses
79
+ ## Dependency Licenses
67
80
 
68
- The following table lists the top-level production and peer dependencies. All of these dependencies—along with their transitive dependencies—have been recursively verified to use one of the following commercially friendly licenses: **Apache-2.0**, **BSD-2-Clause**, **CC0-1.0**, or **MIT**. Developers cloning this repository should independently verify all **development** and **optional** dependencies. This project is used solely to support development activities and is not used in production or distributed in any other form.
81
+ The following table lists the top-level production and peer dependencies. All of these dependencies—along with their transitive dependencies—have been recursively verified to use one of the following commercially friendly licenses: **BSD-2-Clause**, **CC0-1.0**, or **MIT**. Developers cloning this repository should independently verify all **development** and **optional** dependencies. This project supports development activities only. It is not used in production or distributed in any other form.
69
82
 
70
83
  We use the `npm` packages [license-report](https://www.npmjs.com/package/license-report), [license-report-check](https://www.npmjs.com/package/license-report-check), [license-report-recursive](https://www.npmjs.com/package/license-report-recursive) and [license-downloader](https://www.npmjs.com/package/license-downloader) to identify all dependency licenses and include copies of them. We do not use any unlicensed dependencies in either production or development.
71
84
 
72
85
  <!-- DEPENDENCY_LICENSES_START -->
73
- |Name|Type|Installed|Latest|Latest Release|Deps|Document|
74
- |:-|:-|:-:|:-:|:-|-:|:-|
75
- |@datapos/datapos-shared|MIT|0.3.298 ⚠️|0.3.300|this month: 2025-12-10|3|[LICENSE](https://raw.githubusercontent.com/data-positioning/datapos-shared/main/LICENSE)|
76
- |acorn|MIT|8.15.0|8.15.0|6 months ago: 2025-06-09|0|⚠️ No license file|
77
- |acorn-typescript|MIT|1.4.13|1.4.13|23 months ago: 2024-01-03❗|1|[LICENSE](https://raw.githubusercontent.com/TyrealHu/acorn-typescript/master/LICENSE)|
78
- |acorn-walk|MIT|8.3.4|8.3.4|15 months ago: 2024-09-09❗|1|⚠️ No license file|
79
- |dotenv|BSD-2-Clause|17.2.3|17.2.3|2 months ago: 2025-09-29|0|[LICENSE](https://raw.githubusercontent.com/motdotla/dotenv/master/LICENSE)|
80
- |zod|MIT|4.1.13|4.1.13|this month: 2025-12-07|0|[LICENSE](https://raw.githubusercontent.com/colinhacks/zod/main/LICENSE)|
86
+
87
+ | Name | Type | Installed | Latest | Latest Release | Deps | Document |
88
+ | :---------------------- | :----------- | :--------: | :-----: | :-------------------------- | ---: | :---------------------------------------------------------------------------------------- |
89
+ | @datapos/datapos-shared | MIT | 0.3.298 ⚠️ | 0.3.300 | this month: 2025-12-10 | 3 | [LICENSE](https://raw.githubusercontent.com/data-positioning/datapos-shared/main/LICENSE) |
90
+ | acorn | MIT | 8.15.0 | 8.15.0 | 6 months ago: 2025-06-09 | 0 | ⚠️ No license file |
91
+ | acorn-typescript | MIT | 1.4.13 | 1.4.13 | 23 months ago: 2024-01-03❗ | 1 | [LICENSE](https://raw.githubusercontent.com/TyrealHu/acorn-typescript/master/LICENSE) |
92
+ | acorn-walk | MIT | 8.3.4 | 8.3.4 | 15 months ago: 2024-09-09❗ | 1 | ⚠️ No license file |
93
+ | dotenv | BSD-2-Clause | 17.2.3 | 17.2.3 | 2 months ago: 2025-09-29 | 0 | [LICENSE](https://raw.githubusercontent.com/motdotla/dotenv/master/LICENSE) |
94
+ | zod | MIT | 4.1.13 | 4.1.13 | this month: 2025-12-07 | 0 | [LICENSE](https://raw.githubusercontent.com/colinhacks/zod/main/LICENSE) |
81
95
 
82
96
  <!-- DEPENDENCY_LICENSES_END -->
83
97
 
98
+ Insert link to other document for detailed explanation. Only show messages if issues arise.
99
+
84
100
  1. **Installed** column:
85
101
 
86
- A ⚠️ symbol is used to highlight any installed version that does not match the latest available version.
102
+ The ⚠️ symbol indicates that the installed version does not match the latest available version.”.
87
103
 
88
104
  1. **Latest Release** column:
89
105
 
90
- A ⚠️ symbol is used to highlight any dependency that has gone **more than 6 months** without an update but **no more than 12 months**.
106
+ The ⚠️ symbol indicates that the dependency has gone **more than 6 months** without an update but **no more than 12 months**.
91
107
 
92
- A **❗** symbol indicates a dependency that has gone **more than 12 months** without an update.
108
+ The symbol indicates a dependency that has gone **more than 12 months** without an update.
93
109
 
94
110
  If a dependency has no, or only a small number of, transitive dependencies, then it may not require frequent updates. The **Deps** column shows the number of transitive dependencies. Full details for these dependencies can be found in [licenses/licenseTree.json](licenses/licenseTree.json).
95
111
 
96
112
  1. **Document** column:
97
113
 
98
- The message “⚠️ No license file” is used to highlight any dependency that does not include a license file.
99
-
100
- ### Bundle Analysis Report
101
-
102
- The Bundle Analysis Report provides a detailed breakdown of the bundle's composition and module sizes, helping to identify which modules contribute most to the final build. It is generated automatically on each release using the `npm` package [rollup-plugin-visualizer](https://www.npmjs.com/package/rollup-plugin-visualizer).
103
-
104
- [View the Bundle Analysis Report](https://data-positioning.github.io/datapos-development/stats.html)
105
-
106
- ## Repository Management Commands
107
-
108
- Implements the common Data Positioning repository management command detailed in
109
- The table below lists the repository management commands available in this project.
110
- For detailed implementation, see the `scripts` section in the `package.json` file.
111
-
112
- | Name | VS Key Code | Notes |
113
- | ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
114
- | audit | alt+ctrl+shift+a | Audit the project's dependencies for known security vulnerabilities. |
115
- | build | alt+ctrl+shift+b | Build the package using Vite. Output to '/dist' directory. |
116
- | check | alt+ctrl+shift+c | Identify outdated dependencies using npm `outdated` and `npm-check-updates` with option to install latest versions. Also runs `retire` scanner. |
117
- | document | alt+ctrl+shift+d | Identify licenses of the project's production and peer dependencies. See [licenses.json](./licenses.json). |
118
- | format | alt+ctrl+shift+f | Use `prettier` to enforce formatting style rules. |
119
- | lint | alt+ctrl+shift+l | Use `eslint` to check the code for potential errors and enforces coding style rules. |
120
- | release | alt+ctrl+shift+r | Bump version, build library, synchronise with `GitHub` and publish to `npm`. |
121
- | sync:withGitHub | alt+ctrl+shift+s | Synchronise local repository with the main GitHub repository. |
122
- | test | alt+ctrl+shift+t | ❌ Not implemented. |
123
- | update:dataPosDeps | alt+ctrl+shift+u | Install the latest version of all Data Positioning dependencies. |
124
-
125
- ## TODO
126
-
127
- 1. Enhance `uploadDirectoryToR2`to batch upload files so more efficient and performant.
128
- 2. Review if it is better to replace all `execCommand`calls with `spawnCommand` calls?
114
+ The “⚠️ No license file” message indicates a dependency that does not include a license file.
129
115
 
130
116
  ## License
131
117
 
132
- This project is licensed under the MIT License, allowing free use, modification, and distribution.
118
+ This project is licensed under the MIT License, permitting free use, modification, and distribution.
133
119
 
134
120
  [MIT](./LICENSE) © 2026 Data Positioning Pty Ltd
135
-
136
- ## Review License Reporting
137
-
138
- Here’s a step-by-step license compliance checklist for Node.js projects that combines automated tooling like license-report with manual verification. This is designed to make sure your MIT project remains compliant when using third-party dependencies.
139
-
140
- Node.js License Compliance Checklist
141
- Step 1: Generate initial license report
142
-
143
- Run your tool, e.g., license-report:
144
-
145
- npx license-report --json > licenses.json
146
-
147
- Save the output for review.
148
-
149
- This gives a first-pass list of all dependencies and their declared licenses.
150
-
151
- Step 2: Identify potential issues
152
-
153
- For each dependency in the report, check for:
154
-
155
- Flag What it means Action
156
- No license declared No license field in package.json Check for LICENSE file in repo. If none, contact author or replace dependency.
157
- Custom/proprietary license License not recognized Manually review the license text and confirm compatibility.
158
- Copyleft license (GPL, LGPL) May require release of modifications If LGPL, ensure linking rules are followed. GPL may restrict distribution.
159
- License mismatch License field differs from LICENSE file Trust LICENSE file; update your report accordingly.
160
- Step 3: Verify actual license text
161
-
162
- Check the dependency’s repository for a LICENSE file.
163
-
164
- Confirm that the license text matches the package.json declaration.
165
-
166
- For multi-license projects, note which license applies to the code you are using.
167
-
168
- Step 4: Document all licenses
169
-
170
- Create a ThirdPartyLicenses.md or LICENSES/ folder in your project.
171
-
172
- For each dependency, include:
173
-
174
- Dependency name and version
175
-
176
- License type (from LICENSE file)
177
-
178
- URL to repository or package
179
-
180
- Any copyleft obligations (e.g., “LGPL: modifications must remain LGPL”)
181
-
182
- Example (ThirdPartyLicenses.md):
183
-
184
- # Third-Party Dependencies
185
-
186
- ## LibraryA 1.2.3
187
-
188
- - License: Apache-2.0
189
- - Repository: https://github.com/user/libraryA
190
- - License text: LICENSES/LibraryA.txt
191
-
192
- ## LibraryB 4.5.6
193
-
194
- - License: BSD-2-Clause
195
- - Repository: https://github.com/user/libraryB
196
- - License text: LICENSES/LibraryB.txt
197
-
198
- ## LibraryC 0.1.2
199
-
200
- - License: LGPL-3.0-only
201
- - Repository: https://github.com/user/libraryC
202
- - License text: LICENSES/LibraryC.txt
203
- - Note: If you modify this library, modifications must remain LGPL-3.0-only
204
-
205
- Step 5: Include license texts
206
-
207
- Copy the full license text into your project for each dependency.
208
-
209
- Put each in LICENSES/LibraryName.txt or combine into ThirdPartyLicenses.md.
210
-
211
- Make it easily accessible to end users.
212
-
213
- Step 6: Audit before release
214
-
215
- Review all dependencies: no missing licenses.
216
-
217
- Confirm compliance with copyleft licenses.
218
-
219
- Ensure your own MIT license only covers your code.
220
-
221
- Update ThirdPartyLicenses.md whenever dependencies are added/updated.
222
-
223
- Step 7: Automate for future
224
-
225
- Use CI scripts to regenerate license report on npm install or release.
226
-
227
- Fail the build if any dependency has “no license” or an incompatible license.
228
-
229
- Optional tools:
230
-
231
- license-checker (Node.js)
232
-
233
- npm-license-crawler
234
-
235
- fossology (more comprehensive scanning)
@@ -0,0 +1,13 @@
1
+ # Data Positioning default EditorConfig
2
+ root = true
3
+
4
+ [*]
5
+ charset = utf-8
6
+ end_of_line = lf
7
+ indent_style = space
8
+ indent_size = 4
9
+ insert_final_newline = true
10
+ trim_trailing_whitespace = true
11
+
12
+ [*.md]
13
+ trim_trailing_whitespace = false
@@ -1,10 +1,10 @@
1
1
  import { promises as ge } from "node:fs";
2
2
  import { nanoid as Ds } from "nanoid";
3
3
  import Ms from "node:path";
4
- import { promisify as Vs } from "node:util";
5
- import { exec as zs, spawn as js } from "node:child_process";
6
- import { CONNECTOR_SOURCE_OPERATIONS as Fs, CONNECTOR_DESTINATION_OPERATIONS as $s } from "@datapos/datapos-shared";
7
- import { fileURLToPath as Bs, URL as Zs } from "node:url";
4
+ import { fileURLToPath as Vs, URL as zs } from "node:url";
5
+ import { promisify as js } from "node:util";
6
+ import { exec as Fs, spawn as $s } from "node:child_process";
7
+ import { CONNECTOR_SOURCE_OPERATIONS as Bs, CONNECTOR_DESTINATION_OPERATIONS as Zs } from "@datapos/datapos-shared";
8
8
  function k(e, t, i) {
9
9
  function r(d, y) {
10
10
  if (d._zod || Object.defineProperty(d, "_zod", {
@@ -7650,7 +7650,7 @@ function Fh(e) {
7650
7650
  return Rs;
7651
7651
  };
7652
7652
  }
7653
- const $h = Vs(zs);
7653
+ const $h = js(Fs);
7654
7654
  async function Bh(e) {
7655
7655
  let t;
7656
7656
  try {
@@ -7726,7 +7726,7 @@ async function Uh(e) {
7726
7726
  }
7727
7727
  async function Ie(e, t, i = [], r = !1) {
7728
7728
  return re(`${e} - spawn(${t} ${i.join(" ")})`), new Promise((n, u) => {
7729
- js(t, i, { stdio: "inherit" }).on("close", (d) => {
7729
+ $s(t, i, { stdio: "inherit" }).on("close", (d) => {
7730
7730
  d === 0 || r ? n() : u(new Error(`${t} exited with code ${d}`));
7731
7731
  });
7732
7732
  });
@@ -7908,7 +7908,7 @@ async function Ns(e, t, i = "./") {
7908
7908
  function Jh(e) {
7909
7909
  let t = !1, i = !1;
7910
7910
  for (const r of e)
7911
- Fs.includes(r) && (t = !0), $s.includes(r) && (i = !0);
7911
+ Bs.includes(r) && (t = !0), Zs.includes(r) && (i = !0);
7912
7912
  return t && i ? "bidirectional" : t ? "source" : i ? "destination" : "unknown";
7913
7913
  }
7914
7914
  const Yh = {
@@ -7932,7 +7932,7 @@ async function vl() {
7932
7932
  "--nodePackageSkipDevDependencies",
7933
7933
  "--nvdApiKey",
7934
7934
  process.env.OWASP_NVD_API_KEY ?? ""
7935
- ]), await el("2️⃣"), await Ie("3️⃣ Check using 'npm outdated'", "npm", ["audit"]), Fe("Dependencies audited.");
7935
+ ]), await el("2️⃣"), await Ie("3️⃣ Check using 'npm audit'", "npm", ["audit"]), Fe("Dependencies audited.");
7936
7936
  } catch (e) {
7937
7937
  console.error("❌ Error auditing dependencies.", e), process.exit(1);
7938
7938
  }
@@ -7978,7 +7978,7 @@ const Sr = "<!-- DEPENDENCY_LICENSES_START -->", il = "<!-- DEPENDENCY_LICENSES_
7978
7978
  async function gl(e = [], t = !0) {
7979
7979
  try {
7980
7980
  Re("Document Dependencies"), await Li();
7981
- const i = e.flatMap((n) => ["--allowed", `'${n}'`]), r = Bs(new Zs(import.meta.resolve("@datapos/datapos-development/license-report-config")));
7981
+ const i = e.flatMap((n) => ["--allowed", `'${n}'`]), r = Vs(new zs(import.meta.resolve("@datapos/datapos-development/license-report-config")));
7982
7982
  await Te(
7983
7983
  "1️⃣ Generate 'licenses.json' file",
7984
7984
  "license-report",
@@ -8028,7 +8028,7 @@ async function rl(e, t) {
8028
8028
  return S.values();
8029
8029
  })()
8030
8030
  ];
8031
- let o = `|Name|Type|Installed|Latest|Latest Release|Deps|Document|
8031
+ let o = `|Name|Type|Installed|Latest|Latest Released|Deps|Document|
8032
8032
  |:-|:-|:-:|:-:|:-|-:|:-|
8033
8033
  `;
8034
8034
  for (const S of y) {