feat: add URI lexer/parser with URL normalization (#1)

Introduce a compiler-style URI lexer and parser that returns a tokenized
AST, plus a stricter parseUrl normalizer for production URL validation.
Establish build/test tooling and packaging for dual ESM/CJS distribution
so the library is ready to publish.

Author: lxcid

.gitignore

@@ -0,0 +1,30 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Test coverage
+coverage/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment
+.env
+.env.local
+.env.*.local

.npmignore

@@ -0,0 +1,34 @@
+# Source files
+src/
+
+# Examples
+examples/
+
+# Scripts
+scripts/
+
+# Tests and coverage
+coverage/
+*.test.ts
+*.spec.ts
+
+# Config files
+tsconfig.json
+tsconfig.eslint.json
+vitest.config.ts
+eslint.config.js
+.prettierrc
+
+# Git
+.git/
+.gitignore
+
+# IDE
+.vscode/
+.idea/
+
+# Project files
+PROJECT_SUMMARY.md
+
+# Node
+node_modules/

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "semi": true
+}

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 - 2026-01-22
+
+### Added
+- Initial implementation
+- Lexer with explicit token types
+- Parser with support for:
+  - Optional schemes
+  - Scheme-relative URLs (//example.com)
+  - Host-ish URLs (example.com, localhost:3000)
+  - Absolute paths (/path)
+  - Relative paths
+  - Query strings and fragments
+  - IPv6 addresses
+  - Userinfo
+- Typed AST for URI components
+- Lossless parsing (raw values preserved)

CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to URI Parser
+
+Thank you for your interest in contributing to the URI Parser!
+
+## Development Setup
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Run tests:
+   ```bash
+   npm test
+   ```
+
+4. Run tests in watch mode:
+   ```bash
+   npm run test:watch
+   ```
+
+5. Run linter:
+   ```bash
+   npm run lint
+   ```
+
+## Project Structure
+
+```
+uri-parser/
+├── src/
+│   ├── lexer-types.ts    # Token type definitions
+│   ├── lexer.ts          # Lexer implementation
+│   ├── parser-types.ts   # AST type definitions
+│   ├── parser.ts         # Parser implementation
+│   ├── errors.ts         # Error classes
+│   └── index.ts          # Public API exports
+├── scripts/
+│   └── build.mjs         # Build script
+└── tests/                # Test files
+```
+
+## Design Philosophy
+
+This parser follows the temporal-parser philosophy:
+
+1. **Explicit tokens → shallow grammar → AST → later normalization**
+2. **Lexer is permissive and logic-light**
+3. **Parser builds a typed AST**
+4. **Lossless parsing** (raw values preserved)
+5. **Easy to extend** with normalization passes
+
+## Testing
+
+- Write tests for new features
+- Ensure existing tests pass
+- Aim for high code coverage
+- Test edge cases and error conditions
+
+## Code Style
+
+- Follow the existing code style
+- Use TypeScript strict mode
+- Add JSDoc comments for public APIs
+- Run `npm run lint:fix` before committing
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Run the test suite
+6. Submit a pull request
+
+## Questions?
+
+Feel free to open an issue for discussion!

LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Taskade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.