Skip to content

Commit 23e258e

Browse files
relu91relu91
authored
Merge branch 'master' into issue-1430-typescript-eslint-no-require-imports
2 parents 77f0c4b + 702793a commit 23e258e

89 files changed

Lines changed: 7923 additions & 2346 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/copilot-instructions.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
## **AI Agent Instructions for eclipse-thingweb/node-wot**
2+
3+
### **Repository Context**
4+
5+
- **Project**: Eclipse Thingweb Node-WoT
6+
- **Language**: TypeScript, JavaScript
7+
- **Purpose**: A fast and extensible framework to connect any device with your browser and backend applications
8+
- **Standards**: W3C Web of Things (WoT) specifications
9+
10+
---
11+
12+
## **WHEN PROVIDING CODE**
13+
14+
### **Pre-Development Requirements**
15+
16+
1. **Read the CONTRIBUTING.md file** at https://github.com/eclipse-thingweb/node-wot/blob/master/CONTRIBUTING.md
17+
2. **Understand the W3C WoT standards** at https://www.w3.org/TR/2023/REC-wot-thing-description11-20231205/
18+
3. **Verify Eclipse Foundation compliance**:
19+
- Contributor must have an Eclipse Foundation account with GitHub ID linked
20+
- Contributor must have signed the Eclipse Contributor Agreement (ECA)
21+
22+
### **Code Quality Standards**
23+
24+
1. **Linting & Formatting**:
25+
26+
- Run `npm run lint` before committing
27+
- Run `npm run format` to automatically fix style issues
28+
- Ensure no ESLint warnings or errors remain
29+
- Follow the strict boolean expressions rule (use `==` or `!=` for null/undefined checks, not `if (var)`)
30+
31+
2. **Scope & Minimal Diffs**:
32+
33+
- Keep changes limited to the specific feature/fix scope
34+
- Do not modify unrelated parts of files
35+
- Strive for the minimum git diff (fewest lines changed)
36+
- Avoid unnecessary refactoring outside the scope of work
37+
38+
3. **Testing**:
39+
40+
- Run the full test suite before committing: `npm run test` or equivalent
41+
- Ensure all tests pass
42+
- Add tests for new features or fixes
43+
44+
4. **Special Attention for Core Changes**:
45+
46+
- If modifying `packages/core`, understand that this impacts ALL other packages
47+
- Check if changes contradict the W3C WoT Scripting API specification: https://w3c.github.io/wot-scripting-api/
48+
- Verify all dependent packages are updated accordingly
49+
- Validate compatibility with existing protocol bindings
50+
51+
5. **Bypassing the Problem**:
52+
53+
- If you do not find a solution to the problem, do not bypass it by typecasting, ignoring the tests etc.
54+
55+
6. **Commit Requirements**:
56+
57+
- **All commits MUST be signed** using the contributor's Eclipse Foundation account email
58+
- Configure git: `git config user.email "<eclipse-account-email>"`
59+
- Commit with `-s` flag: `git commit -s -m "<message>"`
60+
- Follow Conventional Changelog format:
61+
62+
```
63+
<type>(<scope>): <subject>
64+
65+
<body>
66+
67+
<footer>
68+
```
69+
70+
- **Allowed types**: `feat`, `fix`, `refactor`, `perf`, `style`, `test`, `chore`, `docs`
71+
- **Subject**: imperative mood, present tense, lowercase, no period
72+
- **Example**: `feat(binding-coap): add support for observe option`
73+
74+
### **Pull Request Requirements**
75+
76+
1. **PR Body MUST include**:
77+
78+
- **Explanation of AI assistance used**: Describe how AI tools assisted in generating the code, specific aspects AI helped with, and what human review/validation was performed
79+
- **Concise change description**: Exactly what was changed, why, and technical details
80+
- **Do NOT discuss**: Benefits, impact on users, or general statements about the value of the change
81+
82+
2. **Example PR Body**:
83+
84+
```markdown
85+
## AI Assistance Summary
86+
87+
This PR was generated with AI assistance for boilerplate code generation and structural
88+
implementation. The AI helped with [specific aspect], while human verification confirmed
89+
[what was validated].
90+
91+
## Changes
92+
93+
- Modified `packages/binding-foo/src/foo-client.ts` to implement ProtocolClient interface
94+
- Added error handling for connection timeouts
95+
- Updated corresponding test file
96+
97+
Fixes #123
98+
```
99+
100+
3. **PR Process**:
101+
- Create feature branch from master
102+
- Do NOT merge with master while developing
103+
- If master updates are needed, rebase: `git checkout master && git pull && git checkout - && git rebase master`
104+
- Ensure CI/CD checks pass
105+
- Do NOT force push unless absolutely necessary
106+
107+
---
108+
109+
## **WHEN REVIEWING CODE**
110+
111+
### **Review Scope & Guidelines**
112+
113+
1. **Primary Focus Areas**:
114+
115+
- Code correctness and adherence to W3C WoT standards
116+
- Compliance with repository coding standards (ESLint, Prettier, style guide)
117+
- Proper testing and test coverage
118+
- Commit message quality and signing
119+
- PR description completeness (especially AI assistance disclosure)
120+
121+
2. **Avoid Redundancy**:
122+
123+
- Do NOT repeat observations already in the PR author's initial summary/first comment
124+
- Read the PR description first to understand context and intent
125+
126+
3. **W3C WoT Standards Validation**:
127+
128+
- Verify implementation matches W3C WoT Thing Description specification
129+
- Check W3C WoT Scripting API compliance for any core changes
130+
- Validate protocol binding implementations against expected interfaces
131+
132+
4. **Ecosystem Impact Assessment**:
133+
- If reviewing core changes: verify impact across all dependent packages
134+
- Check if breaking changes are properly documented in PR body
135+
- Validate that bindings still function correctly
136+
137+
### **Comment Management**
138+
139+
1. **Consolidation Rule**:
140+
141+
- If you find yourself writing more than 5 separate comments:
142+
- Consolidate into a single summarized comment
143+
- Organize by category (critical issues, style, suggestions)
144+
- Clearly mark blockers vs. optional improvements
145+
- Ask contributor to review and respond to the summary comment
146+
147+
2. **Comment Examples**:
148+
- ✅ **Good**: Points out specific issue with concrete fix suggestion
149+
- ❌ **Avoid**: Repeating the same point multiple times across different comments
150+
- ✅ **Good**: Consolidating multiple style issues into: "Code style issues found in 3 locations: [list]. Please run `npm run format`"
151+
152+
### **Approval Criteria**
153+
154+
- [ ] All commits are signed with Eclipse account email
155+
- [ ] Code passes `npm run lint` and `npm run format`
156+
- [ ] All tests pass (`npm run test`)
157+
- [ ] PR body explains AI assistance and changes clearly
158+
- [ ] Conventional commit format followed
159+
- [ ] No unrelated changes to files
160+
- [ ] W3C WoT standards compliance verified
161+
- [ ] If core changes: dependent packages updated/validated
162+
- [ ] No merge conflicts with master
163+
164+
---
165+
166+
## **Key References for AI Agents**
167+
168+
| Resource | Purpose |
169+
| --------------------------------------------------------------------------------------------- | ----------------------------- |
170+
| [CONTRIBUTING.md](https://github.com/eclipse-thingweb/node-wot/blob/master/CONTRIBUTING.md) | Full contribution guidelines |
171+
| [W3C WoT Thing Description](https://www.w3.org/TR/2023/REC-wot-thing-description11-20231205/) | Core specification |
172+
| [W3C WoT Scripting API](https://w3c.github.io/wot-scripting-api/) | Required for core/API changes |
173+
| [Eclipse ECA](http://www.eclipse.org/legal/ECA.php) | Legal requirements |
174+
| [Eclipse Committer Handbook](https://www.eclipse.org/projects/handbook/) | Best practices |
175+
176+
---
177+
178+
## **Common Pitfalls to Avoid**
179+
180+
1. ❌ Unsigned commits → ✅ Always use `-s` flag with Eclipse account email
181+
2. ❌ Linting warnings → ✅ Run `npm run lint && npm run format` before commit
182+
3. ❌ Scope creep → ✅ Only modify files related to the specific change
183+
4. ❌ Missing AI disclosure → ✅ Always explain AI assistance in PR body
184+
5. ❌ Core changes without validation → ✅ Test impact on all dependent packages
185+
6. ❌ Large diffs → ✅ Strive for minimal, focused changes
186+
7. ❌ Verbose PR descriptions → ✅ Be concise and technical, not marketing-focused
187+
8. ❌ Excessive review comments → ✅ Consolidate into organized summary at 5+ comments

‎Dockerfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,4 @@ STOPSIGNAL SIGINT
3535
ENTRYPOINT [ "node", "dist/cli.js" ]
3636
CMD [ "-h" ]
3737

38-
## docker build -t wot-servient ./docker/Dockerfile
38+
## docker build -t node-wot ./docker/Dockerfile

‎README.md‎

Lines changed: 88 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,9 @@ For further information please refer to the official [W3C Web of Things](https:/
5656

5757
## Installation
5858

59-
The framework can be used in two ways: as a library or as a CLI tool. In this section we will explain how to install the framework in both ways.
59+
The framework is composed by different packages that users can use as they please. The core package is @node-wot/core and it is the only mandatory package to install. The other packages are bindings that allow the framework to communicate with different protocols.
6060

61-
### As a library
62-
63-
The framework is composed by different packages that users can use as they please. The core package is `@node-wot/core` and it is the only mandatory package to install. The other packages are bindings that allow the framework to communicate with different protocols.
64-
65-
#### Node.js
61+
### Prerequisite: Node.js with build tools
6662

6763
> [!WARNING]
6864
> We no longer actively support Node.js version 18 and lower.
@@ -81,27 +77,52 @@ Platforms specific prerequisites:
8177
- Mac OS: Meet the [node-gyp](https://github.com/nodejs/node-gyp#installation) requirements:
8278
- `xcode-select --install`
8379

84-
If you want to use node-wot as a library in your Node.js application, you can use npm to install the node-wot packages that you need. To do so, `cd` inside your application folder, and run:
80+
### As a library
81+
82+
If you want to use node-wot as a library in your Node.js application, you can use npm to install the node-wot packages that you need.
83+
Todo so, `cd` inside your application folder and install at least the mandatory core package:
8584

8685
```
87-
npm i @node-wot/core @node-wot/binding-http --save
86+
npm i @node-wot/core
8887
```
8988

90-
#### Browser
89+
Usually, your application needs at least one protocol binding to commmunicate, e.g.,:
9190

92-
To use node-wot as a browser-side JavaScript Library, the browser needs to support ECMAScript 2015.
91+
```
92+
npm i @node-wot/binding-http
93+
```
9394

94-
Using a browser with only ES5 support (e.g., IE 11) might be possible if you add polyfills. If you want to use node-wot as a library in your browser application, you can install the `@node-wot/browser-bundle` as following:
95+
In case the application shall consume Thing Descriptions that are stored locally, you would also need the `file` binding:
9596

9697
```
97-
npm i @node-wot/browser-bundle --save
98+
npm i @node-wot/binding-file
9899
```
99100

100-
you can find more installation options in the specific [package README](./packages/browser-bundle/README.md).
101+
You see other available bindings in the [packages folder](./packages), which you can install via `npm i @node-wot/<package-name>`.
102+
103+
### In the browser
104+
105+
To use node-wot as JavaScript library insde the Web browser, it needs to support ECMAScript 2015+. Using a browser with only ES5 support (e.g., IE 11) might be possible if you add polyfills.
106+
107+
If you want to use node-wot as a library in your browser application,`cd` inside your application folder and install the browser bundle:
108+
109+
```
110+
npm i @node-wot/browser-bundle
111+
```
112+
113+
You can find more (non-)installation options in the specific [package README](./packages/browser-bundle/README.md).
101114

102115
### As a CLI tool
103116

104-
You can alternatively use node-wot via its command line interface (CLI). Please visit the [CLI tool's Readme](<[url](https://github.com/eclipse-thingweb/node-wot/tree/master/packages/cli)>) to find out more.
117+
You can alternatively use node-wot via its command line interface (CLI). Please visit the [CLI tool README](https://github.com/eclipse-thingweb/node-wot/tree/master/packages/cli) to find out more.
118+
119+
#### As global tool
120+
121+
To make the `node-wot` command available on your machine, install the CLI tool in the global scope:
122+
123+
```
124+
npm i @node-wot/cli -g
125+
```
105126

106127
#### As a docker image
107128

@@ -119,16 +140,16 @@ Go into the repository:
119140
cd node-wot
120141
```
121142

122-
Build the Docker image named `wot-servient` from the `Dockerfile`:
143+
Build the Docker image named `node-wot` from the `Dockerfile`:
123144

124145
```
125146
npm run build:docker
126147
```
127148

128-
Run the wot-servient as a container:
149+
Run the `node-wot` as a container:
129150

130151
```
131-
docker run --rm wot-servient -h
152+
docker run --rm node-wot -h
132153
```
133154

134155
## Examples
@@ -231,12 +252,12 @@ Can't find your preferred MediaType? More codecs can be easily added by implemen
231252
Run all the steps above including "Link Packages" and then run this:
232253

233254
```
234-
wot-servient -h
255+
node-wot -h
235256
cd examples/scripts
236-
wot-servient
257+
node-wot
237258
```
238259

239-
Without the "Link Packages" step, the `wot-servient` command is not available and `node` needs to be used (e.g., Windows CMD shell):
260+
Without the "Link Packages" step, the `node-wot` command is not available and `node` needs to be used (e.g., Windows CMD shell):
240261

241262
```
242263
# expose
@@ -256,9 +277,9 @@ First [build the docker image](#as-a-docker-image) and then run the counter exam
256277

257278
```
258279
# expose
259-
docker run -it --init -p 8080:8080/tcp -p 5683:5683/udp -v "$(pwd)"/examples:/srv/examples --rm wot-servient /srv/examples/scripts/counter.js
280+
docker run -it --init -p 8080:8080/tcp -p 5683:5683/udp -v "$(pwd)"/examples:/srv/examples --rm node-wot /srv/examples/scripts/counter.js
260281
# consume
261-
docker run -it --init -v "$(pwd)"/examples:/srv/examples --rm --net=host wot-servient /srv/examples/scripts/counter-client.js --client-only
282+
docker run -it --init -v "$(pwd)"/examples:/srv/examples --rm --net=host node-wot /srv/examples/scripts/counter-client.js --client-only
262283
```
263284

264285
- The counter exposes the HTTP endpoint at 8080/tcp and the CoAP endpoint at 5683/udp and they are bound to the host machine (with `-p 8080:8080/tcp -p 5683:5683/udp`).
@@ -298,6 +319,51 @@ Below are small explanations of what they can be used for:
298319
- Smart Clock: It simply has a property affordance for the time. However, it runs 60 times faster than real-time to allow time-based decisions that can be easily tested.
299320
- Simple Coffee Machine: This is a simpler simulation of the coffee machine above.
300321

322+
## Experimental Features
323+
324+
### Data Mapping per Thing
325+
326+
node-wot allows configuration of "Data Mapping" which extracts specific values from a Thing's response object (e.g., getting `123` from a wrapper `{ value: 123, timestamp: ... }`). This is useful when the Interaction only cares about an inner value but the Thing returns a wrapper object.
327+
328+
This is configured using the experimental node-wot `nw:dataSchemaMapping` vocabulary in the Thing Description. It can be defined at the Thing level or globally injected via the `Servient` configuration:
329+
330+
```json
331+
{
332+
"title": "MyThing",
333+
"properties": {
334+
"status": {
335+
"type": "integer",
336+
"forms": [{ "href": "/status" }]
337+
}
338+
},
339+
"nw:dataSchemaMapping": {
340+
"nw:property": {
341+
"nw:valuePath": "/value"
342+
},
343+
"nw:action": {
344+
"nw:valuePath": "/value"
345+
},
346+
"nw:event": {
347+
"nw:valuePath": "/value"
348+
}
349+
}
350+
}
351+
```
352+
353+
The `nw:valuePath` supports simple JSON Pointer-like notation (e.g., `/value` or `value/nested`) or dot-notation (e.g., `value.nested`) and is evaluated _after_ content deserialization but _before_ JSON Schema validation. Currently, the `nw:` vocabulary is hardcoded internally and doesn't explicitly require an `@context` definition for node-wot to process it.
354+
355+
Servient-level configuration can be added to naturally inject this vocabulary to any consumed or exposed Thing Descriptions without the application needing to do it manually. In the `wot-servient.conf.json` file, you can specify this parameter under the `"servient"` key:
356+
357+
```json
358+
{
359+
"servient": {
360+
"dataSchemaMapping": {
361+
"nw:property": { "nw:valuePath": "/value" }
362+
}
363+
}
364+
}
365+
```
366+
301367
## Documentation
302368

303369
> [!WARNING]

‎eslint.config.mjs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ export default defineConfig([
8484
"n/no-unsupported-features/node-builtins": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
8585
"n/no-extraneous-import": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
8686
"n/no-deprecated-api": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
87-
"n/no-unpublished-import": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
87+
"n/no-unpublished-import": "error",
8888
"n/no-process-exit": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
8989
"n/hashbang": "warn",
9090

@@ -122,7 +122,7 @@ export default defineConfig([
122122
"@typescript-eslint/no-unused-vars": "off",
123123
"@typescript-eslint/no-unused-expressions": "off",
124124
"@typescript-eslint/no-require-imports": "error",
125-
"@typescript-eslint/prefer-nullish-coalescing": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
125+
"@typescript-eslint/prefer-nullish-coalescing": "error",
126126
"@typescript-eslint/no-empty-object-type": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
127127
"@typescript-eslint/no-floating-promises": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
128128

@@ -135,7 +135,7 @@ export default defineConfig([
135135

136136
"no-use-before-define": "error",
137137

138-
"no-unused-private-class-members": "off", // https://github.com/eclipse-thingweb/node-wot/issues/1430
138+
"no-unused-private-class-members": "error",
139139
"no-prototype-builtins": "off",
140140
"no-case-declarations": "off",
141141

0 commit comments

Comments
 (0)