Add comprehensive GitHub Copilot instructions for foresta-js repository

.github/copilot-instructions.md

@@ -0,0 +1,116 @@
+# Foresta.js
+
+Foresta.js is a JavaScript library that provides a selector engine for JavaScript Abstract Syntax Trees (ASTs). It allows you to write CSS-like queries against ASTs generated by Esprima to extract specific expressions from JavaScript code.
+
+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.
+
+## Working Effectively
+
+- Bootstrap, build, and test the repository:
+  - `npm ci` -- installs dependencies from lockfile (takes ~2-3 seconds, NEVER CANCEL)
+  - `npm run build` -- builds all distribution formats (takes <1 second, NEVER CANCEL)
+  - `npm test` -- runs Jest test suite (takes <1 second, NEVER CANCEL)
+  - `npm run test:coverage` -- runs tests with coverage report (takes <2 seconds, NEVER CANCEL)
+
+- Alternative installation method:
+  - `npm install` -- installs dependencies and automatically runs prepare script (takes ~45-50 seconds, NEVER CANCEL)
+
+- Run examples to validate functionality:
+  - `node examples/basic.js` -- demonstrates all major features with sample code
+
+- Development workflow:
+  - `npm run test:watch` -- runs Jest in watch mode for development (interactive, press 'a' to run all tests, 'q' to quit)
+  - `npm run clean` -- removes dist/ directory
+  - `npm run prepare` -- runs clean and build (automatically triggered by npm install)
+
+## Validation
+
+- ALWAYS run through at least one complete end-to-end scenario after making changes.
+- Test the library functionality by running `node examples/basic.js` to verify all selector types work correctly.
+- Run `npm test` to ensure all 17 test cases pass.
+- ALWAYS run `npx eslint src/ test/ examples/ --env es6 --env node` before committing (no default eslint config exists).
+- The CI (.github/workflows/ci.yml) runs tests on Node.js 14.x, 16.x, 18.x, and 20.x.
+
+## Common Tasks
+
+The following are outputs from frequently run commands. Reference them instead of viewing, searching, or running bash commands to save time.
+
+### Repo root
+```
+ls -la
+.github/
+.gitignore
+README.md
+dist/           # Build output (created by npm run build)
+examples/
+jest.config.json
+logo.png
+node_modules/   # Dependencies (created by npm install/ci)
+package-lock.json
+package.json
+rollup.config.js
+src/
+test/
+```
+
+### Package.json scripts
+```json
+{
+  "scripts": {
+    "build": "rollup -c",
+    "test": "jest", 
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "clean": "rm -rf dist/",
+    "prepare": "npm run clean && npm run build"
+  }
+}
+```
+
+### Key files structure
+- `src/foresta.js` -- Main library source code (275 lines)
+- `test/foresta.test.js` -- Jest test suite (17 tests covering all functionality)
+- `examples/basic.js` -- Comprehensive usage examples
+- `dist/foresta.js` -- CommonJS build output
+- `dist/foresta.esm.js` -- ES Module build output  
+- `dist/foresta.umd.js` -- UMD build output for browsers
+
+### Core functionality
+The library provides these selector types:
+- `#IdentifierName` -- Select by identifier name (e.g., `#config`)
+- `ExpressionType` -- Select by AST node type (e.g., `Literal`, `FunctionExpression`)
+- `*` -- Wildcard, matches any expression type
+- Property modifiers -- `selector:property:modifier` (e.g., `#update:parent:value`)
+- Path queries -- Multi-level selectors (e.g., `Program VariableDeclaration VariableDeclarator`)
+
+### Dependencies
+- Runtime: `esprima` (v4.0.1) for JavaScript parsing
+- Dev: `jest`, `rollup`, `eslint`, `typescript`, `@types/esprima`
+
+### Build process
+- Uses Rollup to create 3 distribution formats from single source file
+- Build warning about module type is expected (can be ignored)
+- Outputs to `dist/` directory with automatic cleaning
+
+### Test coverage
+- 17 test cases covering all selector types and edge cases
+- ~92% statement coverage, ~74% branch coverage
+- Tests validate: basic functionality, literals, identifiers, property modifiers, wildcards, complex queries, edge cases
+
+### Manual validation scenarios
+After making changes, validate by running the example and checking that it produces:
+1. 3 literal values (4, 2, "hello")
+2. 1 instance of "theValue" identifier 
+3. 2 global variable declarations (theValue, config)
+4. 1 function expression via property modifier
+5. 1 binary expression (4 + 2)
+
+### CI validation
+The GitHub Actions workflow runs:
+```bash
+npm ci
+npm test  
+npm run test:coverage
+```
+
+Always ensure these commands pass before pushing changes.