fix(docs): refresh package documentation and align metadata with current project layout
This commit is contained in:
@@ -1,5 +1,13 @@
|
||||
# Changelog
|
||||
|
||||
## 2026-05-09 - 10.0.1 - fix(docs)
|
||||
refresh package documentation and align metadata with current project layout
|
||||
|
||||
- replace the generic README with project-specific usage, behavior, and layout documentation
|
||||
- remove obsolete docs pages and switch the packaged license file from license.md to license
|
||||
- simplify build and test script commands and update @git.zone development dependency versions
|
||||
- drop the unused tsconfig baseUrl setting and align package author metadata
|
||||
|
||||
## 2026-03-24 - 10.0.0 - BREAKING CHANGE(package)
|
||||
migrate package to the @git.zone scope and ESM-based tooling
|
||||
|
||||
|
||||
@@ -1,9 +0,0 @@
|
||||
[Legal Info](https://lossless.gmbh)
|
||||
[Privacy Policy](https://lossless.gmbh/privacy.html)
|
||||
///
|
||||
[Git.Zone](https://git.zone)
|
||||
<span>tools for a seamless dev workflow</span>
|
||||
|
||||
[Lossless GmbH](https://push.rocks)
|
||||
<span>the company behind git.zone and npmts</span>
|
||||
///
|
||||
@@ -1,10 +0,0 @@
|
||||
# Changelog
|
||||
|
||||
## 2017-07-30: Version 7.x.x -> 8.x.x
|
||||
|
||||
Testfiles in ./test/ can now import files directly from the ts dir:
|
||||
|
||||
```javascript
|
||||
// ./test/test.ts
|
||||
import * as myModule from '../ts/index
|
||||
```
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
name: config
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
npmts can be configured to your needs.
|
||||
|
||||
### npmextra.json
|
||||
|
||||
the npmts section in npmextra.json can be used to configure npmts.
|
||||
|
||||
**Default**
|
||||
|
||||
> Note: When you are using `"mode":"default"` it'll cause npmts to override any other settings you may have made except for tsOptions (ES target etc.)
|
||||
> with default behaviour.
|
||||
|
||||
```json
|
||||
{
|
||||
"npmts": {
|
||||
"mode": "default"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Custom settings**
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "custom",
|
||||
"test": true,
|
||||
"npmts": {
|
||||
"ts": {
|
||||
"./customdir/*.ts": "./"
|
||||
},
|
||||
"tsOptions": {
|
||||
"declaration": false,
|
||||
"target": "ES6"
|
||||
},
|
||||
"cli": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| key | default value | description |
|
||||
| -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `"mode"` | `"default"` | "default" will do default stuff and override , "custom" only does what you specify, "merge" will merge default options with whatever you specify on your own |
|
||||
| `"test"` | `true` | test your module |
|
||||
| `"ts"` | `{"./ts/*.ts":"./","./test/test.ts":"./test/"}` | allows you to define multiple ts portions |
|
||||
| `"tsOptions"` | `{"target":"ES5", "declaration":"true"}` | specify options for tsc |
|
||||
| `"cli"` | `"false"` | some modules are designed to be used from cli. If set to true NPMTS will create a cli.js that wires you dist files up for cli use. |
|
||||
| `"testConfig"` | `{ parallel: true, coverage: true }` | allows you to control test behaviour. `"parallel"` controls wether testfiles are run sequentially or in parallel, and `"coverage` wether to create coverage reports |
|
||||
|
||||
### TypeScript
|
||||
|
||||
by default npmts looks for `./ts/*.ts` and `./test/test.ts` that will compile to
|
||||
`./dist/*.js` and `./test/test.js`
|
||||
|
||||
Use commonjs module system for wiring up files.
|
||||
|
||||
### Declaration files
|
||||
|
||||
**npmts** also creates declaration files like `./dist/index.d.ts` by default.
|
||||
You can reference it in your package.json like this.
|
||||
|
||||
```json
|
||||
"main": "dist/index.js",
|
||||
"typings": ".dist/index.d.ts",
|
||||
```
|
||||
|
||||
This is in line with the latest TypeScript best practices.
|
||||
You can then import plugins via the TypeScript `import` Syntax
|
||||
and tsc will pick up the declaration file automatically.
|
||||
|
||||
## Some notes:
|
||||
|
||||
#### Typings for third party modules that do not bundle declaration files
|
||||
|
||||
NPMTS no longer supports typings.json. Instead use the new TypeScript 2.x approach to typings using the @types/ npm scope.
|
||||
|
||||
#### Instrumentalize Code
|
||||
|
||||
npmts instrumentalizes (using istanbul) the created JavaScript code to create a coverage report.
|
||||
|
||||
#### Tests
|
||||
|
||||
Any errors will be shown with reference to their originating source in TypeScript
|
||||
thanks to autogenerated source maps.
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
name: Default Behaviour
|
||||
---
|
||||
|
||||
# Default Behaviour
|
||||
|
||||
when you don't configure it otherwise.
|
||||
|
||||
1. **Config:** Check config in ./npmextra.json (Check out [npmextra](https://www.npmjs.com/package/npmextra))
|
||||
1. **Clean:** Clean up from any previous builds (old js files)
|
||||
1. **Check:** Check project for typings declaration in package.json, unused dependencies and missing dependencies
|
||||
1. **Transpile:** Transpile TypeScript with **inline sourcemaps** and **declaration files** to ES target
|
||||
1. **Test:** transpile TypeScript of module to ES5 for tests (so it can be instrumentalized) and pipe it to tapbuffer. All this happens in memory.
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
name: Examples
|
||||
---
|
||||
|
||||
# Examples
|
||||
|
||||
modules that use npmts in theis development workflow
|
||||
|
||||
| Module Name | Description |
|
||||
| ---------------------------------------------------------- | --------------------------- |
|
||||
| [gitzone](https://www.npmjs.com/package/gitzone) | fast npm module prototyping |
|
||||
| [gulp-browser](https://www.npmjs.com/package/gulp-browser) | browserify for gulp |
|
||||
| [npmdocker](https://www.npmjs.com/package/npmdocker) | dockerized npm development |
|
||||
| [smartcli](https://www.npmjs.com/package/smartcli) | easy cli tool creation |
|
||||
|
||||
> There are tons more... We will add them here over time.
|
||||
|
||||
### Tips and tricks:
|
||||
|
||||
- Use [npmts-g](https://www.npmjs.com/package/npmts-g) to use globally installed npmts and install npmts locally if no global npmts is available.
|
||||
- Use [npmpage](https://www.npmjs.com/package/npmpage) to create a webpage from coverage reports and TypeDoc for the module
|
||||
- Use [hosttoday/ht-docker-node:npmci](https://hub.docker.com/r/hosttoday/ht-docker-node/) for speedy CI builds
|
||||
- Use [npmdocker](https://www.npmjs.com/package/npmdocker) for running tests consistently with docker.
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
name: Get Started
|
||||
description: learn how to quickly write npm TypeScript modules
|
||||
---
|
||||
|
||||
# Get Started with NPMTS
|
||||
|
||||
and learn how to quickly write npm TypeScript modules
|
||||
|
||||
## Step1: Install the tools
|
||||
|
||||
To use npmts install it using npm or yarn:
|
||||
|
||||
```sh
|
||||
npm install -g npmts # install with npm
|
||||
yarn global add npmts # install with yarn
|
||||
```
|
||||
|
||||
For the purpose of getting started quickly please also install **gitzone**.
|
||||
It'll proovide awesome scaffolding for new npmts maintained modules and also updates them later on.
|
||||
|
||||
```sh
|
||||
npm install -g gitzone # install with npm
|
||||
yarn global add gitzone # install with yarn
|
||||
```
|
||||
|
||||
You can make sure npmts and gitzone are installed correctly by typing `npmts -v && gitzone -v`.
|
||||
|
||||
## Scaffold a new module
|
||||
|
||||
To scaffold a new module type
|
||||
|
||||
```shell
|
||||
gitzone template npm
|
||||
```
|
||||
|
||||
This will run you through a series of question to get gitzone to know the specifics of your module.
|
||||
Enter all information accordingly.
|
||||
|
||||
## Run NPMTS for the first time
|
||||
@@ -1,52 +0,0 @@
|
||||
---
|
||||
name: Index
|
||||
description: best practice npm TypeScript modules
|
||||
---
|
||||
|
||||
# npmts
|
||||
|
||||
best practice npm TypeScript modules
|
||||
|
||||
## Availabililty
|
||||
|
||||
[](https://www.npmjs.com/package/npmts)
|
||||
[](https://GitLab.com/gitzone/npmts)
|
||||
[](https://github.com/gitzone/npmts)
|
||||
[](https://gitzone.gitlab.io/npmts/)
|
||||
|
||||
## Status for master
|
||||
|
||||
[](https://GitLab.com/gitzone/npmts/commits/master)
|
||||
[](https://GitLab.com/gitzone/npmts/commits/master)
|
||||
[](https://www.npmjs.com/package/npmts)
|
||||
[](https://david-dm.org/gitzonetools/npmts)
|
||||
[](https://www.bithound.io/github/gitzonetools/npmts/master/dependencies/npm)
|
||||
[](https://www.bithound.io/github/gitzonetools/npmts)
|
||||
[](https://nodejs.org/dist/latest-v6.x/docs/api/)
|
||||
[](https://nodejs.org/dist/latest-v6.x/docs/api/)
|
||||
[](http://standardjs.com/)
|
||||
|
||||
## Quick Demo
|
||||
|
||||
[](https://asciinema.org/a/9c3assmh21i49qhe5lmi48sze?speed=2&t=0)
|
||||
|
||||
## Usage
|
||||
|
||||
NPMTS is your friend when writing, testing, publishing and documenting npm modules written in TypeScript.
|
||||
|
||||
npmts will
|
||||
|
||||
1. check your dependencies and package.json (unused, missing, updates, security)
|
||||
1. transpile your code with tsc,
|
||||
1. test your code with tap (supports the fancy stuff like Promises, Generators, async/await, sourcemaps, parallel test execution in child processes)
|
||||
1. create coverage with istanbul (supports tracing of the originating TypeScript)
|
||||
|
||||
For more information on how tests are run check out the [tapbuffer module](https://www.npmjs.com/package/tapbuffer).
|
||||
|
||||
This works on your machine and in CI. There is a prebuild docker image available that includes npmts to make CI a breeze:
|
||||
[hosttoday/ht-docker-node:npmts on Dockerhub](https://hub.docker.com/r/hosttoday/ht-docker-node/)
|
||||
|
||||
> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh)
|
||||
> | By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy.html)
|
||||
|
||||
[](https:/git.zone)
|
||||
@@ -1,19 +0,0 @@
|
||||
# Install npmts
|
||||
|
||||
Get started with TypeScript awesomeness.
|
||||
|
||||
> \*_npmts-g_ checks if the global version of npmts suffices the modules requirements.
|
||||
> If not it installs npmts locally in the right version during npm install.
|
||||
|
||||
```sh
|
||||
npm install npmts -g # installs npmts globally
|
||||
npm install npmts-g --save-dev # installs npmts-g checking tool as devDependency
|
||||
```
|
||||
|
||||
Then add it to your package.json's script section to trigger a build:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"test": "(npmts)"
|
||||
}
|
||||
```
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
name: npmts project structure
|
||||
description: how npmts projects are structured
|
||||
---
|
||||
|
||||
# npmts - Project Structure
|
||||
|
||||
**locally**
|
||||
|
||||
```text
|
||||
projectroot
|
||||
|- .nogit/ # contains files that should not be checked into git - NOgit
|
||||
|- dist/ # contains compiled js files and their corresponding typings - git
|
||||
|- node_modules/ # contains the installed node modules - NOgit
|
||||
|- test/ # contains the test files - git
|
||||
|- ts/ # contains the source TypeScript files - git
|
||||
|
|
||||
|- .gitignore # the normal gitignore file
|
||||
|- .gitlab-ci.yml # the gitlab ci yml file
|
||||
|- npmextra.json # npmextra.json
|
||||
|- package.json # the standard npm module package.json file
|
||||
|- readme.md # the standard project readme
|
||||
|- tslint.json # the standard tslint.json for TypeScript
|
||||
|- yarn.lock # yarn.lock - the standard yarn.lock file
|
||||
```
|
||||
|
||||
**in git**
|
||||
Generated
-11399
File diff suppressed because it is too large
Load Diff
+10
-9
@@ -9,8 +9,8 @@
|
||||
"tscoverage": "cli.js"
|
||||
},
|
||||
"scripts": {
|
||||
"test": "(tstest test/)",
|
||||
"build": "(tsbuild)"
|
||||
"test": "tstest test/",
|
||||
"build": "tsbuild"
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
@@ -20,19 +20,19 @@
|
||||
"TypeScript",
|
||||
"Declaration"
|
||||
],
|
||||
"author": "Lossless GmbH",
|
||||
"author": "Task Venture Capital GmbH",
|
||||
"license": "MIT",
|
||||
"bugs": {
|
||||
"url": "https://gitlab.com/gitzone/npmts/issues"
|
||||
},
|
||||
"homepage": "https://gitlab.com/gitzone/npmts#readme",
|
||||
"devDependencies": {
|
||||
"@git.zone/tsbuild": "^4.3.0",
|
||||
"@git.zone/tsbundle": "^2.9.3",
|
||||
"@git.zone/tsrun": "^2.0.1",
|
||||
"@git.zone/tstest": "^3.5.1",
|
||||
"@git.zone/tswatch": "^3.3.1",
|
||||
"@types/node": "^25.5.0"
|
||||
"@git.zone/tsbuild": "^4.4.0",
|
||||
"@git.zone/tsbundle": "^2.10.1",
|
||||
"@git.zone/tsrun": "^2.0.3",
|
||||
"@git.zone/tstest": "^3.6.5",
|
||||
"@git.zone/tswatch": "^3.3.3",
|
||||
"@types/node": "^25.6.2"
|
||||
},
|
||||
"private": true,
|
||||
"files": [
|
||||
@@ -44,6 +44,7 @@
|
||||
"dist_ts_web/**/*",
|
||||
"assets/**/*",
|
||||
"cli.js",
|
||||
"license",
|
||||
".smartconfig.json",
|
||||
"readme.md"
|
||||
]
|
||||
|
||||
Generated
+2170
-2728
File diff suppressed because it is too large
Load Diff
@@ -1,63 +1,73 @@
|
||||
# @git.zone/tscoverage
|
||||
|
||||
A CLI tool for collecting and reporting test coverage information for TypeScript projects in the gitzone ecosystem.
|
||||
`@git.zone/tscoverage` is the TypeScript package scaffold for the `tscoverage` command in the `@git.zone` toolchain. The current implementation is intentionally minimal: the package entrypoint prints `tscoverage`, and the CLI wrapper loads the compiled entrypoint.
|
||||
|
||||
## Issue Reporting and Security
|
||||
|
||||
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
|
||||
|
||||
## 📦 Install
|
||||
## Current Behavior
|
||||
|
||||
Install globally for CLI usage:
|
||||
The source entrypoint lives in `ts/index.ts` and currently performs one action when imported or executed:
|
||||
|
||||
```bash
|
||||
pnpm install -g @git.zone/tscoverage
|
||||
```
|
||||
|
||||
Or as a dev dependency in your project:
|
||||
|
||||
```bash
|
||||
pnpm install --save-dev @git.zone/tscoverage
|
||||
```
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### CLI
|
||||
|
||||
Run `tscoverage` in your gitzone TypeScript project directory to execute tests and generate a coverage report:
|
||||
|
||||
```bash
|
||||
```text
|
||||
tscoverage
|
||||
```
|
||||
|
||||
This will run your project's test suite and produce a coverage report, giving you visibility into which parts of your codebase are exercised by tests.
|
||||
The production CLI entrypoint is `cli.js`. It imports `dist_ts/index.js` and calls an exported `runCli()` function if one is added in the future. Because no `runCli()` export exists today, the CLI currently relies on the entrypoint side effect.
|
||||
|
||||
### Programmatic
|
||||
## Usage
|
||||
|
||||
You can also import `tscoverage` in your own scripts:
|
||||
|
||||
```typescript
|
||||
import * as tscoverage from '@git.zone/tscoverage';
|
||||
```
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
This project uses the standard `@git.zone` toolchain:
|
||||
Build before using the production CLI wrapper:
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Build the project
|
||||
pnpm run build
|
||||
node cli.js
|
||||
```
|
||||
|
||||
# Run tests
|
||||
For development against the TypeScript source wrapper:
|
||||
|
||||
```bash
|
||||
node cli.ts.js
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
Install dependencies with pnpm:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
Build the package:
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
Run the test suite:
|
||||
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
The project uses the current `@git.zone` TypeScript toolchain:
|
||||
|
||||
- `@git.zone/tsbuild` compiles `ts/**/*.ts` to `dist_ts/`.
|
||||
- `@git.zone/tstest` runs tests from `test/`.
|
||||
- `@git.zone/tsrun`, `@git.zone/tsbundle`, and `@git.zone/tswatch` are available as development tooling dependencies.
|
||||
|
||||
## Project Layout
|
||||
|
||||
- `ts/` contains the TypeScript source.
|
||||
- `dist_ts/` contains generated build output.
|
||||
- `test/` contains the tstest-based test suite.
|
||||
- `cli.js` is the production CLI wrapper.
|
||||
- `cli.ts.js` is the TypeScript-source CLI wrapper for development.
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license.md](./license.md) file.
|
||||
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
|
||||
|
||||
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
||||
|
||||
|
||||
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@git.zone/tscoverage',
|
||||
version: '10.0.0',
|
||||
version: '10.0.1',
|
||||
description: 'get coverage information for gitzone projects'
|
||||
}
|
||||
|
||||
+1
-2
@@ -1,7 +1,6 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"esModuleInterop": true,
|
||||
"baseUrl": "."
|
||||
"esModuleInterop": true
|
||||
},
|
||||
"exclude": [
|
||||
"node_modules",
|
||||
|
||||
Reference in New Issue
Block a user