fix(docs): refresh package documentation and align metadata with current project layout

This commit is contained in:
2026-05-09 12:33:38 +00:00
parent 5f87fd3eae
commit b31ea2ab4f
17 changed files with 2238 additions and 14458 deletions
+8
View File
@@ -1,5 +1,13 @@
# Changelog # 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) ## 2026-03-24 - 10.0.0 - BREAKING CHANGE(package)
migrate package to the @git.zone scope and ESM-based tooling migrate package to the @git.zone scope and ESM-based tooling
-9
View File
@@ -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>
///
-10
View File
@@ -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
```
-88
View File
@@ -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.
-13
View File
@@ -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.
-23
View File
@@ -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.
-40
View File
@@ -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
-52
View File
@@ -1,52 +0,0 @@
---
name: Index
description: best practice npm TypeScript modules
---
# npmts
best practice npm TypeScript modules
## Availabililty
[![npm](https://gitzone.gitlab.io/assets/repo-button-npm.svg)](https://www.npmjs.com/package/npmts)
[![git](https://gitzone.gitlab.io/assets/repo-button-git.svg)](https://GitLab.com/gitzone/npmts)
[![git](https://gitzone.gitlab.io/assets/repo-button-mirror.svg)](https://github.com/gitzone/npmts)
[![docs](https://gitzone.gitlab.io/assets/repo-button-docs.svg)](https://gitzone.gitlab.io/npmts/)
## Status for master
[![build status](https://GitLab.com/gitzone/npmts/badges/master/build.svg)](https://GitLab.com/gitzone/npmts/commits/master)
[![coverage report](https://GitLab.com/gitzone/npmts/badges/master/coverage.svg)](https://GitLab.com/gitzone/npmts/commits/master)
[![npm downloads per month](https://img.shields.io/npm/dm/npmts.svg)](https://www.npmjs.com/package/npmts)
[![Dependency Status](https://david-dm.org/gitzonetools/npmts.svg)](https://david-dm.org/gitzonetools/npmts)
[![bitHound Dependencies](https://www.bithound.io/github/gitzonetools/npmts/badges/dependencies.svg)](https://www.bithound.io/github/gitzonetools/npmts/master/dependencies/npm)
[![bitHound Code](https://www.bithound.io/github/gitzonetools/npmts/badges/code.svg)](https://www.bithound.io/github/gitzonetools/npmts)
[![TypeScript](https://img.shields.io/badge/TypeScript-2.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/)
[![node](https://img.shields.io/badge/node->=%206.x.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/)
[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)
## Quick Demo
[![asciicast](https://asciinema.org/a/9c3assmh21i49qhe5lmi48sze.png)](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 | **&copy;** [Lossless GmbH](https://lossless.gmbh)
> | By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy.html)
[![repo-footer](https://gitzone.gitlab.io/assets/repo-footer.svg)](https:/git.zone)
-19
View File
@@ -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)"
}
```
-27
View File
@@ -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**
View File
-11399
View File
File diff suppressed because it is too large Load Diff
+10 -9
View File
@@ -9,8 +9,8 @@
"tscoverage": "cli.js" "tscoverage": "cli.js"
}, },
"scripts": { "scripts": {
"test": "(tstest test/)", "test": "tstest test/",
"build": "(tsbuild)" "build": "tsbuild"
}, },
"repository": { "repository": {
"type": "git", "type": "git",
@@ -20,19 +20,19 @@
"TypeScript", "TypeScript",
"Declaration" "Declaration"
], ],
"author": "Lossless GmbH", "author": "Task Venture Capital GmbH",
"license": "MIT", "license": "MIT",
"bugs": { "bugs": {
"url": "https://gitlab.com/gitzone/npmts/issues" "url": "https://gitlab.com/gitzone/npmts/issues"
}, },
"homepage": "https://gitlab.com/gitzone/npmts#readme", "homepage": "https://gitlab.com/gitzone/npmts#readme",
"devDependencies": { "devDependencies": {
"@git.zone/tsbuild": "^4.3.0", "@git.zone/tsbuild": "^4.4.0",
"@git.zone/tsbundle": "^2.9.3", "@git.zone/tsbundle": "^2.10.1",
"@git.zone/tsrun": "^2.0.1", "@git.zone/tsrun": "^2.0.3",
"@git.zone/tstest": "^3.5.1", "@git.zone/tstest": "^3.6.5",
"@git.zone/tswatch": "^3.3.1", "@git.zone/tswatch": "^3.3.3",
"@types/node": "^25.5.0" "@types/node": "^25.6.2"
}, },
"private": true, "private": true,
"files": [ "files": [
@@ -44,6 +44,7 @@
"dist_ts_web/**/*", "dist_ts_web/**/*",
"assets/**/*", "assets/**/*",
"cli.js", "cli.js",
"license",
".smartconfig.json", ".smartconfig.json",
"readme.md" "readme.md"
] ]
+2170 -2728
View File
File diff suppressed because it is too large Load Diff
+48 -38
View File
@@ -1,63 +1,73 @@
# @git.zone/tscoverage # @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 ## 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. 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 ```text
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
tscoverage 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: Build before using the production CLI wrapper:
```typescript
import * as tscoverage from '@git.zone/tscoverage';
```
## 🛠️ Development
This project uses the standard `@git.zone` toolchain:
```bash ```bash
# Install dependencies
pnpm install
# Build the project
pnpm run build 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 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 ## 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. **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.
@@ -69,7 +79,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
### Company Information ### Company Information
Task Venture Capital GmbH Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or further information, please contact us via email at hello@task.vc. For any legal inquiries or further information, please contact us via email at hello@task.vc.
+1 -1
View File
@@ -3,6 +3,6 @@
*/ */
export const commitinfo = { export const commitinfo = {
name: '@git.zone/tscoverage', name: '@git.zone/tscoverage',
version: '10.0.0', version: '10.0.1',
description: 'get coverage information for gitzone projects' description: 'get coverage information for gitzone projects'
} }
+1 -2
View File
@@ -1,7 +1,6 @@
{ {
"compilerOptions": { "compilerOptions": {
"esModuleInterop": true, "esModuleInterop": true
"baseUrl": "."
}, },
"exclude": [ "exclude": [
"node_modules", "node_modules",