mirror of
https://github.com/esengine/DeepSeek-Reasonix.git
synced 2026-11-08 01:48:26 -10:00
docs(contrib): CONTRIBUTING.md + PR / feature-request templates · refresh REASONIX.md layout
CONTRIBUTING.md is the human-facing rules entry on GitHub (CLAUDE.md stays as the AI-agent entry). Code rules previously only in CLAUDE.md are now inlined here so contributors actually see them. REASONIX.md layout table catches up to the recent structure refactor — adds core/, ports/, adapters/, frame/, memory/, transcript/, telemetry/, server/, code/ which had drifted off the doc.
This commit is contained in:
esengine committed
1 parent
146ddb0658
commit
4bf0abefc1
4 files changed
+201
-2
No files matched your search
@@ -0,0 +1,20 @@
|
||||
---
|
||||
name: Feature request
|
||||
about: Propose a new behavior or enhancement
|
||||
labels: enhancement
|
||||
---
|
||||
|
||||
**Problem**
|
||||
What real problem does this solve? Who hits it?
|
||||
|
||||
**Proposed change**
|
||||
What you'd like reasonix to do differently. Include a sketch of the
|
||||
UX or API if relevant.
|
||||
|
||||
**Alternatives considered**
|
||||
What else you tried or thought about. "I just want it" is not an
|
||||
alternative.
|
||||
|
||||
**Scope check**
|
||||
- [ ] This belongs in core reasonix (not better as a separate npm package)
|
||||
- [ ] I've read CLAUDE.md and CONTRIBUTING.md
|
||||
@@ -0,0 +1,20 @@
|
||||
<!-- Read CONTRIBUTING.md first if this is your first PR. -->
|
||||
|
||||
## What
|
||||
|
||||
<!-- One paragraph: what does this change? -->
|
||||
|
||||
## Why
|
||||
|
||||
<!-- Bug fix? Pre-existing issue? Linked discussion? -->
|
||||
|
||||
## How to verify
|
||||
|
||||
<!-- Steps the reviewer can run. `npm run verify` is assumed. -->
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] `npm run verify` passes locally (lint + typecheck + tests + comment-policy gate)
|
||||
- [ ] CHANGELOG updated under `## [Unreleased]` if user-visible
|
||||
- [ ] No `Co-Authored-By: Claude` trailer in commits
|
||||
- [ ] Comments follow CLAUDE.md (no module-essay headers, no incident history)
|
||||
+150
@@ -0,0 +1,150 @@
|
||||
# Contributing to Reasonix
|
||||
|
||||
Thanks for showing up. Reasonix is a small, opinionated codebase
|
||||
maintained primarily by [@esengine](https://github.com/esengine);
|
||||
PRs are welcome, but read this first so the round-trip is short.
|
||||
|
||||
## Setup
|
||||
|
||||
```sh
|
||||
git clone https://github.com/esengine/reasonix
|
||||
cd reasonix
|
||||
npm install
|
||||
npm run dev # tsx src/cli/index.ts — live source
|
||||
```
|
||||
|
||||
Node ≥ 20.10. No global install needed during development.
|
||||
|
||||
For stack, layout, scripts, see [`REASONIX.md`](./REASONIX.md).
|
||||
|
||||
## Proposing changes
|
||||
|
||||
- **Bug fixes** — go ahead and open a PR. Include a reproduction.
|
||||
- **New features / behavior changes** — open an issue first to align
|
||||
on scope and approach. Reasonix tries to stay small; "we could add
|
||||
X" PRs that arrive cold are usually rejected or scoped down.
|
||||
- **External MCP servers, plugins, presets** — a thin wrapper is
|
||||
fine; a sprawling integration is better hosted as a separate
|
||||
package that depends on `reasonix`.
|
||||
|
||||
## Code rules
|
||||
|
||||
These are enforced by review and (where possible) by
|
||||
`tests/comment-policy.test.ts` — which runs under `npm run verify`
|
||||
and gates pre-push.
|
||||
|
||||
### Comments — default is none
|
||||
|
||||
Write a comment ONLY when **why** is non-obvious and removing the
|
||||
comment would confuse a future reader. Justified examples:
|
||||
|
||||
- a hidden constraint (`// Yoga miscounts wrap → must clamp to width-1`)
|
||||
- a workaround for a specific bug
|
||||
- a subtle invariant the type system can't express
|
||||
|
||||
Don't write:
|
||||
|
||||
- **What the code does.** Names already say it. No `// when x is positive`
|
||||
above `if (x > 0)`.
|
||||
- **Module-level essays.** Multi-paragraph docstrings at the top of a
|
||||
file are dead weight. Two short lines max.
|
||||
- **Conversation history.** No "user reported X", "screenshot showed
|
||||
Y", "v0.13.2 introduced Z". That belongs in commits / PR text.
|
||||
- **Section banners.** `// ─── helpers ───` is noise; group by export.
|
||||
- **Restated parameter docs.** If `function pad(f, top, right, bottom,
|
||||
left)`, no `@param top - top padding`.
|
||||
|
||||
If a comment is justified, **one line is almost always enough**.
|
||||
Comments needing 4+ lines usually mean the code itself needs to be
|
||||
clearer (rename, extract, simplify) before any comment is added.
|
||||
|
||||
### TypeScript
|
||||
|
||||
- Strict mode. No `any` without a `// biome-ignore` and a reason.
|
||||
- Prefer narrow types over option bags; if a function takes 5+
|
||||
optional flags, split the responsibilities.
|
||||
- Don't re-export types just so two files can share them — move the
|
||||
type to the file that owns the concept.
|
||||
|
||||
### Libraries over hand-rolled
|
||||
|
||||
If a problem has a well-maintained npm library, use it. Specific
|
||||
landmines this project has hit:
|
||||
|
||||
- Visual width / unicode width → `string-width`
|
||||
- Grapheme segmentation → `Intl.Segmenter`
|
||||
- ANSI strip → use what `string-width` ships with
|
||||
- Color → use `theme.ts` constants, not raw hex in component code
|
||||
|
||||
If a lib is missing a case, file the issue upstream and add a thin
|
||||
wrapper — don't fork a local table.
|
||||
|
||||
### Files
|
||||
|
||||
- One responsibility per file. New code goes in new files when an
|
||||
existing one is already large.
|
||||
- File header comment: zero or one line.
|
||||
- No `index.ts` re-exports unless they meaningfully shrink the
|
||||
public surface.
|
||||
- Don't create new `*.md` documentation files unless explicitly
|
||||
asked.
|
||||
|
||||
### Errors / fallbacks
|
||||
|
||||
- Don't add try/catch for "internal" errors. Trust your own code.
|
||||
- Don't validate things the type system already proves.
|
||||
- Boundary code (user input, network, FS) does validate; everything
|
||||
else trusts.
|
||||
- No "graceful fallback" silently masking bugs. Log + crash >
|
||||
silent wrong output.
|
||||
|
||||
### Tests
|
||||
|
||||
- Test what's hard to verify by reading the code: invariants, edge
|
||||
cases, regressions.
|
||||
- Don't test type signatures or that `function returns X` (the type
|
||||
system does that).
|
||||
- Don't write tests just to bump coverage.
|
||||
|
||||
### Git / commits
|
||||
|
||||
- Imperative mood, scope tag, why-not-what. See recent `git log`
|
||||
for the pattern (`feat(ui): …`, `fix(loop): …`, `chore(release):
|
||||
…`).
|
||||
- One logical change per commit; refactors land separately from
|
||||
features.
|
||||
- No `Co-Authored-By: Claude` trailer.
|
||||
|
||||
## PR expectations
|
||||
|
||||
- Branch off `main`. One logical change per PR.
|
||||
- `npm run verify` must pass locally (lint + typecheck + tests +
|
||||
comment-policy gate). Pre-push hook runs this; CI runs it on
|
||||
Node 20 and 22.
|
||||
- Update `CHANGELOG.md` under `## [Unreleased]` if user-visible.
|
||||
Maintainers move it under a versioned section at release time.
|
||||
|
||||
## Code review
|
||||
|
||||
Reasonix prefers blunt, fast review. Expect:
|
||||
|
||||
- Line-level pushback on comments that explain *what* instead of *why*.
|
||||
- Pushback on new abstractions / flags introduced before there are
|
||||
two real call sites.
|
||||
- Pushback on hand-rolled implementations of problems a maintained
|
||||
npm library already solves.
|
||||
|
||||
None of this is personal — it's how the codebase stays small.
|
||||
|
||||
## Releasing (maintainers)
|
||||
|
||||
1. Bump `package.json` version.
|
||||
2. Move `## [Unreleased]` → `## [X.Y.Z] — <date>` in `CHANGELOG.md`.
|
||||
3. `chore(release): X.Y.Z — <one-line summary>` commit.
|
||||
4. `git tag -a vX.Y.Z -m "..."`, push commit + tag.
|
||||
5. Wait for CI green, then `npm publish`.
|
||||
|
||||
## Reporting security issues
|
||||
|
||||
Don't open a public issue. Email <359807859@qq.com> with details and
|
||||
a reproduction; we'll respond within a few days.
|
||||
+11
-2
@@ -16,18 +16,27 @@ MIT-licensed. Node ≥20.10 required.
|
||||
|
||||
| Path | What |
|
||||
|---|---|
|
||||
| `src/` | All source — `mcp/`, `tools/`, `cli/`, `code/`, `repair/`, `index/` |
|
||||
| `src/cli/` | CLI entry + commands (`chat.tsx`, `code.tsx`, `diff.ts`, etc.) + Ink TUI in `ui/` |
|
||||
| `src/tools/` | Tool defs (filesystem, shell, MCP, plan, subagent, web, workspace) |
|
||||
| `src/mcp/` | MCP client, transports (stdio, SSE), registry, spec |
|
||||
| `src/repair/` | Tool-call repair pipeline (flatten, scavenge, storm, truncation) |
|
||||
| `src/index/` | Semantic vector index |
|
||||
| `src/code/` | SEARCH/REPLACE edit-block parser + apply gate |
|
||||
| `src/core/` | Event-log kernel — `events.ts` (Event union), `reducers.ts` (pure projections), `eventize.ts` |
|
||||
| `src/ports/` | Port interfaces — ModelClient, ToolHost, EventSink, MemoryStore, HookRunner, CheckpointStore |
|
||||
| `src/adapters/` | Concrete adapters for the ports (e.g. `event-sink-jsonl.ts`, `event-source-jsonl.ts`) |
|
||||
| `src/frame/` | Frame compiler (cell grid → ANSI) used by the TUI log renderer |
|
||||
| `src/memory/` | Project / session / user / runtime memory stores |
|
||||
| `src/transcript/` | Transcript log (write), diff, replay |
|
||||
| `src/telemetry/` | Usage records + cross-session stats |
|
||||
| `src/server/` | Dashboard HTTP server + REST API |
|
||||
| `tests/` | Vitest tests, flat `*.test.ts` |
|
||||
| `examples/` | `basic-chat.ts`, `mcp-server-demo.ts`, etc. |
|
||||
| `benchmarks/` | Harvest + tau-bench harnesses |
|
||||
| `dashboard/` | Compiled dashboard SPA assets |
|
||||
| `data/` | Tokenizer data (`deepseek-tokenizer.json.gz`) |
|
||||
| `dist/` | Build output — **do not edit** |
|
||||
| `.github/` | CI + issue templates |
|
||||
| `.github/` | CI + issue / PR templates |
|
||||
|
||||
## Commands
|
||||
|
||||
|
||||
Reference in new issue
Block a user