Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (76 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

109 lines (76 loc) · 3.5 KB
Raw

Contributing to console-toolkit

Prerequisites

  • Node.js 22 or later
  • npm

Setup

git clone --recursive https://github.com/uhop/console-toolkit
cd console-toolkit
npm install

The --recursive flag is needed to clone the wiki submodule under wiki/.

Project structure

See ARCHITECTURE.md for a detailed module map and dependency graph.

  • src/ — all source code (shipped to npm)
  • tests/ — automated tests (test-*.js) and manual visual tests (manual/)
  • scripts/ — example/demo scripts
  • wiki/ — GitHub wiki (git submodule)

Development workflow

Running tests

npm test                                        # Run all automated tests
node tests/test-<name>.js                       # Run a single test file directly
npm test -- test-foo.js test-bar.js             # Run selected files (workers)
npm run test:seq -- test-foo.js test-bar.js     # Run selected files (sequential)
npm run test:proc -- test-foo.js test-bar.js    # Run selected files (subprocesses)
npm run test:bun                                # Run with Bun
npm run test:deno                               # Run with Deno

Type checking

npm run ts-check        # tsc --noEmit

Linting and formatting

npm run lint            # Check formatting (Prettier)
npm run lint:fix        # Auto-format

Manual/visual tests

node tests/manual/test-<name>.js

Coding conventions

General

  • ESM-only: use import/export with .js extensions in all import paths.
  • No build step: source JS is shipped directly.
  • No runtime dependencies: do not add any.
  • Formatting: Prettier — 120 char width, single quotes, no bracket spacing, no trailing commas.
  • Indentation: 2 spaces.

Documentation

  • Every public .js module has a hand-written .d.ts file alongside it.
  • .d.ts files are NOT generated — edit them manually.
  • No JSDoc in .js files — the .d.ts sidecar is the sole source of types and docs.
  • Each .js carries // @ts-self-types="./<file>.d.ts" at the top so IDE hover defers to the .d.ts.
  • When changing a public API, always update both the .js and its .d.ts.

Patterns

  • Box is immutable — methods return new Box instances.
  • Panel is mutable — methods mutate this and return this for chaining.
  • Method aliases are created via addAlias/addAliases from meta.js.
  • pad(t, r, b, l) follows CSS shorthand order on both Box and Panel.

Adding new features

New public function in an existing module

  1. Add implementation to src/<module>.js (types go in the .d.ts, not JSDoc).
  2. Add type signature to src/<module>.d.ts with matching JSDoc.
  3. Add tests to tests/test-<module>.js.
  4. Run npm test and npm run ts-check.

New theme

  1. Create src/themes/<category>/<name>.js exporting the theme object.
  2. Create matching .d.ts with JSDoc.
  3. Optionally add a visual test in tests/manual/.

New module or sub-package

  1. Create src/<name>.js and src/<name>.d.ts.
  2. If it's a sub-package, create src/<name>/index.js and src/<name>/index.d.ts.
  3. Add an export entry in package.json "exports" if it should be a named entry point.
  4. Add tests and update documentation.

License

By contributing, you agree that your contributions will be licensed under the project's BSD-3-Clause license. No external contributions are accepted under licenses fundamentally incompatible with the BSD-3-Clause license this library is distributed under.