From 0985465b358feb9024bcad15c741c5c937633507 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Thu, 19 Nov 2026 13:38:38 -0500 Subject: [PATCH 1/8] spec: add release-v0-2-0 OpenSpec change (#7) Proposal, design, tasks, and cli spec delta for the v0.2.0 release: version bump, NOTICE in the tarball, source-map exclusion, registry metadata, full-lifecycle stdio smoke test, CHANGELOG, and archiving align-protocol-v1-2-0. Co-Authored-By: Claude Opus 5.5 --- .../changes/release-v0-2-0/.openspec.yaml | 3 ++ openspec/changes/release-v0-2-0/design.md | 38 ++++++++++++++ openspec/changes/release-v0-2-0/proposal.md | 52 +++++++++++++++++++ .../changes/release-v0-2-0/specs/cli/spec.md | 35 +++++++++++++ openspec/changes/release-v0-2-0/tasks.md | 24 +++++++++ 5 files changed, 152 insertions(+) create mode 100644 openspec/changes/release-v0-2-0/.openspec.yaml create mode 100644 openspec/changes/release-v0-2-0/design.md create mode 100644 openspec/changes/release-v0-2-0/proposal.md create mode 100644 openspec/changes/release-v0-2-0/specs/cli/spec.md create mode 100644 openspec/changes/release-v0-2-0/tasks.md diff --git a/openspec/changes/release-v0-2-0/.openspec.yaml b/openspec/changes/release-v0-2-0/.openspec.yaml new file mode 100644 index 0000000..6e45cf4 --- /dev/null +++ b/openspec/changes/release-v0-2-0/.openspec.yaml @@ -0,0 +1,3 @@ +schema: spec-driven +created: 2026-11-19 +x-originating-issue: 7 diff --git a/openspec/changes/release-v0-2-0/design.md b/openspec/changes/release-v0-2-0/design.md new file mode 100644 index 0000000..6863399 --- /dev/null +++ b/openspec/changes/release-v0-2-0/design.md @@ -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. diff --git a/openspec/changes/release-v0-2-0/proposal.md b/openspec/changes/release-v0-2-0/proposal.md new file mode 100644 index 0000000..cbe67f3 --- /dev/null +++ b/openspec/changes/release-v0-2-0/proposal.md @@ -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. diff --git a/openspec/changes/release-v0-2-0/specs/cli/spec.md b/openspec/changes/release-v0-2-0/specs/cli/spec.md new file mode 100644 index 0000000..be6a5ac --- /dev/null +++ b/openspec/changes/release-v0-2-0/specs/cli/spec.md @@ -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/` diff --git a/openspec/changes/release-v0-2-0/tasks.md b/openspec/changes/release-v0-2-0/tasks.md new file mode 100644 index 0000000..37c343d --- /dev/null +++ b/openspec/changes/release-v0-2-0/tasks.md @@ -0,0 +1,24 @@ +# Tasks + +## 1. Versioning + +- [ ] 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 + +- [ ] 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 +- [ ] 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 + +- [ ] 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 + +- [ ] 4.1 Add `CHANGELOG.md` with the v0.2.0 entry +- [ ] 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 + +- [ ] 5.1 Archive `align-protocol-v1-2-0` with `--skip-specs` +- [ ] 5.2 Run the CI parity gates — `npx biome check src/ tests/`, `npm run build`, `npx vitest run --coverage` — all pass at ≥85% From f11c8f912a320fdf392432942854dbf2e705766d Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Thu, 19 Nov 2026 13:38:50 -0500 Subject: [PATCH 2/8] chore: bump version to 0.2.0 (release-v0-2-0 1.1) Co-Authored-By: Claude Opus 5.5 --- openspec/changes/release-v0-2-0/tasks.md | 2 +- package-lock.json | 4 ++-- package.json | 2 +- src/index.ts | 2 +- tests/cli.test.ts | 6 +++--- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/openspec/changes/release-v0-2-0/tasks.md b/openspec/changes/release-v0-2-0/tasks.md index 37c343d..fc486e6 100644 --- a/openspec/changes/release-v0-2-0/tasks.md +++ b/openspec/changes/release-v0-2-0/tasks.md @@ -2,7 +2,7 @@ ## 1. Versioning -- [ ] 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 +- [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 diff --git a/package-lock.json b/package-lock.json index 5e1c412..e0b4c5c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "reading-stone", - "version": "0.1.0", + "version": "0.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "reading-stone", - "version": "0.1.0", + "version": "0.2.0", "license": "Apache-2.0", "dependencies": { "typescript": "7.0.2" diff --git a/package.json b/package.json index efe00dd..61d65a5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "reading-stone", - "version": "0.1.0", + "version": "0.2.0", "description": "TypeScript side-effect analyzer backend for Gaze", "type": "module", "license": "Apache-2.0", diff --git a/src/index.ts b/src/index.ts index b4b07bd..5473bf1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -32,7 +32,7 @@ * compile-time types stays explicit. */ -export const VERSION = "0.1.0"; +export const VERSION = "0.2.0"; export type { PatternSet, diff --git a/tests/cli.test.ts b/tests/cli.test.ts index 259e9ac..6a6fa3d 100644 --- a/tests/cli.test.ts +++ b/tests/cli.test.ts @@ -82,8 +82,8 @@ describe("main", () => { }); describe("package metadata", () => { - it("exposes VERSION 0.1.0", () => { - expect(VERSION).toBe("0.1.0"); + it("exposes VERSION 0.2.0", () => { + expect(VERSION).toBe("0.2.0"); }); it("declares the expected package.json fields", () => { @@ -91,7 +91,7 @@ describe("package metadata", () => { readFileSync(new URL("../package.json", import.meta.url), "utf8"), ) as Record; expect(pkg.name).toBe("reading-stone"); - expect(pkg.version).toBe("0.1.0"); + expect(pkg.version).toBe("0.2.0"); expect(pkg.license).toBe("Apache-2.0"); expect(pkg.type).toBe("module"); expect(pkg.bin).toEqual({ From 5fdfcd25e2b2a374409ea32299a9d035522fd120 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Thu, 19 Nov 2026 13:40:20 -0500 Subject: [PATCH 3/8] fix: ship NOTICE, drop dangling source maps, add lifecycle smoke test (release-v0-2-0 2.1, 2.2, 3.1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit npm does not auto-include NOTICE, so the tarball would have shipped snake-eyes-derived code without the Apache-2.0 §4(d) attribution. Source maps pointed at the unshipped src/ and are now excluded. Adds homepage, bugs, keywords, and an exports map for the index barrel, plus a tarball-contents test pinned via npm pack --dry-run --json. Adds the issue #7 end-to-end test: one dist/main.js session runs initialize, discover, all seven analysis methods, and shutdown over a fixture project, requiring a success and non-empty rows from each. Co-Authored-By: Claude Opus 5.5 --- openspec/changes/release-v0-2-0/tasks.md | 6 +- package.json | 25 ++- tests/cli.test.ts | 215 ++++++++++++++++++++++- 3 files changed, 241 insertions(+), 5 deletions(-) diff --git a/openspec/changes/release-v0-2-0/tasks.md b/openspec/changes/release-v0-2-0/tasks.md index fc486e6..1eed14d 100644 --- a/openspec/changes/release-v0-2-0/tasks.md +++ b/openspec/changes/release-v0-2-0/tasks.md @@ -6,12 +6,12 @@ ## 2. Packaging -- [ ] 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 -- [ ] 2.2 Add a tarball-contents test (`npm pack --dry-run --json`) pinning NOTICE/LICENSE/README/package.json present and no `.map` files +- [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 -- [ ] 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) +- [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 diff --git a/package.json b/package.json index 61d65a5..9eb9f48 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,16 @@ "name": "reading-stone", "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", @@ -9,6 +19,10 @@ "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" }, @@ -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", diff --git a/tests/cli.test.ts b/tests/cli.test.ts index 6a6fa3d..f4232c6 100644 --- a/tests/cli.test.ts +++ b/tests/cli.test.ts @@ -1,4 +1,4 @@ -import { spawn } from "node:child_process"; +import { spawn, spawnSync } from "node:child_process"; import { existsSync, readFileSync } from "node:fs"; import { Readable, Writable } from "node:stream"; import { fileURLToPath } from "node:url"; @@ -103,6 +103,19 @@ describe("package metadata", () => { // typescript/unstable/* surface, which carries no semver stability // guarantee, so a caret range could resolve a breaking 7.x. expect(pkg.dependencies).toEqual({ typescript: "7.0.2" }); + // The registry surface (release-v0-2-0): the barrel is the only + // exported entry (AP-001); NOTICE ships for Apache-2.0 §4(d) + // attribution, which npm does not auto-include; source maps are + // excluded because their `sources` point at the unshipped src/. + expect(pkg.exports).toEqual({ + ".": { types: "./dist/index.d.ts", default: "./dist/index.js" }, + "./package.json": "./package.json", + }); + expect(pkg.files).toEqual(["dist", "!dist/**/*.map", "NOTICE"]); + expect(pkg.homepage).toBe("https://github.com/zero-dot-force/reading-stone#readme"); + expect(pkg.bugs).toEqual({ + url: "https://github.com/zero-dot-force/reading-stone/issues", + }); }); it("ships the gaze-analyzer-typescript bin alias for PATH auto-discovery", () => { @@ -173,6 +186,78 @@ interface SubprocessComplexityEntry { readonly complexity: number; } +// The full-lifecycle fixture (release-v0-2-0 task 3.1): one documented, +// exported source function carrying a stdout write, a parameter mutation, +// a branch, and a return value; one vitest test asserting on it; a +// tsconfig so program mode (checker-dependent signals) is exercised; and +// a hand-authored Istanbul artifact so `coverage` answers rows without +// any test execution (Constitution Principle V). Every analysis method +// returns at least one row over it, so a regression that empties any +// method fails the lifecycle test loudly. +const LIFECYCLE_SOURCES: Readonly> = { + "package.json": '{"name":"fixture","devDependencies":{"vitest":"*"}}\n', + "tsconfig.json": + '{"compilerOptions":{"strict":true,"module":"NodeNext","moduleResolution":"NodeNext"},"include":["src","tests"]}\n', + "src/store.ts": [ + "/** Records a value in the cache and returns the previous one. */", // 1 + "export function remember(cache: Map, key: string, value: number): number | undefined {", // 2 + " const previous = cache.get(key);", // 3 + " if (previous === undefined) {", // 4 + ' console.log("first write", key);', // 5 + " }", // 6 + " cache.set(key, value);", // 7 + " return previous;", // 8 + "}", // 9 + "", + ].join("\n"), + "tests/store.test.ts": [ + 'import { expect, it } from "vitest";', + 'import { remember } from "../src/store";', + "", + 'it("returns the previous value", () => {', + " const cache = new Map();", + ' expect(remember(cache, "a", 1)).toBeUndefined();', + ' expect(remember(cache, "a", 2)).toBe(1);', + "});", + "", + ].join("\n"), + "coverage/coverage-final.json": JSON.stringify({ + "src/store.ts": { + path: "src/store.ts", + statementMap: { + "0": { start: { line: 3, column: 2 }, end: { line: 3, column: 35 } }, + "1": { start: { line: 4, column: 2 }, end: { line: 6, column: 3 } }, + "2": { start: { line: 5, column: 4 }, end: { line: 5, column: 36 } }, + "3": { start: { line: 7, column: 2 }, end: { line: 7, column: 24 } }, + "4": { start: { line: 8, column: 2 }, end: { line: 8, column: 18 } }, + }, + fnMap: { + "0": { + name: "remember", + decl: { start: { line: 2, column: 16 }, end: { line: 2, column: 24 } }, + loc: { start: { line: 2, column: 101 }, end: { line: 9, column: 1 } }, + }, + }, + branchMap: {}, + s: { "0": 2, "1": 2, "2": 1, "3": 2, "4": 2 }, + f: { "0": 2 }, + b: {}, + }, + }), +}; + +// The lifecycle order issue #7 names, each analysis method paired with +// the single result key its v1.2.0 schema defines. +const LIFECYCLE_METHODS: ReadonlyArray = [ + ["analyze", "functions"], + ["complexity", "functions"], + ["coverage", "functions"], + ["test_mapping", "mappings"], + ["classify_signals", "signals"], + ["doc_coverage", "symbols"], + ["cognitive_complexity", "functions"], +]; + describe.skipIf(!existsSync(mainJs))("subprocess", () => { function readLine(stream: Readable): Promise { return new Promise((resolve, reject) => { @@ -223,6 +308,134 @@ describe.skipIf(!existsSync(mainJs))("subprocess", () => { expect(exitCode).toBe(2); }); + // Release-v0-2-0 task 2.2: the tarball npm would publish, read with + // `npm pack --dry-run --json` (honors `files`, its negation, and npm's + // auto-includes) without writing a tarball. Gated with this suite + // because the list only contains dist/ once it is built. + it("packs NOTICE and the compiled surface, never source maps", { + timeout: 60_000, + }, () => { + const packed = spawnSync( + "npm", + ["pack", "--dry-run", "--json", "--ignore-scripts"], + { + cwd: fileURLToPath(new URL("..", import.meta.url)), + encoding: "utf8", + shell: process.platform === "win32", + }, + ); + expect(packed.status).toBe(0); + const [manifest] = JSON.parse(packed.stdout) as Array<{ + files: Array<{ path: string }>; + }>; + const paths = (manifest?.files ?? []).map((file) => file.path); + for (const required of [ + "NOTICE", + "LICENSE", + "README.md", + "package.json", + "dist/main.js", + "dist/index.js", + "dist/index.d.ts", + ]) { + expect(paths).toContain(required); + } + expect(paths.filter((path) => path.endsWith(".map"))).toEqual([]); + expect( + paths.filter((path) => path.startsWith("src/") || path.startsWith("tests/")), + ).toEqual([]); + }); + + // Release-v0-2-0 task 3.1 (issue #7): the whole protocol lifecycle in + // ONE session against the BUILT server Gaze spawns — initialize, + // discover, the seven analysis methods, shutdown. Every response must + // be a success echoing its id; every analysis method must answer its + // single schema key with a non-empty row array over the fixture. + it("serves the full v1.2.0 lifecycle in one session", { + timeout: 120_000, + }, async () => { + const tree = await createFixtureTree(LIFECYCLE_SOURCES); + const child = spawn(process.execPath, [mainJs, "--stdio"]); + try { + const rootParam = `{"root_path":${JSON.stringify(tree.root)}}`; + const methods = [ + "initialize", + "discover", + ...LIFECYCLE_METHODS.map(([method]) => method), + "shutdown", + ]; + const lines: string[] = []; + let buffer = ""; + child.stdout.on("data", (chunk: Buffer) => { + buffer += chunk.toString(); + let index = buffer.indexOf("\n"); + while (index >= 0) { + lines.push(buffer.slice(0, index)); + buffer = buffer.slice(index + 1); + index = buffer.indexOf("\n"); + } + }); + const exited = new Promise((resolve) => { + child.on("exit", (code) => resolve(code)); + }); + child.stdin.write( + methods + .map( + (method, index) => + `{"jsonrpc":"2.0","id":${index + 1},"method":"${method}","params":${rootParam}}\n`, + ) + .join(""), + ); + const exitCode = await exited; + + // Assertions run only after the child exits, so a failure can + // never strand the subprocess. + expect(exitCode).toBe(0); + expect(lines).toHaveLength(methods.length); + const responses = lines.map( + (line) => + JSON.parse(line) as { + jsonrpc: string; + id: number; + result?: Record; + error?: unknown; + }, + ); + responses.forEach((response, index) => { + expect(response.jsonrpc).toBe("2.0"); + expect(response.id).toBe(index + 1); + expect(response.error).toBeUndefined(); + expect(response.result).toBeTypeOf("object"); + }); + + const [initialize, discover] = responses; + expect(initialize?.result?.protocol_version).toBe("1.2.0"); + expect(initialize?.result?.capabilities).toEqual({ + classify_signals: true, + cognitive_complexity: true, + discover: true, + doc_coverage: true, + streaming: false, + test_mapping: true, + }); + expect(discover?.result?.source_files).toEqual(["src/store.ts"]); + expect(discover?.result?.test_files).toEqual(["tests/store.test.ts"]); + + LIFECYCLE_METHODS.forEach(([method, key], offset) => { + const result = responses[offset + 2]?.result ?? {}; + expect(Object.keys(result), method).toEqual([key]); + const rows = result[key]; + expect(Array.isArray(rows), method).toBe(true); + expect((rows as unknown[]).length, method).toBeGreaterThan(0); + }); + + expect(responses.at(-1)?.result).toEqual({}); + } finally { + child.kill(); + await tree.cleanup(); + } + }); + // The closed kind set (005 FR-001): the gaze protocol's doc_coverage // schema enumeration, mirrored so this black-box check validates the // same six values the serializer enforces (the tests/helpers/wire.ts From 50f2c4a02c2b4e455a6e5b5bf97591acde7dfe42 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Thu, 19 Nov 2026 13:40:50 -0500 Subject: [PATCH 4/8] docs: CHANGELOG, README npm install, AGENTS.md release note (release-v0-2-0 4.1, 4.2) Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 3 +- CHANGELOG.md | 51 ++++++++++++++++++++++++ README.md | 20 ++++++---- openspec/changes/release-v0-2-0/tasks.md | 4 +- 4 files changed, 68 insertions(+), 10 deletions(-) create mode 100644 CHANGELOG.md diff --git a/AGENTS.md b/AGENTS.md index 67c1a83..ca32959 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..82f281e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,51 @@ +# 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] + +## [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). +- `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 diff --git a/README.md b/README.md index 1467fd7..d92aeb8 100644 --- a/README.md +++ b/README.md @@ -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 | |--------|--------| @@ -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 @@ -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 diff --git a/openspec/changes/release-v0-2-0/tasks.md b/openspec/changes/release-v0-2-0/tasks.md index 1eed14d..803b97d 100644 --- a/openspec/changes/release-v0-2-0/tasks.md +++ b/openspec/changes/release-v0-2-0/tasks.md @@ -15,8 +15,8 @@ ## 4. Documentation -- [ ] 4.1 Add `CHANGELOG.md` with the v0.2.0 entry -- [ ] 4.2 README: v0.2.0 status heading, npm install path, exact `typescript` pin note; AGENTS.md: correct the "v0.1.0 shipped" claim +- [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 From a88d9abdcf455417c653f0cffda3b77a187af5a3 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Thu, 19 Nov 2026 13:41:03 -0500 Subject: [PATCH 5/8] chore: archive align-protocol-v1-2-0 OpenSpec change (release-v0-2-0 5.1) Archived with --skip-specs: its deltas were pre-synced into the main specs at merge and 005 has since advanced the capability scenarios, so re-applying them would regress the main spec. Co-Authored-By: Claude Opus 5.5 --- .../2026-11-19-align-protocol-v1-2-0}/.openspec.yaml | 0 .../2026-11-19-align-protocol-v1-2-0}/design.md | 0 .../2026-11-19-align-protocol-v1-2-0}/proposal.md | 0 .../2026-11-19-align-protocol-v1-2-0}/specs/protocol/spec.md | 0 .../2026-11-19-align-protocol-v1-2-0}/specs/server/spec.md | 0 .../2026-11-19-align-protocol-v1-2-0}/tasks.md | 0 openspec/changes/release-v0-2-0/tasks.md | 2 +- 7 files changed, 1 insertion(+), 1 deletion(-) rename openspec/changes/{align-protocol-v1-2-0 => archive/2026-11-19-align-protocol-v1-2-0}/.openspec.yaml (100%) rename openspec/changes/{align-protocol-v1-2-0 => archive/2026-11-19-align-protocol-v1-2-0}/design.md (100%) rename openspec/changes/{align-protocol-v1-2-0 => archive/2026-11-19-align-protocol-v1-2-0}/proposal.md (100%) rename openspec/changes/{align-protocol-v1-2-0 => archive/2026-11-19-align-protocol-v1-2-0}/specs/protocol/spec.md (100%) rename openspec/changes/{align-protocol-v1-2-0 => archive/2026-11-19-align-protocol-v1-2-0}/specs/server/spec.md (100%) rename openspec/changes/{align-protocol-v1-2-0 => archive/2026-11-19-align-protocol-v1-2-0}/tasks.md (100%) diff --git a/openspec/changes/align-protocol-v1-2-0/.openspec.yaml b/openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/.openspec.yaml similarity index 100% rename from openspec/changes/align-protocol-v1-2-0/.openspec.yaml rename to openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/.openspec.yaml diff --git a/openspec/changes/align-protocol-v1-2-0/design.md b/openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/design.md similarity index 100% rename from openspec/changes/align-protocol-v1-2-0/design.md rename to openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/design.md diff --git a/openspec/changes/align-protocol-v1-2-0/proposal.md b/openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/proposal.md similarity index 100% rename from openspec/changes/align-protocol-v1-2-0/proposal.md rename to openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/proposal.md diff --git a/openspec/changes/align-protocol-v1-2-0/specs/protocol/spec.md b/openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/specs/protocol/spec.md similarity index 100% rename from openspec/changes/align-protocol-v1-2-0/specs/protocol/spec.md rename to openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/specs/protocol/spec.md diff --git a/openspec/changes/align-protocol-v1-2-0/specs/server/spec.md b/openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/specs/server/spec.md similarity index 100% rename from openspec/changes/align-protocol-v1-2-0/specs/server/spec.md rename to openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/specs/server/spec.md diff --git a/openspec/changes/align-protocol-v1-2-0/tasks.md b/openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/tasks.md similarity index 100% rename from openspec/changes/align-protocol-v1-2-0/tasks.md rename to openspec/changes/archive/2026-11-19-align-protocol-v1-2-0/tasks.md diff --git a/openspec/changes/release-v0-2-0/tasks.md b/openspec/changes/release-v0-2-0/tasks.md index 803b97d..7dd529c 100644 --- a/openspec/changes/release-v0-2-0/tasks.md +++ b/openspec/changes/release-v0-2-0/tasks.md @@ -20,5 +20,5 @@ ## 5. OpenSpec hygiene and gates -- [ ] 5.1 Archive `align-protocol-v1-2-0` with `--skip-specs` +- [x] 5.1 Archive `align-protocol-v1-2-0` with `--skip-specs` - [ ] 5.2 Run the CI parity gates — `npx biome check src/ tests/`, `npm run build`, `npx vitest run --coverage` — all pass at ≥85% From d6c744f1c3edbb012c4f3ed5306eb4ff5f17fdc3 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Thu, 19 Nov 2026 13:41:40 -0500 Subject: [PATCH 6/8] tasks: mark release-v0-2-0 5.2 CI parity gates complete Co-Authored-By: Claude Opus 5.5 --- openspec/changes/release-v0-2-0/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openspec/changes/release-v0-2-0/tasks.md b/openspec/changes/release-v0-2-0/tasks.md index 7dd529c..de6b01e 100644 --- a/openspec/changes/release-v0-2-0/tasks.md +++ b/openspec/changes/release-v0-2-0/tasks.md @@ -21,4 +21,4 @@ ## 5. OpenSpec hygiene and gates - [x] 5.1 Archive `align-protocol-v1-2-0` with `--skip-specs` -- [ ] 5.2 Run the CI parity gates — `npx biome check src/ tests/`, `npm run build`, `npx vitest run --coverage` — all pass at ≥85% +- [x] 5.2 Run the CI parity gates — `npx biome check src/ tests/`, `npm run build`, `npx vitest run --coverage` — all pass at ≥85% From abfc1777829e842f64637d61a7b92a6078171831 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Thu, 19 Nov 2026 15:11:06 -0500 Subject: [PATCH 7/8] docs: CHANGELOG notes Gaze assertion-type set (#28) Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 82f281e..381d669 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,8 @@ for TypeScript and JavaScript projects. 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 From 0cd90f0e47c4e3650c93dbbb29d2eb7ab591f7f2 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Thu, 19 Nov 2026 16:50:51 -0500 Subject: [PATCH 8/8] chore: archive align-assertion-types OpenSpec change (merged in #28) Co-Authored-By: Claude Opus 5.5 --- .../2026-11-19-align-assertion-types}/.openspec.yaml | 0 .../2026-11-19-align-assertion-types}/proposal.md | 0 .../2026-11-19-align-assertion-types}/tasks.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename openspec/changes/{align-assertion-types => archive/2026-11-19-align-assertion-types}/.openspec.yaml (100%) rename openspec/changes/{align-assertion-types => archive/2026-11-19-align-assertion-types}/proposal.md (100%) rename openspec/changes/{align-assertion-types => archive/2026-11-19-align-assertion-types}/tasks.md (100%) diff --git a/openspec/changes/align-assertion-types/.openspec.yaml b/openspec/changes/archive/2026-11-19-align-assertion-types/.openspec.yaml similarity index 100% rename from openspec/changes/align-assertion-types/.openspec.yaml rename to openspec/changes/archive/2026-11-19-align-assertion-types/.openspec.yaml diff --git a/openspec/changes/align-assertion-types/proposal.md b/openspec/changes/archive/2026-11-19-align-assertion-types/proposal.md similarity index 100% rename from openspec/changes/align-assertion-types/proposal.md rename to openspec/changes/archive/2026-11-19-align-assertion-types/proposal.md diff --git a/openspec/changes/align-assertion-types/tasks.md b/openspec/changes/archive/2026-11-19-align-assertion-types/tasks.md similarity index 100% rename from openspec/changes/align-assertion-types/tasks.md rename to openspec/changes/archive/2026-11-19-align-assertion-types/tasks.md