296 lines
8.4 KiB
Markdown
296 lines
8.4 KiB
Markdown
# Project Specifications for TypeScript NPM Module
|
|
|
|
- name of package: tiny-pattern-ts
|
|
|
|
## 0. References
|
|
|
|
typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starter-tiny/
|
|
|
|
## 1. Development Environment
|
|
|
|
- **TypeScript**: Use strictest rules (via npm package "@tsconfig/strictest", additional strictures)
|
|
- **EditorConfig**: Use `.editorconfig` from typescript-lib-starter-tiny
|
|
- **Prettier**: For code formatting, integrated with ESLint
|
|
- **ESLint**: Strictest type-checked rules, integrated with Prettier
|
|
- **Import Sorting**: Via Prettier or ESLint
|
|
- **cspell**: Basic spelling configuration
|
|
- **Lefthook**: Pre-commit checks for:
|
|
|
|
- Type checking
|
|
- Spelling
|
|
- Package sorting
|
|
- Linting
|
|
- Formatting
|
|
- Outdated Packages
|
|
|
|
- **Additional Dev Dependencies**:
|
|
|
|
- lefthook
|
|
- sort-package-json
|
|
- check-outdated
|
|
|
|
## 2. Build & Test
|
|
|
|
- **Build Tool**: Vite (ESM only, no CJS)
|
|
- **Testing**: Vitest
|
|
- **TypeScript Build Output**: `dist` directory
|
|
- **Additional Runtime Dependencies**:
|
|
- tslib
|
|
- type-fest
|
|
|
|
## 3. Project Structure & Files
|
|
|
|
- __.gitignore__: Ignore `dist`, `node_modules`, and other common files
|
|
- **.npmignore**: Ignore `src` and other non-dist files
|
|
- **LICENSE**: MIT
|
|
- **README.md**: Scaffolded
|
|
- **commit-message-template**: From typescript-lib-starter-tiny
|
|
- **Target Environments**: Browser and latest LTS Node.js
|
|
- **No React, No CJS, ESM only**
|
|
|
|
## 4. Automation & Quality
|
|
|
|
- **Version Automation**: Use standard `npm version` for versioning
|
|
- **Unused Dependency Check**: Use `check-outdated` with config
|
|
- **No commitlint, no conventional commits**
|
|
|
|
## 5. Scripts (Clustered as in typescript-lib-starter-tiny, named similarly)
|
|
|
|
### SETUP
|
|
|
|
- `use:git-commit-message`: Set up commit message template (if needed)
|
|
|
|
### TEST
|
|
|
|
- `test`: Run typecheck and all tests
|
|
- `test:unit`: Run unit tests with Vitest
|
|
- `test:ci`: Run tests in CI mode (with coverage, fail-fast)
|
|
|
|
### BUILD
|
|
|
|
- `build`: Build the project using Vite
|
|
|
|
### CLEAN
|
|
|
|
- `clean`: Clean build output
|
|
- `clean:build`: Remove dist directory
|
|
|
|
### CHECK
|
|
|
|
- `check`: Run all checks (lint, spell, typecheck, import/package sort, outdated)
|
|
- `check:eslint`: Run ESLint
|
|
- `check:prettier`: Check formatting with Prettier
|
|
- `check:cspell`: Run cspell
|
|
- `check:tsc`: TypeScript typecheck (no emit)
|
|
- `check:package`: Check package.json sort
|
|
- `check:outdated`: Check for unused/outdated dependencies
|
|
|
|
### FIX
|
|
|
|
- `fix`: Run all fixers (eslint, prettier, package sort)
|
|
- `fix:eslint`: Auto-fix ESLint issues
|
|
- `fix:prettier`: Auto-fix formatting with Prettier
|
|
- `fix:package`: Auto-fix package.json sort
|
|
|
|
### HOOKS
|
|
|
|
- Lefthook will run relevant scripts on staged files for pre-commit (typecheck, lint, spell, sort, format, check:outdated)
|
|
|
|
---
|
|
|
|
## 6. Repository & CI/CD
|
|
|
|
- **Repository**: Hosted on GitHub
|
|
- **Build Pipeline**: Use GitHub Actions for CI/CD
|
|
- On push and pull request: run build, lint, typecheck, test:ci, spell, check:outdated
|
|
- On release (tagged commit): publish to npm
|
|
|
|
## 7. Versioning & Publishing
|
|
|
|
- **Version Update**: Use `npm version` to bump version after merging to main and before publishing
|
|
- **Publishing to npm**: Only publish from CI on tagged commits (e.g., after version bump and release notes)
|
|
- **Recommended Workflow**:
|
|
1. Develop and merge PRs to main
|
|
2. Run all checks via CI
|
|
3. Bump version with `npm version <patch|minor|major>`
|
|
4. Push tag to GitHub
|
|
5. CI builds and publishes to npm on tag
|
|
|
|
## 8. NPM Keywords
|
|
|
|
- pattern-matching
|
|
- pattern
|
|
- match
|
|
- algebraic-data-types
|
|
- adt
|
|
- typescript
|
|
|
|
> The library is for pattern matching (not regex), similar to F#'s pattern matching, for TypeScript/ESM environments.
|
|
|
|
## 9. Code Coverage
|
|
|
|
- **Configuration**:
|
|
|
|
```ts
|
|
import { defineConfig } from 'vitest/config';
|
|
export default defineConfig({
|
|
test: {
|
|
coverage: {
|
|
reporter: ['text', 'html', 'lcov'],
|
|
include: ['src/**/*.ts'],
|
|
exclude: ['src/**/*.test.ts', 'test/**'],
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
- Coverage reports: text summary, HTML, and lcov formats
|
|
|
|
- Add coverage thresholds if desired
|
|
|
|
- **CI**: Ensure coverage is generated and optionally uploaded as an artifact or checked for minimum thresholds
|
|
|
|
## 10. Source Structure & Tree Shaking
|
|
|
|
- **Source Directory**: All source code resides in `src/` and is exported via `src/index.ts`.
|
|
- **Configuration**:
|
|
- Ensure `sideEffects: false` in `package.json`
|
|
- Use ESM-only exports
|
|
- Avoid top-level side effects in modules
|
|
- Prefer explicit exports in `index.ts` for best results
|
|
- the human will implement the source code
|
|
|
|
## 11. Included Templates from typescript-lib-starter-tiny
|
|
|
|
### .editorconfig
|
|
|
|
```plaintext
|
|
# Editor configuration, see http://editorconfig.org
|
|
root = true
|
|
|
|
[*]
|
|
charset = utf-8
|
|
indent_style = space
|
|
indent_size = 4
|
|
insert_final_newline = true
|
|
max_line_length = 80
|
|
trim_trailing_whitespace = true
|
|
quote_type = double
|
|
|
|
[*.md]
|
|
max_line_length = 0
|
|
trim_trailing_whitespace = false
|
|
|
|
[COMMIT_EDITMSG]
|
|
max_line_length = 0
|
|
```
|
|
|
|
### commit-message-template
|
|
|
|
```plaintext
|
|
# If applied, this commit will... (Max 50 char)
|
|
|
|
|
|
# Explain why this change is being made (Max 72 Char) [WHAT and WHY vs HOW]
|
|
|
|
|
|
# Provide links or keys to any relevant tickets, articles or other resources
|
|
Resolves #...
|
|
|
|
# --- COMMIT END ---
|
|
# Remember to
|
|
# Use the imperative mood in the subject line
|
|
# Capitalize the subject line
|
|
# Do not end the subject line with a period
|
|
# Separate subject from body with a blank line
|
|
# Use the body to explain what and why vs. how
|
|
# Can use multiple lines with "-" for bullet points in body
|
|
```
|
|
|
|
### README.md Structure (to scaffold)
|
|
|
|
- Project title and description
|
|
- Development
|
|
- Build: `npm run build`
|
|
- Test: `npm run test`, `npm run test:ci`
|
|
- Checks: `npm run check`, `npm run fix`
|
|
- VSCode integration
|
|
- Debugging
|
|
- Running tests
|
|
- Document workflows like
|
|
- Version updates
|
|
- Changelog automation
|
|
- Publishing
|
|
- Contribution guidelines
|
|
- Commit signing (GPG)
|
|
- How to set up commit message template
|
|
- Reference to commit-message-template
|
|
|
|
## 12. Project Initialization & Commit Strategy
|
|
|
|
- Start by initilizing git with a main branch
|
|
- Initial commit: add an empty README.md
|
|
- create a feature branch: `feature/setup`
|
|
- For each technology or tool added (and its configuration), create a separate commit:
|
|
- Prepend each commit message with a matching gitmoji (e.g., :sparkles: for new features, :wrench: for config, etc.)
|
|
- Example commit messages:
|
|
- :tada: Initial commit with empty README
|
|
- :sparkles: Configured Vite (Vite-specific setup)
|
|
- :sparkles: Configured TypeScript (may be merged with Vite if dependent)
|
|
- :wrench: Configured ESLint
|
|
- :wrench: Configured Prettier
|
|
- ...and so on for each technology/tool
|
|
- Each commit should include only the relevant files and configuration for that technology/tool
|
|
- This approach ensures a clean, understandable project history and makes it easy to review or revert specific setup steps
|
|
|
|
|
|
## 13. Changelog Automation
|
|
|
|
- Use a tool like standard-version or changesets to automate changelog generation from commit messages or PRs.
|
|
- Ensure changelog is updated as part of the release process.
|
|
|
|
## 14. Publishing Public
|
|
|
|
- Configure npm publishing to be public by default.
|
|
- Add `"publishConfig": { "access": "public" }` to package.json.
|
|
- Ensure CI/CD pipeline publishes with public access.
|
|
|
|
## 15. VSCode Integration
|
|
|
|
- Add a `.vscode/settings.json` with the following content:
|
|
|
|
```json
|
|
{
|
|
"typescript.tsdk": "node_modules/typescript/lib",
|
|
"[typescript]": {
|
|
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
|
"editor.formatOnSave": true
|
|
},
|
|
"[json]": {
|
|
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
|
"editor.formatOnSave": true
|
|
},
|
|
"[mdx]": {
|
|
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
|
"editor.formatOnSave": true
|
|
},
|
|
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
|
"editor.formatOnSave": true,
|
|
"[javascript]": {
|
|
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
|
"editor.formatOnSave": true
|
|
}
|
|
}
|
|
```
|
|
|
|
- Add `.vscode/extensions.json` with recommended extensions:
|
|
- `esbenp.prettier-vscode` (Prettier)
|
|
- `dbaeumer.vscode-eslint` (ESLint)
|
|
- `streetsidesoftware.code-spell-checker` (cspell)
|
|
- `vitest.explorer` (for test integration)
|
|
- `ms-vscode.vscode-typescript-next` (for latest TS features, optional)
|
|
|
|
- Add `.vscode/tasks.json` for common tasks (optional):
|
|
- Build, test, lint, typecheck, format, spell, check:outdated
|
|
- Ensure VSCode uses workspace TypeScript version and Prettier for formatting
|