@serdaraytac/agentsitter 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +91 -0
- package/README.md +349 -0
- package/dist/analyzer.d.ts +78 -0
- package/dist/analyzer.d.ts.map +1 -0
- package/dist/analyzer.js +815 -0
- package/dist/analyzer.js.map +1 -0
- package/dist/browser.d.ts +5 -0
- package/dist/browser.d.ts.map +1 -0
- package/dist/browser.js +5 -0
- package/dist/browser.js.map +1 -0
- package/dist/mcp-server.d.ts +3 -0
- package/dist/mcp-server.d.ts.map +1 -0
- package/dist/mcp-server.js +323 -0
- package/dist/mcp-server.js.map +1 -0
- package/dist/optimizer.d.ts +9 -0
- package/dist/optimizer.d.ts.map +1 -0
- package/dist/optimizer.js +345 -0
- package/dist/optimizer.js.map +1 -0
- package/dist/parser.d.ts +20 -0
- package/dist/parser.d.ts.map +1 -0
- package/dist/parser.js +115 -0
- package/dist/parser.js.map +1 -0
- package/dist/platforms.d.ts +12 -0
- package/dist/platforms.d.ts.map +1 -0
- package/dist/platforms.js +143 -0
- package/dist/platforms.js.map +1 -0
- package/dist/scorer.d.ts +14 -0
- package/dist/scorer.d.ts.map +1 -0
- package/dist/scorer.js +124 -0
- package/dist/scorer.js.map +1 -0
- package/package.json +56 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
Elastic License 2.0
|
|
2
|
+
|
|
3
|
+
URL: https://www.elastic.co/licensing/elastic-license
|
|
4
|
+
|
|
5
|
+
## Acceptance
|
|
6
|
+
|
|
7
|
+
By using the software, you agree to all of the terms and conditions below.
|
|
8
|
+
|
|
9
|
+
## Copyright License
|
|
10
|
+
|
|
11
|
+
The licensor grants you a non-exclusive, royalty-free, worldwide,
|
|
12
|
+
non-sublicensable, non-transferable license to use, copy, distribute, make
|
|
13
|
+
available, and prepare derivative works of the software, in each case subject
|
|
14
|
+
to the limitations and conditions below.
|
|
15
|
+
|
|
16
|
+
## Limitations
|
|
17
|
+
|
|
18
|
+
You may not provide the software to third parties as a hosted or managed
|
|
19
|
+
service, where the service provides users with access to any substantial set of
|
|
20
|
+
the features or functionality of the software.
|
|
21
|
+
|
|
22
|
+
You may not move, change, disable, or circumvent the license key functionality
|
|
23
|
+
in the software, and you may not remove or obscure any functionality in the
|
|
24
|
+
software that is protected by the license key.
|
|
25
|
+
|
|
26
|
+
You may not alter, remove, or obscure any licensing, copyright, or other
|
|
27
|
+
notices of the licensor in the software. Any use of the licensor's trademarks
|
|
28
|
+
is subject to applicable law.
|
|
29
|
+
|
|
30
|
+
## Patents
|
|
31
|
+
|
|
32
|
+
The licensor grants you a license, under any patent claims the licensor can
|
|
33
|
+
license, or becomes able to license, to make, have made, use, sell, offer for
|
|
34
|
+
sale, import and otherwise run, modify and propagate the contents of this
|
|
35
|
+
software. This license does not cover any patent claims that you cause to be
|
|
36
|
+
infringed by modifications or additions to the software. If you or your company
|
|
37
|
+
make any written claim that the software infringes or contributes to
|
|
38
|
+
infringement of any patent, your patent license for the software granted under
|
|
39
|
+
these terms ends immediately.
|
|
40
|
+
|
|
41
|
+
## Notices
|
|
42
|
+
|
|
43
|
+
You must ensure that anyone who gets a copy of any part of the software from
|
|
44
|
+
you also gets a copy of these terms.
|
|
45
|
+
|
|
46
|
+
If you modify the software, you must include in any modified copies of the
|
|
47
|
+
software prominent notices stating that you have modified the software.
|
|
48
|
+
|
|
49
|
+
## No Other Rights
|
|
50
|
+
|
|
51
|
+
These terms do not imply any licenses other than those expressly granted in
|
|
52
|
+
these terms.
|
|
53
|
+
|
|
54
|
+
## Termination
|
|
55
|
+
|
|
56
|
+
If you use the software in violation of these terms, such use is not licensed,
|
|
57
|
+
and your licenses will automatically terminate. If the licensor provides you
|
|
58
|
+
with a notice of your violation, and you cease all violation of this license no
|
|
59
|
+
later than 30 days after you receive that notice, your licenses will be
|
|
60
|
+
reinstated retroactively. However, if you violate these terms after such
|
|
61
|
+
reinstatement, any additional violation of these terms will cause your licenses
|
|
62
|
+
to terminate automatically and permanently.
|
|
63
|
+
|
|
64
|
+
## No Liability
|
|
65
|
+
|
|
66
|
+
As far as the law allows, the software comes as is, without any warranty or
|
|
67
|
+
condition, and the licensor will not be liable to you for any damages arising
|
|
68
|
+
out of these terms or the use or nature of the software, under any kind of
|
|
69
|
+
legal claim.
|
|
70
|
+
|
|
71
|
+
## Definitions
|
|
72
|
+
|
|
73
|
+
The "licensor" is the entity offering these terms, and the "software" is the
|
|
74
|
+
software the licensor makes available under these terms, including any portion
|
|
75
|
+
of it.
|
|
76
|
+
|
|
77
|
+
"you" refers to the individual or entity agreeing to these terms.
|
|
78
|
+
|
|
79
|
+
"your company" is any legal entity, sole proprietorship, or other kind of
|
|
80
|
+
organization that you work for, plus all organizations that have control over,
|
|
81
|
+
are under the control of, or are under common control with that organization.
|
|
82
|
+
"control" means ownership of substantially all the assets of an entity, or the
|
|
83
|
+
power to direct its management and legal affairs.
|
|
84
|
+
|
|
85
|
+
"your licenses" are all the licenses granted to you for the software under
|
|
86
|
+
these terms.
|
|
87
|
+
|
|
88
|
+
"use" includes any use of the software, including as the basis of a product or
|
|
89
|
+
service.
|
|
90
|
+
|
|
91
|
+
"trademark" means any trademark, service mark, or similar right.
|
package/README.md
ADDED
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
# Agentsitter
|
|
2
|
+
|
|
3
|
+
**Your AI agent is ignoring your rules — and you don’t even know it.**
|
|
4
|
+
|
|
5
|
+
agentsitter finds why, scores it, and fixes it automatically.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## The Problem
|
|
10
|
+
|
|
11
|
+
AI coding agents don’t follow your rules.
|
|
12
|
+
|
|
13
|
+
Not because they’re bad —
|
|
14
|
+
because your config files are.
|
|
15
|
+
|
|
16
|
+
- "Follow best practices" → meaningless to LLMs
|
|
17
|
+
- Wrong frontmatter → rules never activate
|
|
18
|
+
- Files too large → silently truncated
|
|
19
|
+
- Missing sections → incomplete behavior
|
|
20
|
+
- Platform differences → inconsistent outputs
|
|
21
|
+
|
|
22
|
+
👉 You think your agent is broken
|
|
23
|
+
👉 But your config is
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## What Agentsitter does
|
|
28
|
+
|
|
29
|
+
agentsitter analyzes your AI agent configs and fixes them.
|
|
30
|
+
|
|
31
|
+
- **Scores** configs (0–100) across clarity, structure, token efficiency, coverage
|
|
32
|
+
- **Detects vague rules** LLMs can’t execute
|
|
33
|
+
- **Finds platform-specific bugs** (Cursor, Codex, Copilot, Cline, etc.)
|
|
34
|
+
- **Auto-fixes issues** — not just warnings
|
|
35
|
+
- **Optimizes token usage** and estimates cost
|
|
36
|
+
|
|
37
|
+
Works across **13 platforms**.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Example
|
|
42
|
+
|
|
43
|
+
Before:
|
|
44
|
+
|
|
45
|
+
```md
|
|
46
|
+
Follow best practices.
|
|
47
|
+
Handle errors properly.
|
|
48
|
+
Write clean code.
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Run:
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
optimize_config { "filepath": "./backend.md", "write": true }
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Output:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
Score: 29 (F)
|
|
61
|
+
- 3 vague rules
|
|
62
|
+
- 1 missing section
|
|
63
|
+
- 1 duplicate
|
|
64
|
+
|
|
65
|
+
✨ Fixed → Score: 68 (C)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
After:
|
|
69
|
+
|
|
70
|
+
```md
|
|
71
|
+
- follow the conventions defined in this file
|
|
72
|
+
- handle errors by [TODO: define strategy]
|
|
73
|
+
- easy to extend without modifying existing functions
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Why this matters
|
|
79
|
+
|
|
80
|
+
Bad configs = bad AI output.
|
|
81
|
+
|
|
82
|
+
- ❌ Unpredictable code
|
|
83
|
+
- ❌ Ignored instructions
|
|
84
|
+
- ❌ Wasted tokens
|
|
85
|
+
- ❌ Hidden platform bugs
|
|
86
|
+
|
|
87
|
+
Good configs = controllable AI.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Quick Start
|
|
92
|
+
|
|
93
|
+
**Claude Code (one command):**
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
claude mcp add agentsitter -- npx -y @serdaraytac/agentsitter
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Restart Claude Code, then verify the install:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
scan_project { "directory": "." }
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
In Claude Code, type these in the chat window:
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
analyze_config { "filepath": "./AGENTS.md" }
|
|
109
|
+
optimize_config { "filepath": "./AGENTS.md", "write": true }
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
**Other clients — add to your MCP config:**
|
|
113
|
+
|
|
114
|
+
```json
|
|
115
|
+
{
|
|
116
|
+
"mcpServers": {
|
|
117
|
+
"agentsitter": {
|
|
118
|
+
"command": "npx",
|
|
119
|
+
"args": ["-y", "@serdaraytac/agentsitter"]
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**MCP config location by client:**
|
|
126
|
+
|
|
127
|
+
| Client | Config file |
|
|
128
|
+
|---|---|
|
|
129
|
+
| Claude Code | `claude mcp add agentsitter -- npx -y @serdaraytac/agentsitter` |
|
|
130
|
+
| Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` |
|
|
131
|
+
| Cline | VS Code settings → Cline MCP Servers |
|
|
132
|
+
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
|
|
133
|
+
| Gemini CLI | `~/.gemini/settings.json` under `mcpServers` |
|
|
134
|
+
| OpenCode | `opencode.json` under `"mcp"` key |
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Supported Platforms
|
|
139
|
+
|
|
140
|
+
Cursor · Codex · Copilot · Claude Code · Gemini CLI · Cline · Windsurf · OpenCode · Amp · Kimi · Warp · Antigravity · Firebender
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## What it catches
|
|
145
|
+
|
|
146
|
+
- Vague rules ("best practices", "clean code")
|
|
147
|
+
- Silent truncation (Codex 32KB limit)
|
|
148
|
+
- Wrong frontmatter keys (Cursor vs Cline mismatch)
|
|
149
|
+
- Missing scope definitions
|
|
150
|
+
- Invalid imports (Gemini CLI)
|
|
151
|
+
- Duplicate or conflicting rules
|
|
152
|
+
|
|
153
|
+
### Platform-specific checks
|
|
154
|
+
|
|
155
|
+
Every check comes from official documentation — not guesswork.
|
|
156
|
+
|
|
157
|
+
**Claude Code**
|
|
158
|
+
- `CLAUDE_MISSING_BUILD_COMMANDS` — no build, test, or lint commands found; without them Claude discovers commands by reading `package.json` on every session (warning)
|
|
159
|
+
- `CLAUDE_COMMANDS_NOT_IN_BLOCK` — commands exist but are outside fenced code blocks; Claude Code parses fenced blocks for runnable commands
|
|
160
|
+
- `CLAUDE_PLACEHOLDER_FOUND` — unfilled `[TODO:]` markers left in production config; incomplete directives are worse than omission — the model cannot act on them (warning)
|
|
161
|
+
- `CLAUDE_IMPORT_IN_CODE_BLOCK` — `@`-imports inside fenced code blocks are treated as literal text, not resolved
|
|
162
|
+
- `CLAUDE_SUBDIR_SPLIT_RECOMMENDED` — file over 10 KB with no `@`-imports; Claude Code loads `CLAUDE.md` from every directory it navigates to — split into subdirectory files to reduce per-context token cost
|
|
163
|
+
- **Scorer:** missing build commands carries an extra coverage penalty — runnable commands are the highest-value addition to any `CLAUDE.md`
|
|
164
|
+
- **Optimizer:** adds `## Commands` section with a bash code block stub when commands are missing; flags unfilled `[TODO:]` placeholders with a count
|
|
165
|
+
|
|
166
|
+
**Cursor**
|
|
167
|
+
- `CURSOR_MISSING_FRONTMATTER` — `.cursor/rules/` files without YAML frontmatter lose scope control entirely; rule applies to nothing
|
|
168
|
+
- `CURSOR_CURSORRULES_LEGACY` — `.cursorrules` is no longer documented at cursor.com/docs; migrate to `.cursor/rules/*.md`
|
|
169
|
+
- `CURSOR_RULE_TOO_LONG` — files over 500 lines; Cursor docs recommend splitting into focused files
|
|
170
|
+
- `CURSOR_UNKNOWN_FRONTMATTER_KEY` — only `description`, `globs`, `alwaysApply` are recognized; unknown keys silently ignored
|
|
171
|
+
- **Optimizer:** auto-adds frontmatter stub with `description`, `globs`, `alwaysApply` fields
|
|
172
|
+
|
|
173
|
+
**Codex**
|
|
174
|
+
- `CODEX_SIZE_LIMIT` — hard 32 KiB truncation confirmed in [codex-rs source](https://github.com/openai/codex); content beyond it is silently dropped
|
|
175
|
+
- `CODEX_OVERRIDE_FILE_AVAILABLE` — `AGENTS.override.md` at the same directory takes precedence over `AGENTS.md` (shown for large files)
|
|
176
|
+
- **Scorer:** separate penalty for files approaching or exceeding the 32 KiB hard limit — silent truncation is more dangerous than verbosity
|
|
177
|
+
|
|
178
|
+
**GitHub Copilot**
|
|
179
|
+
- `COPILOT_WRONG_LOCATION` — `copilot-instructions.md` outside `.github/` is not recognized (critical)
|
|
180
|
+
- `COPILOT_INSTRUCTIONS_WRONG_EXTENSION` — files in `.github/instructions/` must end with `.instructions.md`
|
|
181
|
+
- `COPILOT_INSTRUCTIONS_MISSING_APPLY_TO` — path-specific instruction files without `applyTo:` apply repository-wide unintentionally
|
|
182
|
+
- `COPILOT_INVALID_EXCLUDE_AGENT` — `excludeAgent` only accepts `"code-review"` or `"cloud-agent"`
|
|
183
|
+
- **Optimizer:** auto-adds `applyTo:` frontmatter stub to path-specific files missing it
|
|
184
|
+
|
|
185
|
+
**Gemini CLI**
|
|
186
|
+
- `GEMINI_LARGE_NO_IMPORTS` — files over 10 KB with no `@`-imports; Gemini CLI supports `@./path.md` with up to 5 recursion levels
|
|
187
|
+
- `GEMINI_IMPORT_IN_CODE_BLOCK` — `@`-imports inside fenced code blocks are silently ignored
|
|
188
|
+
- `GEMINI_IMPORT_INVALID_PATH` — imports must use `@./`, `@../`, `@/`, or `@~/`; bare `@word` is not resolved
|
|
189
|
+
- **Optimizer:** fixes invalid `@path` → `@./path` automatically
|
|
190
|
+
|
|
191
|
+
**Cline**
|
|
192
|
+
- `CLINE_WRONG_FRONTMATTER_KEY` — Cline uses `paths:` for glob scoping, not `globs:` (Cursor's key); `globs:` is silently ignored
|
|
193
|
+
- `CLINE_UNSUPPORTED_EXTENSION` — only `.md` and `.txt` are processed from `.clinerules/`; others silently ignored
|
|
194
|
+
- `CLINE_EMPTY_PATHS` — `paths: []` means the rule never activates
|
|
195
|
+
- `CLINE_AT_IMPORT_NOT_SUPPORTED` — `@`-import syntax not supported; split rules into `.clinerules/` directory instead
|
|
196
|
+
- **Optimizer:** converts unstructured prose to bullet list format
|
|
197
|
+
|
|
198
|
+
**Amp**
|
|
199
|
+
- `AMP_INCORRECT_FILENAME` — `.amp/instructions.md` is not recognized; use `AGENTS.md` at project root
|
|
200
|
+
- `AMP_IMPORT_IMPLICIT_RECURSIVE` — paths without `./` or `../` prefix get `**/` prepended implicitly, matching files across the entire project
|
|
201
|
+
- `AMP_IMPORT_IN_CODE_BLOCK` — `@`-mentions inside fenced code blocks are silently ignored
|
|
202
|
+
- **Optimizer:** fixes bare `@path` → `@./path` to prevent unintended recursive matching
|
|
203
|
+
|
|
204
|
+
**OpenCode**
|
|
205
|
+
- `OPENCODE_PREFERS_AGENTS_MD` — `CLAUDE.md` works as a fallback but `AGENTS.md` is the preferred filename
|
|
206
|
+
- `OPENCODE_AT_IMPORT_NOT_SUPPORTED` — `@`-import syntax not supported; use the `"instructions"` field in `opencode.json` instead
|
|
207
|
+
|
|
208
|
+
### Vagueness detection
|
|
209
|
+
|
|
210
|
+
7 linguistic categories, each with its own penalty weight:
|
|
211
|
+
|
|
212
|
+
| Category | Penalty | Example |
|
|
213
|
+
|---|---|---|
|
|
214
|
+
| `false-shared-context` | −7 | "follow best practices", "industry standard" |
|
|
215
|
+
| `outcome-without-criterion` | −6 | "ensure quality", "handle errors properly" |
|
|
216
|
+
| `unmeasurable-quality` | −5 | "elegant", "robust", "well-written" |
|
|
217
|
+
| `passive-voice` | −5 | "errors should be handled", "tests need to be written" |
|
|
218
|
+
| `comparative-without-baseline` | −4 | "as simple as possible", "improve performance" |
|
|
219
|
+
| `vague-condition` | −3 | "when necessary", "in most cases", "for large files" |
|
|
220
|
+
| `weak-obligation` | −2 | "try to", "ideally", "consider using" |
|
|
221
|
+
|
|
222
|
+
The optimizer doesn't just flag — it rewrites:
|
|
223
|
+
|
|
224
|
+
| Before | After |
|
|
225
|
+
|---|---|
|
|
226
|
+
| `follow best practices` | `follow the conventions defined in this file` |
|
|
227
|
+
| `ensure quality` | `verify quality via tests and linting` |
|
|
228
|
+
| `errors should be handled` | `must [TODO: specify who performs this action and how]` |
|
|
229
|
+
| `try to write tests` | `[TODO: use 'always' if required, or remove if optional]` |
|
|
230
|
+
| `in most cases prefer X` | `always prefer X, except when [TODO: list the explicit exceptions]` |
|
|
231
|
+
| `for large files` | `for files exceeding [TODO: specify a threshold, e.g. 300 lines]` |
|
|
232
|
+
|
|
233
|
+
`[TODO: ...]` markers are inserted where the correct fix depends on project-specific context the tool cannot infer automatically.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## How it works
|
|
238
|
+
|
|
239
|
+
agentsitter combines:
|
|
240
|
+
|
|
241
|
+
- Linguistic analysis (7 vagueness categories)
|
|
242
|
+
- Platform-specific validation rules
|
|
243
|
+
- Token-aware optimization
|
|
244
|
+
- Auto-rewriting engine
|
|
245
|
+
|
|
246
|
+
### Scoring
|
|
247
|
+
|
|
248
|
+
| Category | Max | What it measures |
|
|
249
|
+
|---|---|---|
|
|
250
|
+
| **Clarity** | 25 | Absence of vague directives; penalties scaled by platform sensitivity |
|
|
251
|
+
| **Structure** | 25 | Heading usage, section organization, platform-specific format compliance |
|
|
252
|
+
| **Token Efficiency** | 25 | File size vs. platform context window; hard-limit awareness |
|
|
253
|
+
| **Coverage** | 25 | Expected sections present; critical rules at head/tail |
|
|
254
|
+
|
|
255
|
+
| Score | Grade | |
|
|
256
|
+
|---|---|---|
|
|
257
|
+
| 90–100 | A | Production-ready |
|
|
258
|
+
| 75–89 | B | Minor improvements available |
|
|
259
|
+
| 60–74 | C | Multiple vague or missing sections |
|
|
260
|
+
| 40–59 | D | Significant clarity or structure problems |
|
|
261
|
+
| 0–39 | F | Major overhaul needed |
|
|
262
|
+
|
|
263
|
+
**Sensitivity** multiplies vagueness penalties per platform. Codex (1.3×) and Cursor/Copilot (1.2×) score stricter — GPT-4.1 follows instructions more literally, so the same vague rule causes more damage there.
|
|
264
|
+
|
|
265
|
+
Token efficiency penalizes both extremes. Thresholds scale with the platform's context window: a 4,000-token config is fine for Gemini CLI (1M tokens), but triggers a warning on OpenCode (131k). Codex gets an additional penalty for approaching its hard 32 KiB truncation limit.
|
|
266
|
+
|
|
267
|
+
### Tools
|
|
268
|
+
|
|
269
|
+
```
|
|
270
|
+
scan_project → find all config files in the repo
|
|
271
|
+
analyze_config → score each file, see what's wrong
|
|
272
|
+
optimize_config → fix issues automatically, write back to disk
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
`scan_project` finds files inside `.cursor/rules/`, `.clinerules/`, `.github/instructions/`, `.gemini/`, `.warp/`, `.amp/`, and `.antigravity/` — not just root-level files. It scans one level deep by default; symlinks are not followed.
|
|
276
|
+
|
|
277
|
+
`analyze_config` accepts a filepath or inline content:
|
|
278
|
+
|
|
279
|
+
```json
|
|
280
|
+
{ "filename": ".clinerules", "content": "# Rules\n..." }
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
`optimize_config` returns the fixed content with a before/after score. Add `"write": true` to save to disk.
|
|
284
|
+
|
|
285
|
+
`optimize_config` response shape:
|
|
286
|
+
|
|
287
|
+
```json
|
|
288
|
+
{
|
|
289
|
+
"platform": "claude",
|
|
290
|
+
"before": { "overall": 29, "grade": "F" },
|
|
291
|
+
"after": { "overall": 68, "grade": "C" },
|
|
292
|
+
"changesSummary": ["Rewrote 3 vague rules", "Added Commands section"],
|
|
293
|
+
"optimizedContent": "# CLAUDE.md\n..."
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
If a file path is not found, tools return:
|
|
298
|
+
|
|
299
|
+
```json
|
|
300
|
+
{ "error": "File not found: ./CLAUDE.md" }
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
---
|
|
304
|
+
|
|
305
|
+
## Try it
|
|
306
|
+
|
|
307
|
+
Run `analyze_config` on your config:
|
|
308
|
+
|
|
309
|
+
```
|
|
310
|
+
analyze_config { "filepath": "./CLAUDE.md" }
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
```json
|
|
314
|
+
{
|
|
315
|
+
"platform": "claude",
|
|
316
|
+
"score": {
|
|
317
|
+
"overall": 62,
|
|
318
|
+
"grade": "C",
|
|
319
|
+
"categories": {
|
|
320
|
+
"clarity": 13,
|
|
321
|
+
"structure": 20,
|
|
322
|
+
"tokenEfficiency": 22,
|
|
323
|
+
"coverage": 7
|
|
324
|
+
}
|
|
325
|
+
},
|
|
326
|
+
"issues": [
|
|
327
|
+
{ "code": "VAGUE_RULE", "severity": "warning", "message": "[false-shared-context] 'Best practices' is undefined — LLM fills the gap with its own assumptions", "line": 4 },
|
|
328
|
+
{ "code": "VAGUE_RULE", "severity": "warning", "message": "[weak-obligation] 'Try to keep functions small' — use 'always' or remove", "line": 9 },
|
|
329
|
+
{ "code": "MISSING_SECTION", "severity": "info", "message": "Missing expected sections for Claude Code: commands, architecture" }
|
|
330
|
+
]
|
|
331
|
+
}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
Then `optimize_config` to fix it automatically.
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
## Roadmap
|
|
339
|
+
|
|
340
|
+
- GitHub Actions integration
|
|
341
|
+
- VS Code extension
|
|
342
|
+
- Multi-file rule conflict detection
|
|
343
|
+
- Custom scoring weights
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## License
|
|
348
|
+
|
|
349
|
+
Elastic License 2.0
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import type { ParsedConfig, Platform } from "./parser.js";
|
|
2
|
+
import { type PlatformProfile } from "./platforms.js";
|
|
3
|
+
export type Severity = "critical" | "warning" | "info";
|
|
4
|
+
export interface Issue {
|
|
5
|
+
code: string;
|
|
6
|
+
severity: Severity;
|
|
7
|
+
message: string;
|
|
8
|
+
line?: number;
|
|
9
|
+
context?: string;
|
|
10
|
+
}
|
|
11
|
+
export interface AnalysisResult {
|
|
12
|
+
platform: Platform;
|
|
13
|
+
tokenCount: number;
|
|
14
|
+
estimatedCostUsd: number;
|
|
15
|
+
issues: Issue[];
|
|
16
|
+
checks: {
|
|
17
|
+
tokenCost: TokenCostResult;
|
|
18
|
+
vagueRules: VagueRulesResult;
|
|
19
|
+
missingSections: MissingSectionsResult;
|
|
20
|
+
duplicates: DuplicatesResult;
|
|
21
|
+
attentionPlacement: AttentionPlacementResult;
|
|
22
|
+
structure: StructureResult;
|
|
23
|
+
formatCompliance: FormatComplianceResult;
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
export interface TokenCostResult {
|
|
27
|
+
charCount: number;
|
|
28
|
+
tokenCount: number;
|
|
29
|
+
estimatedCostUsd: number;
|
|
30
|
+
costPerSession: number;
|
|
31
|
+
}
|
|
32
|
+
export type VagueCategory = "unmeasurable-quality" | "false-shared-context" | "passive-voice" | "weak-obligation" | "vague-condition" | "comparative-without-baseline" | "outcome-without-criterion";
|
|
33
|
+
export interface VagueLine {
|
|
34
|
+
line: number;
|
|
35
|
+
text: string;
|
|
36
|
+
reason: string;
|
|
37
|
+
category: VagueCategory;
|
|
38
|
+
}
|
|
39
|
+
export interface VagueRulesResult {
|
|
40
|
+
vagueLines: VagueLine[];
|
|
41
|
+
}
|
|
42
|
+
export interface MissingSectionsResult {
|
|
43
|
+
missing: string[];
|
|
44
|
+
present: string[];
|
|
45
|
+
}
|
|
46
|
+
export interface DuplicatesResult {
|
|
47
|
+
duplicatePhrases: Array<{
|
|
48
|
+
phrase: string;
|
|
49
|
+
occurrences: number;
|
|
50
|
+
lines: number[];
|
|
51
|
+
}>;
|
|
52
|
+
}
|
|
53
|
+
export interface AttentionPlacementResult {
|
|
54
|
+
criticalInHead: boolean;
|
|
55
|
+
criticalInTail: boolean;
|
|
56
|
+
headLines: string[];
|
|
57
|
+
tailLines: string[];
|
|
58
|
+
suggestions: string[];
|
|
59
|
+
}
|
|
60
|
+
export interface StructureResult {
|
|
61
|
+
hasHeadings: boolean;
|
|
62
|
+
headingCount: number;
|
|
63
|
+
maxDepth: number;
|
|
64
|
+
longParagraphLines: number[];
|
|
65
|
+
unorganizedRuleCount: number;
|
|
66
|
+
}
|
|
67
|
+
export interface FormatComplianceResult {
|
|
68
|
+
issues: Issue[];
|
|
69
|
+
}
|
|
70
|
+
export declare function analyzeTokenCost(config: ParsedConfig, profile?: PlatformProfile): TokenCostResult;
|
|
71
|
+
export declare function analyzeVagueRules(config: ParsedConfig): VagueRulesResult;
|
|
72
|
+
export declare function analyzeMissingSections(config: ParsedConfig, profile?: PlatformProfile): MissingSectionsResult;
|
|
73
|
+
export declare function analyzeDuplicates(config: ParsedConfig): DuplicatesResult;
|
|
74
|
+
export declare function analyzeAttentionPlacement(config: ParsedConfig): AttentionPlacementResult;
|
|
75
|
+
export declare function analyzeStructure(config: ParsedConfig): StructureResult;
|
|
76
|
+
export declare function analyzeFormatCompliance(config: ParsedConfig): FormatComplianceResult;
|
|
77
|
+
export declare function analyze(config: ParsedConfig): AnalysisResult;
|
|
78
|
+
//# sourceMappingURL=analyzer.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"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"}
|