Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,20 @@ jobs:
npm test
npm run build

- name: Pack verified CLI tarball
run: |
mkdir -p release
package_version="${GITHUB_REF_NAME#v}"
npm pack --pack-destination release
tar -tzf "release/rulesync-${package_version}.tgz" >/dev/null
sha256sum "release/rulesync-${package_version}.tgz" > "release/rulesync-${package_version}.tgz.sha256"

- name: Create GitHub Release
uses: softprops/action-gh-release@v1
with:
files: dist/*
files: |
dist/*
release/*
draft: false
prerelease: false
env:
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,19 @@ All notable changes to `RuleSync` will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.2.0] - 2026-08-21

### Added

- `rulesync explain <path>` (Context Lens) predicts which canonical rules apply to a workspace file and shows each decision's source line, scope, and reason.
- Pretty, JSON, and Markdown Context Lens output for local review, CI, and pull requests.
- Verified release tarball attached to GitHub Releases for installation when the public npm `rulesync` name resolves to another project.

### Security

- Context Lens never prints rule bodies, calls a network, executes shell commands, or reads outside the workspace boundary.
- Output explicitly states that static scope prediction does not prove provider runtime loading or compliance.

## [1.1.0] - 2026-08-18

### Added
Expand Down
37 changes: 32 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,16 +52,23 @@
Try `RuleSync` immediately in any project without installation:

```bash
# Download the verified rulesync-1.2.0.tgz asset from GitHub Releases.
# The public npm name `rulesync` currently belongs to another project.
npm install --global ./rulesync-1.2.0.tgz

# 1. Bootstrap canonical AGENTS.md rule file and configuration
npx rulesync init
rulesync init

# 2. Lint your AI agent rules for conflicts, duplication, and token bloat
npx rulesync lint
# 2. Ask why a rule applies to one file
rulesync explain src/app.ts --target cursor

# 3. Cross-compile target instruction files for all installed AI tools
npx rulesync build
# 3. Lint and cross-compile target instruction files
rulesync lint
rulesync build
```

> **Package note:** `npx rulesync` is not safe before installing the release tarball because the npm registry name currently resolves to a different package. Each release includes a SHA-256 file beside the tarball so installation stays reviewable and offline after download.

### See exactly what your agent receives

Rule files can be synchronized and still be unclear at review time. `receipt` creates a local fingerprint for the canonical source and every compiled target:
Expand All @@ -79,6 +86,18 @@ npx rulesync receipt --check --format json --output .rulesync/context-receipt.js

Share the context ID in a pull request when someone asks, “Which instructions did the agent see?” A receipt fingerprints expected compiled bytes; it does not claim runtime loading.

### Context Lens: answer “why did this rule apply?”

`receipt` proves generated bytes are synchronized. `explain` answers the next question: **for this exact file, which rules are included, which are excluded, and which glob caused the decision?** It prints rule names and source lines, never rule bodies:

```bash
rulesync explain src/payments/checkout.ts --target cursor
rulesync explain tests/checkout.spec.ts --format markdown --output .rulesync/checkout-context.md
rulesync explain src/payments/checkout.ts --format json
```

Context Lens is a local static prediction. It does not claim that Cursor, Claude, Copilot, or another provider loaded or obeyed the resulting instructions at runtime.

---

## 🔍 Why RuleSync?
Expand Down Expand Up @@ -166,6 +185,14 @@ npx rulesync diff [--target cursor]
Creates a machine-readable, Markdown, or standalone HTML fingerprint of every configured target. `--check` exits with code `1` when a target is missing or drifted.
```bash
npx rulesync receipt [--format json|markdown|html] [--output <path>] [--check]

### `rulesync explain <path>`

Predict which canonical rules apply to one workspace-relative file. Use `--target` to show the generated target path and `--format pretty|json|markdown` for terminal, CI, or pull-request output.

```bash
rulesync explain src/index.ts --target claude
```
```

---
Expand Down
5 changes: 3 additions & 2 deletions SPECIFICATION.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# RuleSync Product Specification & Architecture (v1.0.0)
# RuleSync Product Specification & Architecture (v1.2.0)

## 1. Product Vision & Mission
`RuleSync` is an open-source CLI engine, static analyzer, and cross-format compiler for AI agent context instruction rules. It acts as the "ESLint & Babel for AI Agent Rules", allowing developers and engineering teams to maintain a single canonical source of truth (`AGENTS.md` or `.rulesync/`) and automatically compile, lint, optimize, and synchronize instructions across Cursor (`.cursor/rules/`), Anthropic Claude Code (`CLAUDE.md`), GitHub Copilot (`.github/copilot-instructions.md`), Cline / RooCode (`.cline/instructions.json`), Windsurf (`.windsurfrules`), and OpenCode.
Expand All @@ -25,6 +25,7 @@
| `rulesync check` | CI verification mode — checks if generated target files are up to date with source rules | `--quiet`, `--strict` |
| `rulesync watch` | File-system watcher mode — auto-compiles targets whenever source rule files change | `--debounce <ms>` |
| `rulesync diff` | Displays colorized diff preview between source rules and target compiled rule files | `--target <name>` |
| `rulesync explain <path>` | Predicts which canonical rules apply to one workspace file and records the source line, scope, and decision reason | `--target <name>`, `--format <pretty\|json\|markdown>` |

---

Expand Down Expand Up @@ -111,7 +112,7 @@
* **CLI UX**: Commander.js + Picocolors (Zero external bloat, sub-5ms boot time)
* **Build System**: Tsup / Esbuild (Single bundle CLI output + ESM/CJS exports)
* **Test Runner**: Vitest (Unit tests, compiler snapshots, linter matrix tests)
* **Distribution**: npm (`npx rulesync`), GitHub Releases binary, Homebrew formula template.
* **Distribution**: verified GitHub Release tarball (npm registry name collision documented), with future npm publication possible under owner-controlled credentials.

---

Expand Down
43 changes: 43 additions & 0 deletions docs/verification/context-lens-v1.2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Context Lens v1.2.0 verification record

Date: 2026-08-21 (America/Los_Angeles)

## Real execution

Input: this repository's canonical `AGENTS.md`, configured targets, and the workspace-relative path `src/cli.ts`.

```text
node dist/cli.js explain src/cli.ts --target cursor --format markdown

Summary: 2 applies · 1 excluded · 3 total
Code Style & Standards: applies, glob-match
Testing & Quality: excluded, glob-miss
Security & Privacy Guidelines: applies, unscoped
```

The JSON and Markdown reports expose rule names, source lines, scopes, statuses, and reasons. They do not print rule bodies. The report explicitly says it is a static scope prediction and does not prove provider runtime loading or compliance.

## TDD evidence

- RED: focused `tests/explain.test.ts` failed because `src/explain/index.js` did not exist.
- GREEN: focused suite passed 4/4 after the minimal Context Lens implementation.
- Regression coverage includes glob matches and misses, Windows path normalization, workspace traversal blocking, review-safe Markdown, and JSON output.

## Release gates

| Gate | Result |
| --- | --- |
| `npm test` | PASS — 7 files, 28 tests |
| `npm run typecheck` | PASS |
| `npm run lint` | PASS |
| `npm run build` | PASS — CJS, ESM, declarations |
| `npm audit --omit=dev` | PASS — 0 vulnerabilities |
| `npm pack --dry-run` | PASS — `rulesync-1.2.0.tgz` |
| Release tarball package smoke | PASS — installed tarball reports `1.2.0` and runs `explain` |
| `git diff --check` | PASS |

Local tarball SHA-256: `438eb2919ba1251ab8f72f22c2f58f88bcd6e3952999014267dc9306b93ba4a6`.

## Distribution boundary

The public npm package named `rulesync` currently resolves to `dyoshikawa/rulesync` v16.14.0, not this repository. v1.2.0 therefore ships a verified GitHub Release tarball for explicit installation; npm publication remains unavailable without an owner-controlled npm token.
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.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "rulesync",
"version": "1.1.0",
"version": "1.2.0",
"description": "The ESLint & Babel for AI Agent Rules — Compile, lint, optimize, and sync instructions across AGENTS.md, CLAUDE.md, .cursor/rules, and Copilot.",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
Expand Down
19 changes: 18 additions & 1 deletion src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,14 @@ import { handleCheck } from './commands/check.js';
import { handleWatch } from './commands/watch.js';
import { handleDiff } from './commands/diff.js';
import { handleReceipt } from './receipt/index.js';
import { handleExplain } from './explain/index.js';

const program = new Command();

program
.name('rulesync')
.description('The ESLint & Babel for AI Agent Rules — Compile, lint, optimize, and sync instructions across AGENTS.md, CLAUDE.md, .cursor/rules, and Copilot.')
.version('1.0.0');
.version('1.2.0');

program
.command('init')
Expand Down Expand Up @@ -120,4 +121,20 @@ program
}
});

program
.command('explain <path>')
.description('Explain which canonical rules apply to one workspace file')
.option('-t, --target <target>', 'Target to explain (claude | cursor | copilot | cline | windsurf | agents)')
.option('--format <format>', 'Output format (pretty | json | markdown)', 'pretty')
.option('-o, --output <path>', 'Write the explanation to an explicit workspace-relative path')
.action(async (inputPath, options) => {
try {
const success = handleExplain(inputPath, options);
if (!success) process.exit(1);
} catch (err: any) {
console.error(pc.red(`??Explain failed: ${err.message}`));
process.exit(1);
}
});

program.parse(process.argv);
Loading
Loading