Skip to content

feat: add gaze-analyzer-typescript bin alias for Gaze PATH discovery - #20

Merged
jflowers merged 2 commits into
zero-dot-force:mainfrom
jflowers:quick/gaze-analyzer-typescript-bin-alias
Nov 1, 2026
Merged

jflowers merged 2 commits into
zero-dot-force:mainfrom
jflowers:quick/gaze-analyzer-typescript-bin-alias

Conversation

@jflowers

@jflowers jflowers commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Reading Stone now ships a second bin name, gaze-analyzer-typescript, mapping
to the same dist/main.js entry point as reading-stone — mirroring
snake-eyes' dual gaze-analyzer-python script precedent. With the alias on
PATH (npm i -g reading-stone for consumers, npm link for dogfooding),
Gaze's tier-3 analyzer discovery auto-discovers Reading Stone for TypeScript
projects with no .gaze.yaml needed — which is what makes the /gaze slash
command work against this repository without altering it.

The README Installation and Configuration sections were rewritten to document
both bin names, the PATH-discovery flow with its --language typescript
invocation trigger, and a corrected .gaze.yaml example
(command: gaze-analyzer-typescript with args: ["--stdio"] — Gaze's config
tier passes args verbatim, while the CLI-flag and PATH-convention tiers append
--stdio automatically). A dedicated test in tests/cli.test.ts pins the bin
map alongside the existing manifest snapshot, and two stale gaze v1.8.0
scaffold markers were removed from .opencode/agents/gaze-reporter.md and
.opencode/commands/gaze.md.

This PR carries two concerns (called out explicitly per review advisory):

  1. b7133d1 — the feature: bin alias, README docs, bin-map test, stale
    marker removal.
  2. 8e61d24 — a scaffold chore that rode main ahead of the branch: uf
    scaffolding update (reviewer-testing → divisor-gaze-testing rename, review
    matrix refresh, 9 files). Its content was verified by the review council;
    it is unchanged by this PR.

End-to-end dogfooding verified live: after npm link,
gaze crap --language typescript ./src/... reports "Using external analyzer:
reading-stone (language: typescript)". Related: #7 (v0.2.0 release — the bin
alias is a named deliverable), #19 (blog announcement tracking).

How to Test

Run the CI checks (derived from .github/workflows/ci.yml):

npm ci
npx biome check src/ tests/
npm run build
npx vitest run --coverage

Dogfood the analyzer through Gaze's tier-3 PATH discovery (the /gaze
command's backend path):

npm link
gaze crap --language typescript --format=json ./src/...

Expect Using external analyzer: reading-stone (language: typescript) on
stderr, exit 0, and ~360 analyzed functions at ~94.8% average line coverage.
In opencode, /gaze ./src/... now exercises the full dogfooding path
unchanged.

How to Demo

Trivial packaging/docs change — no runtime demo required. The dogfood command
above doubles as the demo if you want to see the analyzer picked up live.

Key Files Changed

Feature (b7133d1):

  • package.json — second bin entry gaze-analyzer-typescript → dist/main.js
  • README.md — Installation/Configuration rewritten for PATH discovery + corrected .gaze.yaml example
  • tests/cli.test.ts — manifest snapshot updated + dedicated bin-alias test
  • .opencode/agents/gaze-reporter.md, .opencode/commands/gaze.md — stale scaffold markers removed

Scaffold chore (8e61d24, rode in from main):

  • .opencode/agents/divisor-gaze-testing.md (new), .opencode/agents/reviewer-testing.md (deleted), .opencode/agents/gaze-test-generator.md
  • .opencode/commands/gaze-fix.md, .opencode/commands/speckit.testreview.md
  • .opencode/references/doc-scoring-model.md, .opencode/references/example-report.md
  • .uf/review-matrix.yaml, .uf/reviewer-capabilities.yaml

Known Issues

This PR was generated by /uf.finale (AI-assisted).

Add a second bin entry pointing at dist/main.js so Gaze's tier-3
convention (gaze-analyzer-<language> on $PATH) discovers Reading
Stone after `npm i -g reading-stone` or `npm link` with zero
configuration, mirroring snake-eyes' dual entry points. npm's
bin-link also sets the exec bit tsc leaves unset.

- package.json: add "gaze-analyzer-typescript": "dist/main.js"
- README: fix the .gaze.yaml example (args: ["--stdio"] is required
  because Gaze passes tier-2 args verbatim) and document the
  --language typescript trigger for PATH discovery
- tests: update the package-manifest snapshot and add a dedicated
  bin-alias test
- remove stale gaze v1.8.0 scaffold markers from gaze-reporter.md
  and gaze.md

