Repository navigation
Release v0.2.0: version bump, packaging fixes, full-lifecycle smoke test #27
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
jflowers
wants to merge
8
commits into
zero-dot-force:main
Choose a base branch
from
jflowers:release/v0.2.0
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+465
−17
Draft
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
0985465
spec: add release-v0-2-0 OpenSpec change (#7)
jflowers f11c8f9
chore: bump version to 0.2.0 (release-v0-2-0 1.1)
jflowers 5fdfcd2
fix: ship NOTICE, drop dangling source maps, add lifecycle smoke test…
jflowers 50f2c4a
docs: CHANGELOG, README npm install, AGENTS.md release note (release-…
jflowers a88d9ab
chore: archive align-protocol-v1-2-0 OpenSpec change (release-v0-2-0 …
jflowers d6c744f
tasks: mark release-v0-2-0 5.2 CI parity gates complete
jflowers abfc177
docs: CHANGELOG notes Gaze assertion-type set (#28)
jflowers 0cd90f0
chore: archive align-assertion-types OpenSpec change (merged in #28)
jflowers File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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] | ||
|
|
||
| ## [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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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/` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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% |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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 atopenspec/changes/release-v0-2-0/, so release → spec linkage rests on the PR body alone. A line such asSpec: openspec/changes/release-v0-2-0/under the entry restores the audit path. Advisory only — the entry's content itself is accurate.