diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..1f30eb9 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,179 @@ +# Bowser - Browser/Device/OS Detection Library + +Bowser is a lightweight JavaScript library for detecting browser, operating system, and device information from user-agent strings. It works in both browser and Node.js environments and provides a rich API for parsing and comparing browser capabilities. + +**ALWAYS follow these instructions first and fallback to additional search and context gathering only if the information here is incomplete or found to be in error.** + +## Working Effectively + +### Environment Setup +- **CRITICAL**: Use Node.js version 12.16.3 exactly. Newer versions (16+, 20+) will fail due to webpack/babel compatibility issues. +- Install nvm to manage Node.js versions if needed: + ```bash + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash + export NVM_DIR="$HOME/.nvm" + [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" + nvm install 12.16.3 + nvm use 12.16.3 + ``` + +### Bootstrap and Build +Follow these steps exactly in order: +1. **Install dependencies**: `npm ci` -- takes 6-7 seconds. Use npm ci instead of npm install for consistency. +2. **Build the library**: `npm run build` -- takes 4-5 seconds. NEVER CANCEL. Set timeout to 30+ seconds. +3. **Run tests**: `npm test` -- takes 8 seconds. NEVER CANCEL. Set timeout to 60+ seconds. +4. **Run linting**: `npm run lint:check` -- takes 1-2 seconds. + +### Build Troubleshooting +- **If build fails with "digital envelope routines::unsupported"**: You are using the wrong Node.js version. Switch to 12.16.3. +- **If build fails with "@babel/helper-compilation-targets" errors**: You are using the wrong Node.js version. Switch to 12.16.3. +- **npm install shows many deprecation warnings**: This is expected with the legacy dependencies, ignore these warnings. +- **Build shows webpack/babel warnings about core-js and caniuse-lite**: These are expected warnings, the build still succeeds correctly. +- **"WARNING: We noticed you're using the `useBuiltIns` option without declaring a core-js version"**: This is expected, ignore this warning. + +## Validation + +### Manual Testing Requirements +After making any changes, ALWAYS validate functionality: +1. **Test the built library**: Create a test script to verify bowser functionality works correctly +2. **Basic parsing test** (create test script in project root): + ```javascript + const bowser = require('./es5.js'); + const testUA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36'; + const browser = bowser.getParser(testUA); + console.log('Browser:', browser.getBrowserName()); + console.log('OS:', browser.getOSName()); + console.log('Platform:', browser.getPlatformType()); + ``` +3. **Verify build outputs**: Check that both `es5.js` and `bundled.js` are generated and have reasonable file sizes (~26KB and ~114KB respectively) + +### End-to-End Scenarios +Test these complete workflows after making changes: +- **Parse a modern browser UA**: Verify Chrome, Firefox, Safari detection works correctly +- **Parse mobile browser UA**: Test mobile Chrome, Safari iOS detection +- **Test satisfies() method**: Verify version comparison logic with common version patterns +- **Test alias resolution**: Verify browser aliases work (e.g., 'chrome' instead of 'Chrome') + +### Pre-commit Validation +ALWAYS run these before committing changes or the CI will fail: +- `npm run lint:check` - ESLint validation (1-2 seconds) +- `npm run build` - Verify builds successfully (4-5 seconds) +- `npm test` - Full test suite (8 seconds, 257 tests) + +## Development Workflow + +### Common Tasks +- **Add new browser support**: Update `src/parser-browsers.js` and add test cases to `test/acceptance/useragentstrings.yml` +- **Update browser aliases**: Modify `src/constants.js` following naming conventions (lowercase, underscores, no 'browser' suffix) +- **Fix parsing logic**: Main parsing logic is in `src/parser.js` +- **Update documentation**: Run `npm run generate-docs` to rebuild JSDoc documentation (takes <1 second) + +### Testing Strategy +- **Unit tests**: Located in `test/unit/` - test individual functions and methods +- **Acceptance tests**: Located in `test/acceptance/` - test against real user-agent strings from `useragentstrings.yml` +- **Test data**: The `useragentstrings.yml` file contains 200+ real user-agent strings with expected parsing results + +### Code Organization +``` +src/ +├── bowser.js # Main entry point and public API +├── parser.js # Core parsing logic and Parser class +├── parser-browsers.js # Browser detection patterns +├── parser-engines.js # Engine detection patterns +├── parser-os.js # Operating system detection +├── parser-platforms.js# Platform/device type detection +├── constants.js # Browser aliases and constants +└── utils.js # Utility functions + +test/ +├── unit/ # Unit tests for individual modules +└── acceptance/ # End-to-end tests with real user agents +``` + +## Build and Distribution + +### Output Files +- `es5.js` - Main transpiled version (~26KB) - referenced by package.json "main" field +- `bundled.js` - Version with babel polyfill included (~114KB) - for environments without polyfills +- Both files are UMD modules compatible with CommonJS, AMD, and browser globals + +### Webpack Configuration +- Uses webpack 4.41.0 with babel-loader for transpilation +- Targets ES5 for maximum compatibility +- Includes compression plugin for .gz versions +- Configuration in `webpack.config.js` + +## Timing Expectations + +**NEVER CANCEL these commands - wait for completion:** +- `npm ci`: 6-7 seconds +- `npm run build`: 4-5 seconds - NEVER CANCEL, set timeout to 30+ seconds +- `npm test`: 8 seconds - NEVER CANCEL, set timeout to 60+ seconds +- `npm run lint:check`: 1-2 seconds +- `npm run generate-docs`: <1 second + +## CI/CD Integration + +The project uses GitHub Actions (.github/workflows/): +- **pull-request.yml**: Runs on every PR, tests with Node.js 12.16.3 +- **merge-to-master.yml**: Handles merges to master branch +- **publish.yml**: Handles npm publishing +- Uses `npm ci`, `npm run build`, `npm test`, and `npm run lint:check` + +## Library Usage Patterns + +### Common API Usage +```javascript +// Get parser instance +const browser = Bowser.getParser(userAgentString); + +// Get browser info +browser.getBrowserName(); // "Chrome" +browser.getBrowserVersion(); // "91.0.4472.114" + +// Get OS info +browser.getOSName(); // "macOS" +browser.getOSVersion(); // "10.15.7" + +// Get platform info +browser.getPlatformType(); // "desktop" + +// Parse everything at once +Bowser.parse(userAgentString); + +// Version comparison +browser.satisfies({ + chrome: ">=70", + firefox: ">60" +}); +``` + +### Browser Aliases +Defined in `src/constants.js`. Follow these rules when adding: +- Use lowercase letters only +- Replace spaces/dashes with underscores +- Drop "browser" from names when possible +- Examples: "UC Browser" → "uc", "Opera Coast" → "opera_coast" + +## Troubleshooting + +### Common Issues +- **Build fails**: Wrong Node.js version - use 12.16.3 exactly +- **Tests fail**: Usually indicates real bugs - don't ignore failing tests +- **Lint errors**: Run `npm run lint:fix` to auto-fix style issues +- **New browser not detected**: Add patterns to `parser-browsers.js` and test cases to `useragentstrings.yml` + +### Debug Workflow +1. Add console.log() statements in parsing logic +2. Run single test: `npx ava test/unit/parser.js -m "*specific test*"` +3. Test with custom user agent: Create temporary test script +4. Check test data: Verify `useragentstrings.yml` has correct expected results + +## Documentation + +- **API docs**: Generated with JSDoc, run `npm run generate-docs` +- **Main docs**: `README.md` with usage examples +- **Contributing**: `.github/CONTRIBUTING.md` with development guidelines +- **Online demo**: https://bowser-js.github.io/bowser-online/ + +Always update documentation when making API changes or adding new features. \ No newline at end of file diff --git a/docs/Bowser.html b/docs/Bowser.html index eed807e..14d2e60 100644 --- a/docs/Bowser.html +++ b/docs/Bowser.html @@ -492,7 +492,7 @@ explicitly. Same as skipParsing for Parser diff --git a/docs/Parser.html b/docs/Parser.html index 0928cea..7273dc3 100644 --- a/docs/Parser.html +++ b/docs/Parser.html @@ -3596,7 +3596,7 @@ Returns undefined when the browser is no described in the checkTree
diff --git a/docs/bowser.js.html b/docs/bowser.js.html index da6872b..f2bdc3a 100644 --- a/docs/bowser.js.html +++ b/docs/bowser.js.html @@ -133,7 +133,7 @@ export default Bowser;
diff --git a/docs/global.html b/docs/global.html index bc53b64..5d541ff 100644 --- a/docs/global.html +++ b/docs/global.html @@ -2706,7 +2706,7 @@ like "iPhone" or "Kindle Fire HD 7" diff --git a/docs/index.html b/docs/index.html index 934a451..5dc820b 100644 --- a/docs/index.html +++ b/docs/index.html @@ -208,7 +208,7 @@ list of aliases can be found in the file.


diff --git a/docs/parser.js.html b/docs/parser.js.html index 7670ccb..0b176ed 100644 --- a/docs/parser.js.html +++ b/docs/parser.js.html @@ -567,7 +567,7 @@ export default Parser;
diff --git a/docs/utils.js.html b/docs/utils.js.html index bc5d34f..03eec59 100644 --- a/docs/utils.js.html +++ b/docs/utils.js.html @@ -365,7 +365,7 @@ export default class Utils {