Assisted-by: glm-5
Generated with AI assistance (glm-5)
@jflowers jflowers self-assigned this Nov 1, 2026

@jflowers jflowers left a comment

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.

Review Summary

Verdict: APPROVE WITH ADVISORIES — 4 LOW advisories, no blocking findings.

The Divisor review council (5 personas) reviewed this PR; all five approved, with the architect and sre noting advisories:

  • divisor-adversary (heavy): APPROVE — no findings
  • divisor-architect (standard): APPROVE WITH ADVISORIES — 3 LOW findings
  • divisor-curator (standard): APPROVE — no findings
  • divisor-guard (standard): APPROVE — no findings
  • divisor-sre (lightweight): APPROVE WITH ADVISORIES — 1 LOW finding

CI: test (22) and test (24) both pass at head b7133d19. Pre-flight: all CI commands covered by green CI (ci-aware; no local execution needed).

Advisories (4, all LOW)

  1. tests/cli.test.ts:110 — the dedicated bin-alias test duplicates the bin-map assertions the updated metadata snapshot test already makes (CS-004); its value is documentation via the test name.
  2. README.md:120 — the .gaze.yaml configuration section omits the --language typescript requirement for tier-2 discovery; a reader following only that section receives Go analysis instead of the configured analyzer.
  3. package.json:17 — the README/AGENTS structure-tree annotations still name a single bin now that the bin surface doubled (DR-002); deferred to #7 in the PR body.
  4. .uf/review-matrix.yaml:44 — the divisor-testing → divisor-gaze-testing registration leaves inert referents (triage membership plus a capabilities entry for a persona with no agent file here); triage dispatches run without a testing persona.

Three of the four advisories are acknowledged in the PR body's Known Issues; the inline comments carry the details.

This review was generated by /uf.review-pr (AI-assisted).

Comment thread tests/cli.test.ts

it("ships the gaze-analyzer-typescript bin alias for PATH auto-discovery", () => {
// Gaze's zero-config discovery tier spawns whatever
// gaze-analyzer-<language> binary it finds on PATH (the snake-eyes

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 · testing-conventions] This test duplicates the bin-map assertions the preceding metadata test already makes. The updated expect(pkg.bin).toEqual({...}) in "contains the exact package metadata" asserts the complete bin map — both keys, both targets, no extras — so the two assertions here add no coverage (CS-004: two assertion sites must now stay in sync). The test's value is its name and comment documenting the Gaze PATH-discovery convention; if it stays as living documentation, consider dropping the redundant assertions or folding the convention comment into the snapshot test.

Comment thread README.md
without the flag it falls back to its built-in Go analysis. The
global install puts the alias on PATH alongside `reading-stone`.

To name the analyzer explicitly in `.gaze.yaml`, point it at the

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 · operational-documentation] This section omits the --language typescript requirement for tier-2 discovery. The --language flag selects the language key Gaze looks up in both .gaze.yaml (tier 2) and the PATH convention (tier 3); without it, Gaze falls back to its built-in Go analysis even when .gaze.yaml names the analyzer. The flag requirement appears only in the PATH-discovery paragraph above (lines 112–118), so a reader who jumps to this section can follow the steps exactly and receive Go analysis of a TypeScript project. Stating the flag requirement here closes the gap the PR body lists as a known issue.

Comment thread package.json
"bin": {
"reading-stone": "dist/main.js"
"reading-stone": "dist/main.js",
"gaze-analyzer-typescript": "dist/main.js"

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 · documentation] The structure-tree annotations in README.md (~line 144) and AGENTS.md still describe a single bin ("Entry point (reading-stone --stdio)") now that the bin map ships two entry points (DR-002: README/AGENTS reflect the public surface). The PR body defers this to #7; recording the drift here so the release tracking issue captures both files.

Comment thread .uf/review-matrix.yaml
- divisor-sre
- divisor-testing
- divisor-gaze-testing
triage:

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 · configuration-consistency] The persona-rename registration is partial in this repo. The triage membership list still references divisor-testing, and .uf/reviewer-capabilities.yaml keeps its pre-existing divisor-testing entry — but .opencode/agents/divisor-testing.md does not exist here, so those referents are inert: triage dispatches run without a testing persona, and the capabilities file declares two test-quality reviewers, one of which cannot run. The swap matches the upstream gaze repo's diff; adapting it to this repo's inventory (or dropping the dead entries) completes the migration. No functional regression versus the pre-PR state.

@jflowers
jflowers merged commit 950d3f2 into zero-dot-force:main Nov 1, 2026
2 checks passed
@jflowers
jflowers deleted the quick/gaze-analyzer-typescript-bin-alias branch November 15, 2026 21:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant