Alexandro.Net

Download README · GitHub release

@stackline/cardinal

Compatible JavaScript and JSON terminal highlighting with reliable streams, themes, ESM, and types.

npm version license GitHub repository Docs Reddit community

Documentation | npm | Issues | Repository

Current package version: 1.0.4

Why this package?

Compatible JavaScript and JSON syntax highlighting for terminals, with reliable streams, named themes, ESM, browser bundles, and first-party types.

This package is an independent, maintained continuation of cardinal. It preserves the established 2.1.1 library and cdl behavior while fixing an empty-input hang, making theme selection consistent, buffering piped input by logical line, and adding current module and type contracts.

Provenance

The upstream history and preserved boundary are recorded in UPSTREAM_AUDIT.md, COMPATIBILITY_CONTRACT.md, and NOTICE. Stackline is not affiliated with or endorsed by the upstream author.

Compatibility

Item Value
Package @stackline/cardinal@1.0.4
Node.js runtime >=12
CommonJS / primary entry ./cardinal.js
ES module entry ./index.mjs
Type declarations ./index.d.ts

Compatibility Evidence

The maintained suite includes all upstream assertions, 700 differential executions against cardinal@2.1.1, empty-input and six-digit numbering edges, named and path themes, adversarial stream chunking, modern parser adapters, CLI, CJS/ESM, browser, types, packed installs, audits, and package-quality checks.

Current downstream contracts were verified in Netlify Build, Contentful Migration, Refine CLI, tapjs/treport, and American Express json-parse-context before implementation.

The historical dependency keys remain intact. ansicolors resolves exactly to @stackline/ansicolors@1.0.1; redeyed resolves exactly to @stackline/redeyed@1.0.2, which in turn resolves its parser to the dependency-free @stackline/esprima@1.0.0. Clean direct and alias installs report no warnings and zero audit findings across the complete runtime chain.

Installation

Install

npm install @stackline/cardinal

Keep existing require('cardinal') or import cardinal from 'cardinal' calls:

npm install cardinal@npm:@stackline/cardinal

Usage

Quick Start

const cardinal = require('@stackline/cardinal')

console.log(cardinal.highlight('const answer = 42'))

Line numbers and a built-in theme can be selected together:

const output = cardinal.highlight(source, {
  linenos: true,
  firstline: 20,
  theme: 'tomorrow-night',
  jsx: true
})

Theme objects remain fully compatible. Theme names, absolute paths, and paths relative to the current working directory are also accepted in Node.js.

Features and Integrations

Current Syntax

Esprima remains the default so existing token labels and ANSI output do not change silently. Applications that already use a newer parser can opt in:

npm install espree

const espree = require('espree')
const cardinal = require('@stackline/cardinal')

const output = cardinal.highlight('class Box { #value = 1_000n }', {
  parser: espree,
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module'
  }
})

Parser-specific token labels remain parser-specific.

Command Line

The package exposes the historical cdl command:

cdl source.js
cat source.js | cdl

cdl source.js --nonum disables line numbers configured in ~/.cardinalrc. Piped input is buffered by complete logical line, so stream chunk boundaries never insert or duplicate source text.

Example ~/.cardinalrc:

{
  "theme": "hide-semicolons",
  "linenos": true
}

Modules, Types, And Browser

File APIs intentionally throw a clear error in browsers. The browser build supports built-in names and object themes; filesystem theme paths remain a Node.js feature.

Security

Report vulnerabilities privately as described in SECURITY.md. The empty-input fix is a reliability correction; this project does not claim a CVE or GHSA that has not been assigned.

API Surface

API

highlight(code[, options])

Returns ANSI-highlighted source. The default tokenizer and colors match cardinal@2.1.1.

Option Default Purpose
theme default Theme object, built-in name, or Node.js theme path
linenos false Prefix output with line numbers
firstline 1 Number assigned to the first output line
jsx false Enable the historical JSX parser path
parser Esprima 4 Opt in to a compatible tokenizer or parser
parserOptions {} Pass settings to a custom parser

highlightFileSync(fullPath[, options])

Reads a UTF-8 file and returns its highlighted source.

highlightFile(fullPath[, options], callback)

Reads asynchronously and calls callback(error, highlighted). As in the historical runtime, the function itself returns undefined.

Local Development

git clone https://github.com/alexandroit/stackline-cardinal.git
cd stackline-cardinal
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

MIT. The original Cardinal copyright and permission notice remain in LICENSE. Runtime and bundled dependency notices are reproduced in THIRD_PARTY_LICENSES.md.

Credits and original authors

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.