@binary-balance/seshat 0.1.0-rc.1 → 0.1.0

package/README.md

@@ -1,8 +1,129 @@
 # Seshat
 
-This package installs the Seshat command and selects the native payload for
-the current Node platform. The native payload packages are optional so npm can
-skip the four platforms that do not match the consumer.
+Seshat is a native CLI for TypeScript and TSX complexity analysis and mutation
+testing. `check` runs both assessments, `crap` runs complexity and coverage
+analysis, and `mutate` runs mutation testing from the original test baseline.
 
-Seshat needs Node 24.20.0. Run `seshat check`, `seshat crap`, or `seshat mutate`
-with a project `seshat.json`. Add `--json` for the versioned report.
+## Install
+
+Install the entry package in the project you want to assess:
+
+```sh
+npm install --save-dev @binary-balance/seshat
+```
+
+The package declares and verifies Node.js 24.20.0 exactly. It selects one
+native payload for the current platform from these five verified targets:
+
+- Linux x64 (glibc; Debian 11 userspace, glibc 2.31)
+- Linux ARM64 (glibc; Ubuntu 22.04, glibc 2.35)
+- macOS x64 (macOS 15.0 minimum)
+- macOS ARM64 (macOS 15.0 minimum)
+- Windows x64 (Windows Server 2022 verification)
+
+These are the known verification floors; see the [native platform support
+matrix](https://github.com/Binary-Balance/seshat/blob/main/docs/platform-support.md)
+for the detailed target evidence.
+
+## Minimal mutation example
+
+For a small Node test setup, install TypeScript in the project first:
+
+```sh
+npm install --save-dev typescript
+```
+
+Create `src/rules.mts`:
+
+```ts
+export function classify(value: number): 'positive' | 'negative' {
+  return value >= 0 ? 'positive' : 'negative';
+}
+```
+
+Create `tests/rules.test.mjs`:
+
+```js
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import {classify} from '../src/rules.mts';
+
+test('classifies zero and positive values', () => {
+  assert.equal(classify(0), 'positive');
+  assert.equal(classify(1), 'positive');
+});
+```
+
+Create `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.mts"]
+}
+```
+
+Create `seshat.json`:
+
+```json
+{
+  "source": {"include": ["src/**/*.mts"]},
+  "capture": [
+    "package.json",
+    "package-lock.json",
+    "tsconfig.json",
+    "src",
+    "tests",
+    "node_modules"
+  ],
+  "setups": [{
+    "name": "node",
+    "runner": "node",
+    "cwd": ".",
+    "typecheck": [
+      "node",
+      "node_modules/typescript/bin/tsc",
+      "--project",
+      "tsconfig.json"
+    ],
+    "test": [
+      "node",
+      "--test",
+      "--test-concurrency=1",
+      "--test-reporter={seshatReporter}",
+      "tests/rules.test.mjs"
+    ],
+    "coverage": {
+      "command": ["node", "-e", "process.exit(0)"],
+      "report": "coverage/unused.json"
+    }
+  }]
+}
+```
+
+Run mutation testing and save its JSON report:
+
+```sh
+./node_modules/.bin/seshat mutate --config ./seshat.json \
+  --json --no-progress > seshat-report.json
+```
+
+The `coverage` block is required by the configuration schema but is not run by
+`mutate`; the no-op command above keeps this example dependency-light. `check`
+and `crap` do run coverage and need a command that writes a fresh Istanbul JSON
+report. Use the complete [Node example](https://github.com/Binary-Balance/seshat/tree/main/examples/node),
+[Vitest example](https://github.com/Binary-Balance/seshat/tree/main/examples/vitest),
+or [Jest/Expo example](https://github.com/Binary-Balance/seshat/tree/main/examples/jest-expo)
+for those commands.
+
+See the [full configuration guide](https://github.com/Binary-Balance/seshat/blob/main/docs/configuration.md)
+for all fields and runner setup, and the [JSON report format](https://github.com/Binary-Balance/seshat/blob/main/docs/report-format.md)
+for the `--json` output contract.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@binary-balance/seshat",
-  "version": "0.1.0-rc.1",
-  "description": "Native TypeScript code assurance",
+  "version": "0.1.0",
+  "description": "A native CLI for TypeScript and TSX complexity analysis and mutation testing.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Binary-Balance/seshat.git"
+  },
   "type": "module",
   "engines": {
     "node": "24.20.0"
@@ -16,10 +20,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@binary-balance/seshat-linux-x64": "0.1.0-rc.1",
-    "@binary-balance/seshat-linux-arm64": "0.1.0-rc.1",
-    "@binary-balance/seshat-darwin-x64": "0.1.0-rc.1",
-    "@binary-balance/seshat-darwin-arm64": "0.1.0-rc.1",
-    "@binary-balance/seshat-win32-x64": "0.1.0-rc.1"
+    "@binary-balance/seshat-linux-x64": "0.1.0",
+    "@binary-balance/seshat-linux-arm64": "0.1.0",
+    "@binary-balance/seshat-darwin-x64": "0.1.0",
+    "@binary-balance/seshat-darwin-arm64": "0.1.0",
+    "@binary-balance/seshat-win32-x64": "0.1.0"
   }
 }