Skip to content
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,8 @@ The division of responsibility:
- **Runtime**: Node.js stdlib plus one runtime dependency:
`typescript` (the compiler package, consumed at runtime via
`typescript/unstable/sync`; moved from devDependencies to
dependencies — v0.1.0 shipped with zero runtime deps)
dependencies — the unpublished v0.1.0 scaffold had zero
runtime deps; v0.2.0 is the first npm release)
- **Project management**: npm
- **Testing**: [vitest](https://vitest.dev/) with
`@vitest/coverage-v8`
Expand Down
53 changes: 53 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[LOW] The 0.2.0 changelog entry omits a Spec: traceability line. The entry cites issues #2–#6 but never points at openspec/changes/release-v0-2-0/, so release → spec linkage rests on the PR body alone. A line such as Spec: openspec/changes/release-v0-2-0/ under the entry restores the audit path. Advisory only — the entry's content itself is accurate.

## [0.2.0] - unreleased

First npm release. Implements the complete
[Gaze analyzer protocol](https://github.com/unbound-force/gaze) v1.2.0
for TypeScript and JavaScript projects.

### Added

- JSON-RPC 2.0 server over stdin/stdout (`reading-stone --stdio`).
- `initialize` / `shutdown` lifecycle; capabilities `discover`,
`test_mapping`, `classify_signals`, `doc_coverage`, and
`cognitive_complexity` advertised `true`, `streaming` `false`.
- `discover`: source/test file classification and test-framework
detection (#2).
- `analyze`: side-effect detection across the 48-type Gaze taxonomy,
with every effect classified by a deterministic signal pipeline (#3, #4).
- `complexity`: cyclomatic complexity per function (#3).
- `coverage`: per-function statement coverage read from an existing
Istanbul `coverage/coverage-final.json` (never runs tests) (#3).
- `classify_signals`: the raw classification signal feed — `interface`,
`visibility`, `caller_count`, `naming_convention`, `docstring`, and
synthesized `contradiction` signals (#4).
- `test_mapping`: vitest/jest and `node:assert` test-to-assertion
mapping with pairing confidences and side-effect inference (#5).
`assertion_type` uses Gaze's assertion-type set (`equality`,
`error_check`, `nil_check`, `diff_check`, `custom`), never empty (#28).
- `doc_coverage`: documentation coverage over the exported symbol
surface (#6).
- `cognitive_complexity`: SonarSource cognitive complexity per
function (#6).
- `gaze-analyzer-typescript` bin alias for Gaze's zero-config PATH
discovery (`gaze ... --language typescript`).
- Program mode via the project's `tsconfig.json` (type-checker-backed
signals and pairing), with a parse-only fallback when none is usable.

### Notes

- Runtime dependency `typescript` is pinned exactly at `7.0.2`
(`typescript/unstable/*` API).
- The package `exports` map exposes only the root barrel and
`./package.json`; deep imports of `dist/*` are unsupported.

[Unreleased]: https://github.com/zero-dot-force/reading-stone/compare/v0.2.0...HEAD
[0.2.0]: https://github.com/zero-dot-force/reading-stone/releases/tag/v0.2.0
20 changes: 13 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Reading Stone is a Gaze-spawned subprocess. It speaks JSON-RPC 2.0 over stdin/stdout
(protocol v1.2.0). Gaze owns the CLI, scoring, and reports.

## Current status (v0.1.0)
## Current status (v0.2.0)

| Method | Status |
|--------|--------|
Expand Down Expand Up @@ -86,6 +86,18 @@ reports.

Requires Node.js 22+.

### From npm

```bash
npm i -g reading-stone
```

The package's only runtime dependency is `typescript`, pinned exactly
(currently `7.0.2`): Reading Stone uses the compiler's
`typescript/unstable/*` API, which carries no semver stability
guarantee, so the pin moves only in a Reading Stone release. It is
independent of the TypeScript version the analyzed project uses.

### From a clone (local development)

```bash
Expand All @@ -103,12 +115,6 @@ analyzer over stdin/stdout:

## Configuration

Install the package globally:

```bash
npm i -g reading-stone
```

Gaze auto-discovers external analyzers by PATH naming convention:
run gaze with `--language typescript` (e.g.
`gaze quality --language typescript ./src`) and any
Expand Down
3 changes: 3 additions & 0 deletions openspec/changes/release-v0-2-0/.openspec.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
schema: spec-driven
created: 2026-11-19
x-originating-issue: 7
38 changes: 38 additions & 0 deletions openspec/changes/release-v0-2-0/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Design

## Context

v0.2.0 is reading-stone's first npm publication. The code is feature-complete for protocol v1.2.0; this change is packaging, versioning, and release verification only. See `proposal.md` — Why.

## Goals / Non-Goals

**Goals:**

- A publishable v0.2.0 tarball that carries `NOTICE`, no dangling source maps, and complete registry metadata.
- One end-to-end test proving the built artifact Gaze spawns serves the whole lifecycle in a single session.
- Spec and docs that match what ships.

**Non-Goals:**

- Publishing (a maintainer runs `npm publish` from a clean `main`).
- CI release automation — added after npm trusted publishing is configured, so the v0.2.0 tag push does not race a manual publish.
- Any runtime or protocol change.

## Decisions

1. **Exclude source maps via `files` negation, not `tsconfig`.** `"!dist/**/*.map"` keeps local debugging maps intact while the tarball stays free of maps pointing at unshipped `src/`. Alternative — shipping `src/` alongside — rejected: doubles the payload for a subprocess users never debug into.

2. **List `NOTICE` in `files` explicitly.** npm auto-includes `README` and `LICENSE` but not `NOTICE`; Apache-2.0 §4(d) requires redistributions to carry it. The tarball-contents test pins it so a future `files` edit cannot silently drop it.

3. **Tarball test uses `npm pack --dry-run --json`.** It reads exactly the list npm would publish (honoring `files`, negations, and auto-includes) without writing a tarball. It needs `dist/` built, so it rides the existing `describe.skipIf(!existsSync(mainJs))` subprocess guard like the other built-artifact tests.

4. **`exports` map with `"."` and `"./package.json"`.** Declares the public surface as the `src/index.ts` barrel (convention pack AP-001). Bins are unaffected (they resolve by path, not through `exports`). Deep imports of `dist/*` become unsupported — acceptable at 0.x before any consumer exists.

5. **Lifecycle fixture is minimal but non-vacuous.** One source module with a side effect, a documented export, and a branch; one vitest test file asserting on it; a `tsconfig.json` so program mode (checker-dependent signals) is exercised; and a hand-authored `coverage/coverage-final.json` so `coverage` returns rows. Every analysis method must return at least one row, so a regression that empties any method fails loudly.

6. **Archive `align-protocol-v1-2-0` with `--skip-specs`.** Its deltas were pre-synced into the main specs at merge, and 005 later flipped the capability scenarios; validating its MODIFIED block against today's spec fails by design. Skipping the spec sync archives the record without regressing main specs.

## Risks / Trade-offs

- **`exports` restricts deep imports** → no known consumers; documented in CHANGELOG.
- **Lifecycle test runtime** (each method boots a fresh compiler context) → fixture kept to two files; test timeout 120 s.
52 changes: 52 additions & 0 deletions openspec/changes/release-v0-2-0/proposal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Proposal

## Why

All eight analysis methods of Gaze analyzer protocol v1.2.0 have landed (#2–#6) and the `gaze-analyzer-typescript` bin alias has merged, but the package still reports version `0.1.0` and has never been published. Issue #7 tracks the v0.2.0 release: the first npm publication of `reading-stone`. A release-readiness audit also found packaging defects that must be fixed before the first publish:

- The npm tarball omits `NOTICE`. `files` lists only `dist`, and npm does not auto-include `NOTICE`, so the published package would distribute snake-eyes-derived code without the attribution Apache License 2.0 §4(d) requires.
- The tarball ships 34 `dist/**/*.map` source maps whose `sources` point at `../src/*.ts`, which is not shipped — dead weight that resolves to nothing.
- `package.json` lacks `homepage`, `bugs`, `keywords`, and an `exports` map.
- No end-to-end test drives the built server through the full protocol lifecycle in one session; the subprocess suite covers `initialize`/`shutdown`, `doc_coverage`, and `cognitive_complexity` only.
- The `cli` main spec has drifted: it still pins version `0.1.0`, a single bin, and a `^7.0.2` caret range, while the code ships two bins and an exact `7.0.2` pin (review dispatch 44e85014).
- The completed `align-protocol-v1-2-0` change was never archived.

## What Changes

- Version `0.1.0` → `0.2.0`: `package.json`, `package-lock.json`, `VERSION` in `src/index.ts`, the README status heading, and the `tests/cli.test.ts` metadata pins.
- `package.json` packaging: `files` becomes `["dist", "!dist/**/*.map", "NOTICE"]`; add `homepage`, `bugs`, `keywords`, and an `exports` map (`"."` → `dist/index.js` with types, plus `./package.json`).
- A tarball-contents test pins the shipped file set (via `npm pack --dry-run --json`): `NOTICE`, `LICENSE`, `README.md`, `package.json`, and `dist/` with no `.map` files.
- A full-lifecycle stdio smoke test against `dist/main.js`: `initialize` → `discover` → `analyze` → `complexity` → `coverage` → `test_mapping` → `classify_signals` → `doc_coverage` → `cognitive_complexity` → `shutdown` in one session over a fixture project, asserting every response is a success with the method's single result key and a non-empty row array, and that the process exits 0.
- `CHANGELOG.md` (Keep a Changelog format) with the v0.2.0 entry.
- README: v0.2.0 status heading, npm-install path promoted, note on the exact `typescript` pin.
- AGENTS.md: correct "v0.1.0 shipped" (v0.1.0 was never published).
- Archive `align-protocol-v1-2-0` with `--skip-specs`: its main-spec text was materialized at merge time and since advanced by 005, so re-applying its deltas would regress the capability scenario.

Out of scope: the publish itself (manual `npm publish` by a maintainer), a release workflow (follow-up after npm trusted publishing is configured), and the blog post (#19).

## Capabilities

### New Capabilities

None.

### Modified Capabilities

- `cli`: the `Package scaffold and entry point` requirement moves to version `0.2.0`, both bin names, the exact `typescript` `7.0.2` pin, and the `exports` map; a new `Published package contents` requirement pins the tarball file set (NOTICE included, source maps excluded).

## Impact

- `package.json`, `package-lock.json`, `src/index.ts` (`VERSION` only).
- `tests/cli.test.ts` — version pins, tarball-contents test, full-lifecycle smoke test.
- `README.md`, `AGENTS.md`, new `CHANGELOG.md`.
- `openspec/specs/cli/spec.md` via this change's delta; `openspec/changes/align-protocol-v1-2-0/` → `openspec/changes/archive/`.
- No runtime behavior change: no change to `server.ts`, `main.ts`, protocol, or any analysis module. No dependency changes.
- Gaze protocol contract: unchanged (v1.2.0); the `initialize` handshake does not report the package version, so its bytes are identical.

## Constitution Alignment

- **I. Protocol Fidelity — PASS**: no protocol change; the new lifecycle test asserts the built server answers every v1.2.0 method in sequence.
- **II. Detection Accuracy — N/A**: no detection code changes.
- **III. TypeScript-Native Analysis — N/A**: no analysis code changes.
- **IV. Testability — PASS**: coverage strategy — the lifecycle smoke test and tarball-contents test extend `tests/cli.test.ts`; both run in CI after `npm run build`; the 85% gate is unchanged.
- **V. Analysis Safety — PASS**: no new dependencies; the lifecycle fixture is static source plus a hand-authored Istanbul document, never executed.
35 changes: 35 additions & 0 deletions openspec/changes/release-v0-2-0/specs/cli/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Spec Delta

## MODIFIED Requirements

### Requirement: Package scaffold and entry point

> Previously: version `0.1.0`, a single `reading-stone` bin, and `typescript` at `^7.0.2`.

The system SHALL provide a `reading-stone` package installable via `npm ci`, with `package.json` declaring name `reading-stone`, version `0.2.0`, `type: module`, `engines.node >=22`, license `Apache-2.0`, two `bin` entries — `reading-stone` and `gaze-analyzer-typescript` (Gaze's tier-3 PATH discovery name) — both pointing to `dist/main.js`, an `exports` map exposing `"."` (types `dist/index.d.ts`, default `dist/index.js`) and `"./package.json"`, and exactly one runtime dependency: `typescript` pinned exactly at `7.0.2` (the runtime consumes the `typescript/unstable/*` surface, which carries no semver stability guarantee). `src/index.ts` SHALL expose `export const VERSION = "0.2.0"`.

#### Scenario: Package metadata is correct

- **WHEN** `package.json` is inspected
- **THEN** name is `reading-stone`, version is `0.2.0`, `type` is `module`, `engines.node` is `>=22`, license is `Apache-2.0`, `bin` is exactly `{ "reading-stone": "dist/main.js", "gaze-analyzer-typescript": "dist/main.js" }`, and `dependencies` is exactly `{ "typescript": "7.0.2" }`

#### Scenario: Version constant is exposed

- **WHEN** the package entry is imported
- **THEN** `VERSION` equals `"0.2.0"`

## ADDED Requirements

### Requirement: Published package contents

The published tarball SHALL contain `package.json`, `README.md`, `LICENSE`, `NOTICE`, and the compiled `dist/` JavaScript and declaration files, and SHALL NOT contain source maps (`*.map`), `src/`, or `tests/`.

#### Scenario: NOTICE ships with the package

- **WHEN** `npm pack --dry-run --json` lists the tarball contents
- **THEN** the list includes `NOTICE`, `LICENSE`, `README.md`, `package.json`, `dist/main.js`, and `dist/index.d.ts`

#### Scenario: No dangling source maps ship

- **WHEN** `npm pack --dry-run --json` lists the tarball contents
- **THEN** no path ends in `.map` and no path starts with `src/` or `tests/`
24 changes: 24 additions & 0 deletions openspec/changes/release-v0-2-0/tasks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Tasks

## 1. Versioning

- [x] 1.1 Bump version to `0.2.0` in `package.json`/`package-lock.json` (`npm version 0.2.0 --no-git-tag-version`) and `VERSION` in `src/index.ts`; update the `tests/cli.test.ts` version pins

## 2. Packaging

- [x] 2.1 `package.json`: `files` → `["dist", "!dist/**/*.map", "NOTICE"]`; add `homepage`, `bugs`, `keywords`, and the `exports` map; extend the package-metadata test to pin them
- [x] 2.2 Add a tarball-contents test (`npm pack --dry-run --json`) pinning NOTICE/LICENSE/README/package.json present and no `.map` files

## 3. End-to-end conformance

- [x] 3.1 Add the full-lifecycle stdio smoke test against `dist/main.js` (all 10 methods, one session, non-empty rows per analysis method, exit 0)

## 4. Documentation

- [x] 4.1 Add `CHANGELOG.md` with the v0.2.0 entry
- [x] 4.2 README: v0.2.0 status heading, npm install path, exact `typescript` pin note; AGENTS.md: correct the "v0.1.0 shipped" claim

## 5. OpenSpec hygiene and gates

- [x] 5.1 Archive `align-protocol-v1-2-0` with `--skip-specs`
- [x] 5.2 Run the CI parity gates — `npx biome check src/ tests/`, `npm run build`, `npx vitest run --coverage` — all pass at ≥85%
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

27 changes: 25 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,28 @@
{
"name": "reading-stone",
"version": "0.1.0",
"version": "0.2.0",
"description": "TypeScript side-effect analyzer backend for Gaze",
"keywords": [
"gaze",
"typescript",
"javascript",
"static-analysis",
"side-effects",
"json-rpc",
"analyzer",
"test-quality"
],
"type": "module",
"license": "Apache-2.0",
"author": "zero-dot-force",
"repository": {
"type": "git",
"url": "git+https://github.com/zero-dot-force/reading-stone.git"
},
"homepage": "https://github.com/zero-dot-force/reading-stone#readme",
"bugs": {
"url": "https://github.com/zero-dot-force/reading-stone/issues"
},
"engines": {
"node": ">=22"
},
Expand All @@ -18,8 +32,17 @@
},
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
"./package.json": "./package.json"
},
"files": [
"dist"
"dist",
"!dist/**/*.map",
"NOTICE"
],
"scripts": {
"build": "tsc",
Expand Down
2 changes: 1 addition & 1 deletion src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
* compile-time types stays explicit.
*/

export const VERSION = "0.1.0";
export const VERSION = "0.2.0";

export type {
PatternSet,
Expand Down
Loading