Skip to content

Commit 29f2286

Browse files
jonathanKingstoncursoragent
jonathanKingston
and
cursoragent
authored
Initial code comments from PR reviews (#2084)
* Initial code comments from PR reviews * Make some tweaks to wording * Refactor docs and feature examples for clarity and best practices Co-authored-by: jkingston <jkingston@duckduckgo.com> * Refactor: Update coding guidelines and error handling Co-authored-by: jkingston <jkingston@duckduckgo.com> * Docs: Add link to privacy-configuration experiments guide Co-authored-by: jkingston <jkingston@duckduckgo.com> * Refactor conditional changes documentation Co-authored-by: jkingston <jkingston@duckduckgo.com> * Add SideEffects helper and update documentation Co-authored-by: jkingston <jkingston@duckduckgo.com> * Refactor: Remove unused SideEffects helper from MyFeature Co-authored-by: jkingston <jkingston@duckduckgo.com> * Refactor: Remove AI and XSS sections from coding guidelines Co-authored-by: jkingston <jkingston@duckduckgo.com> * Add C-S-S usage guidelines and decision checklist Co-authored-by: jkingston <jkingston@duckduckgo.com> * Refactor: Remove outdated coding guidelines Co-authored-by: jkingston <jkingston@duckduckgo.com> * Refactor: Clarify scope of injected features Co-authored-by: jkingston <jkingston@duckduckgo.com> * Refactor: Clarify README for injected features Co-authored-by: jkingston <jkingston@duckduckgo.com> * Add documentation rules for AI agents Co-authored-by: jkingston <jkingston@duckduckgo.com> * Remove documentation for AI agents Co-authored-by: jkingston <jkingston@duckduckgo.com> * More automated comments * Lint fix * Move comment to where it applies * Make getFeatureSettingEnabled default state message more prominent * Update lint fix after dep updates * Simplify README and add a CONTRIBUTING * Slim down heavily mdc file * Lint fix * Stale netlify cache on updates of pr * Flying blind with netifly ci * Dropping special pages docs --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com>
1 parent a23492a commit 29f2286

File tree

16 files changed

+918
-108
lines changed

16 files changed

+918
-108
lines changed

‎CONTRIBUTING.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Contributing
2+
3+
## Workspace-specific guides
4+
5+
- [Injected coding guidelines](./injected/docs/coding-guidelines.md)
6+
- [Injected testing guide](./injected/docs/testing-guide.md)
7+
- [Special Pages README](./special-pages/README.md)
8+
- [Messaging docs](./messaging/docs/messaging.md)
9+
10+
## Development
11+
12+
Consider using [nvm](https://github.com/nvm-sh/nvm) to manage node versions, after installing in the project directory run:
13+
14+
```
15+
nvm use
16+
```
17+
18+
From the top-level root folder of this npm workspace, you can run the following npm commands:
19+
20+
**Install dependencies**:
21+
22+
Will install all the dependencies we need to build and run the project:
23+
```
24+
npm install
25+
```
26+
27+
**Build all workspaces**:
28+
29+
Use this to produce the same output as a release. The `build` directory will be populated with
30+
various artifacts.
31+
32+
```sh
33+
npm run build
34+
```
35+
36+
> [!TIP]
37+
> You can run the `build` command from within any sub-project too, the artifacts will always be
38+
> lifted out to the root-level `build` folder.
39+
40+
**Run unit tests for all workspaces**:
41+
42+
```sh
43+
npm run test-unit
44+
```
45+
46+
**Run integration tests for all workspaces**:
47+
```sh
48+
npm run test-int
49+
```
50+
51+
**Run extended integration tests for all workspaces**:
52+
```sh
53+
npm run test-int-x
54+
```
55+
56+
**Clean tree and check for changes**:
57+
```sh
58+
npm run test-clean-tree
59+
```
60+
61+
**Generate documentation using TypeDoc**:
62+
```sh
63+
npm run docs
64+
```
65+
66+
**Generate and watch documentation using TypeDoc**:
67+
```sh
68+
npm run docs-watch
69+
```
70+
71+
**Compile TypeScript files**:
72+
```sh
73+
npm run tsc
74+
```
75+
76+
**Watch and compile TypeScript files**:
77+
```sh
78+
npm run tsc-watch
79+
```
80+
81+
**Lint the codebase using ESLint**:
82+
```sh
83+
npm run lint
84+
```
85+
86+
**Lint and automatically fix issues**:
87+
```sh
88+
npm run lint-fix
89+
```
90+
91+
**Serve integration test pages on port 3220**:
92+
```sh
93+
npm run serve
94+
```
95+
96+
**Serve special pages on port 3221**:
97+
```sh
98+
npm run serve-special-pages
99+
```
100+
101+
## Release Process
102+
103+
Releases are created via GitHub Actions: [Release workflow](https://github.com/duckduckgo/content-scope-scripts/actions/workflows/build.yml)
104+
105+
### Creating a release
106+
107+
1. Go to [Actions → Release](https://github.com/duckduckgo/content-scope-scripts/actions/workflows/build.yml)
108+
2. Click "Run workflow"
109+
3. Select version bump type
110+
4. Click "Run workflow"
111+
112+
The workflow creates a tag and GitHub release automatically. Build artifacts on the `releases` branch are consumed by native app repos.

‎README.md‎

Lines changed: 2 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -30,93 +30,6 @@ Utilities to automatically generate TypeScript types from JSON Schema files.
3030

3131
---
3232

33-
## NPM commands
33+
## Contributing
3434

35-
Consider using [nvm](https://github.com/nvm-sh/nvm) to manage node versions, after installing in the project directory run:
36-
37-
```
38-
nvm use
39-
```
40-
41-
From the top-level root folder of this npm workspace, you can run the following npm commands:
42-
43-
**Install dependencies**:
44-
45-
Will install all the dependencies we need to build and run the project:
46-
```
47-
npm install
48-
```
49-
50-
**Build all workspaces**:
51-
52-
Use this to produce the same output as a release. The `build` directory will be populated with
53-
various artifacts.
54-
55-
```sh
56-
npm run build
57-
```
58-
59-
> [!TIP]
60-
> You can run the `build` command from within any sub-project too, the artifacts will always be
61-
> lifted out to the root-level `build` folder.
62-
63-
**Run unit tests for all workspaces**:
64-
65-
```sh
66-
npm run test-unit
67-
```
68-
69-
**Run integration tests for all workspaces**:
70-
```sh
71-
npm run test-int
72-
```
73-
74-
**Run extended integration tests for all workspaces**:
75-
```sh
76-
npm run test-int-x
77-
```
78-
79-
**Clean tree and check for changes**:
80-
```sh
81-
npm run test-clean-tree
82-
```
83-
84-
**Generate documentation using TypeDoc**:
85-
```sh
86-
npm run docs
87-
```
88-
89-
**Generate and watch documentation using TypeDoc**:
90-
```sh
91-
npm run docs-watch
92-
```
93-
94-
**Compile TypeScript files**:
95-
```sh
96-
npm run tsc
97-
```
98-
99-
**Watch and compile TypeScript files**:
100-
```sh
101-
npm run tsc-watch
102-
```
103-
104-
**Lint the codebase using ESLint**:
105-
```sh
106-
npm run lint
107-
```
108-
109-
**Lint and automatically fix issues**:
110-
```sh
111-
npm run lint-fix
112-
```
113-
114-
**Serve integration test pages on port 3220**:
115-
```sh
116-
npm run serve
117-
```
118-
119-
**Serve special pages on port 3221**:
120-
```sh
121-
npm run serve-special-pages
122-
```
35+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, npm commands, and release process.

‎injected/.cursor/rules/injected.mdc‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
description: Guidelines for features running in web page DOM environments
3+
globs: injected/**
4+
---
5+
6+
# Injected Features
7+
8+
JavaScript features injected into web pages or running in DOM environments of DuckDuckGo browsers. Features extend `ContentFeature` and `ConfigFeature` and integrate with remote configuration for per-site enable/disable.
9+
10+
**See also:**
11+
- `docs/coding-guidelines.md` for code style, patterns, and examples
12+
- `docs/css-decision-guide.md` for when to use C-S-S vs native code
13+
- [privacy-configuration experiments guide](https://github.com/duckduckgo/privacy-configuration/blob/main/.cursor/rules/content-scope-experiments.mdc) for A/B testing features
14+
15+
## Structure
16+
17+
```
18+
src/features/<name>.js # Feature implementation (extends ContentFeature)
19+
src/features.js # Feature registry (baseFeatures + otherFeatures arrays)
20+
entry-points/<platform>.js # Platform-specific bundles
21+
integration-test/ # Playwright integration tests
22+
unit-test/ # Jasmine unit tests
23+
```
24+
25+
**Adding a new feature:** Add to `baseFeatures` or `otherFeatures` in `src/features.js`, then add to relevant platform arrays in `platformSupport`.
26+
27+
## TypeScript
28+
29+
JSDoc types in JavaScript files. Import types via `@typedef`:
30+
31+
```javascript
32+
/** @typedef {import('../types/feature.js').SettingType} SettingType */
33+
```
34+
35+
## Testing
36+
37+
Run from `injected/` directory:
38+
39+
| Command | Purpose |
40+
|---------|---------|
41+
| `npm run test-unit` | Jasmine unit tests |
42+
| `npm run test-int` | Playwright integration tests |
43+
| `npm run build` | Build all platform bundles |
44+
45+
Integration tests use test pages in `integration-test/test-pages/`.
46+
47+
## Key Patterns
48+
49+
- **Event listeners**: Use `handleEvent` pattern or stored references (avoid `.bind(this)`)
50+
- **API existence**: Check `typeof API === 'function'` before wrapping
51+
- **DOM timing**: Check `document.readyState` before accessing DOM
52+
- **Error types**: Match native error signatures in API shims
53+
54+
See `docs/coding-guidelines.md` for DDGProxy, captured globals, retry utilities, and other patterns.
55+
56+
## Platform Considerations
57+
58+
Features are bundled per-platform in `entry-points/`:
59+
- `apple.js` - iOS/macOS
60+
- `android.js` - Android
61+
- `windows.js` - Windows
62+
- `extension-mv3.js` - Browser extension
63+
64+
Platform-specific features: `navigatorInterface`, `windowsPermissionUsage`, `messageBridge`, `favicon` (see `utils.js` `platformSpecificFeatures`).
65+
66+
## Notes
67+
68+
- When running Playwright commands, use `--reporter list` to prevent hanging
69+
- Features can be enabled/disabled per-site via remote config
70+
- Add debug flags with `this.addDebugFlag()` for breakage reports

‎injected/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Content Scope Scripts handles injecting DOM modifications in a browser context;
44

55
## Quick Start
66

7-
Content Scope Scripts provides a unified API for browser privacy features across multiple platforms (Firefox, Chrome, Safari, Android, iOS). Features are loaded dynamically based on remote configuration and can be enabled/disabled per site.
7+
Content Scope Scripts provides a unified API for features running in web page DOM environments across multiple platforms (Firefox, Chrome, Safari, Android, iOS). Features are loaded dynamically based on remote configuration and can be enabled/disabled per site.
88

99
## Documentation
1010

@@ -23,12 +23,12 @@ Content Scope Scripts provides a unified API for browser privacy features across
2323
Content Scope Scripts contains two main sub-projects:
2424

2525
- **[Special Pages](../special-pages/)** - HTML/CSS/JS applications loaded into browsers (DuckPlayer, Release Notes, New Tab page, etc.)
26-
- **Injected Features** - Features injected into websites (privacy protections, compatibility fixes)
26+
- **Injected Features** - Features injected into websites (privacy protections, compatibility fixes, DOM manipulations)
2727

2828
> **For Special Pages development**, see the [Special Pages README](../special-pages/README.md) for detailed getting started instructions.
2929
3030
### Features
31-
Features are JavaScript modules that implement privacy protections. Each feature:
31+
Features are JavaScript modules running in web page DOM environments. Each feature:
3232
- Extends the `ConfigFeature` class for remote configuration support
3333
- Implements the feature lifecycle (`load`, `init`, `update`)
3434
- Can be enabled/disabled per site via remote configuration

‎injected/docs/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ This directory contains detailed documentation for the Content Scope Scripts pro
1515

1616
- **[Development Utilities](./development-utilities.md)** - Scope injection utilities and development tools
1717
- **[Testing Guide](./testing-guide.md)** - Local testing and development workflow
18+
- **[Coding Guidelines](./coding-guidelines.md)** - Code style, architecture, security, and performance guidelines
1819

1920
### Existing Documentation
2021

@@ -25,7 +26,8 @@ This directory contains detailed documentation for the Content Scope Scripts pro
2526

2627
If you're new to Content Scope Scripts, start with the main [README](../README.md) for a high-level overview, then dive into the specific documentation based on your needs:
2728

28-
- **Building features?** → [Features Guide](./features-guide.md)
29+
- **Building features?** → [Features Guide](./features-guide.md) (feature files contain inline guidelines)
30+
- **Writing code?** → [Coding Guidelines](./coding-guidelines.md)
2931
- **Integrating with a platform?** → [Platform Integration](./platform-integration.md) and [Platform-Specific Build & Troubleshooting Tips](./build-and-troubleshooting.md)
3032
- **Using the API?** → [API Reference](./api-reference.md)
3133
- **Developing utilities?** → [Development Utilities](./development-utilities.md)

0 commit comments

Comments
 (0)