From 0f66572dcbf83a36fd868b19d1ccab347c604fbe Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 9 Nov 2025 13:32:46 +0000 Subject: [PATCH 1/2] Initial plan From 6d9528c4fba49fdddc4fd0540a9acbb8dcb674c5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 9 Nov 2025 13:39:19 +0000 Subject: [PATCH 2/2] Enhance copilot-instructions.md with best practices sections Co-authored-by: ttt43ttt <132509+ttt43ttt@users.noreply.github.com> --- .github/copilot-instructions.md | 105 ++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 384241b..6e88714 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,8 +2,39 @@ Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. +## About This Project + OpenCV-JS is a TypeScript NPM package that provides OpenCV.js (JavaScript/WebAssembly version of OpenCV) for both Node.js and browser environments. The package wraps a pre-built 11MB OpenCV.js WASM binary with TypeScript type definitions. +**Repository:** https://github.com/TechStark/opencv-js +**NPM Package:** [@techstark/opencv-js](https://www.npmjs.com/package/@techstark/opencv-js) +**Version:** 4.12.0-release.1 + +## Technology Stack + +- **Language:** TypeScript +- **Runtime:** Node.js 20.x (also supports browser environments) +- **Build Tool:** TypeScript Compiler (tsc) +- **Testing:** Jest with ts-jest +- **Package Manager:** npm +- **OpenCV Version:** 4.12.0 (WebAssembly/JavaScript build) +- **Key Dependencies:** Jimp (for image loading in tests) + +## Table of Contents + +- [Working Effectively](#working-effectively) +- [Package Usage Patterns](#package-usage-patterns) +- [Testing and Validation](#testing-and-validation) +- [File Structure and Navigation](#file-structure-and-navigation) +- [CI/CD and Publishing](#cicd-and-publishing) +- [Common Development Tasks](#common-development-tasks) +- [Browser vs Node.js Differences](#browser-vs-nodejs-differences) +- [Performance and Timing Expectations](#performance-and-timing-expectations) +- [Troubleshooting](#troubleshooting) +- [Security Considerations](#security-considerations) +- [External Documentation](#external-documentation) +- [Contributing Guidelines](#contributing-guidelines) + ## Working Effectively ### Initial Setup and Build @@ -176,4 +207,78 @@ After making changes, ALWAYS test these scenarios: - `npm audit` - Check for security vulnerabilities - `npm pack && tar -tzf *.tgz | head -20` - Inspect package contents +## Security Considerations + +### Dependency Security +- ALWAYS run `npm audit` before committing changes +- Use `npm audit fix` to automatically fix security vulnerabilities +- Review security advisories for OpenCV.js and WebAssembly-related issues +- Keep TypeScript and build dependencies up to date + +### WASM Binary Safety +- The `dist/opencv.js` file is a pre-built WebAssembly binary from OpenCV.org +- Verify the source when updating: https://docs.opencv.org/4.12.0/opencv.js +- Do NOT accept modified opencv.js files from untrusted sources + +### Memory Safety +- Always call `.delete()` on OpenCV objects to prevent memory leaks +- Memory leaks in WASM can cause browser crashes or performance degradation +- Use try/finally blocks to ensure cleanup even when errors occur + +### Input Validation +- Validate image dimensions and formats before processing +- Handle invalid inputs gracefully to prevent crashes +- Be cautious with user-provided images in browser environments + +## External Documentation + +### OpenCV Resources +- [OpenCV.js Documentation](https://docs.opencv.org/4.12.0/d5/d10/tutorial_js_root.html) +- [OpenCV.js Tutorials](https://docs.opencv.org/4.12.0/#:~:text=OpenCV%2DPython%20Tutorials-,OpenCV.js%20Tutorials,-Tutorials%20for%20contrib) +- [OpenCV.js API Reference](https://docs.opencv.org/4.12.0/d0/de1/group__js.html) +- [OpenCV Build Information](https://docs.opencv.org/4.12.0/opencv.js) + +### Package Resources +- [NPM Package Page](https://www.npmjs.com/package/@techstark/opencv-js) +- [GitHub Repository](https://github.com/TechStark/opencv-js) +- [Code Examples Repository](https://github.com/TechStark/opencv-js-examples) +- [Live Demo (React)](https://codesandbox.io/s/techstarkopencv-js-demo-page-f7gvk) +- [Live Demo (Angular)](https://codesandbox.io/s/techstark-opencv-js-angular-demo-hkmc1n) +- [Face Detection Demo](https://codesandbox.io/s/opencv-js-face-detection-i1i3u) + +### TypeScript Resources +- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) +- [Jest Testing Framework](https://jestjs.io/docs/getting-started) +- [ts-jest Configuration](https://kulshekhar.github.io/ts-jest/) + +## Contributing Guidelines + +### Before Making Changes +1. Search existing issues and PRs to avoid duplicates +2. For significant changes, open an issue first to discuss +3. Fork the repository and create a feature branch +4. Ensure you understand the codebase by running: `npm install && npm run build && npm test` + +### Making Changes +1. Follow existing code style and patterns +2. Add TypeScript type definitions for new OpenCV features +3. Include tests for new functionality in the `test/` directory +4. Update documentation if adding new features or changing behavior +5. Ensure all tests pass: `npm test` +6. Format code: `npm run format` +7. Check for security issues: `npm audit` + +### Submitting Changes +1. Write clear, descriptive commit messages +2. Reference related issues in commit messages (e.g., "Fixes #123") +3. Ensure CI/CD workflows pass (unit tests, build) +4. Provide clear PR description explaining the changes +5. Be responsive to review feedback + +### Code Review Process +- PRs require passing CI checks before merge +- Maintainer review is required +- Keep PRs focused and reasonably sized +- Update type definitions when adding new OpenCV methods + ALWAYS follow these patterns for reliable OpenCV-JS development and avoid common pitfalls with async initialization and memory management. \ No newline at end of file