@parseme/cli 0.0.6 → 0.1.0
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/README.md +402 -136
- package/dist/cli/cli.js +7 -1
- package/dist/core/context-builder.js +1 -1
- package/dist/core/generator.js +6 -2
- package/package.json +10 -5
package/README.md
CHANGED
|
@@ -1,16 +1,43 @@
|
|
|
1
1
|
# PARSEME
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Local code analysis and context generation to improve token efficiency of AI Coding agents
|
|
4
|
+
Cross-project access via Cloud MCP**
|
|
4
5
|
|
|
5
6
|
PARSEME analyzes your TypeScript/JavaScript projects and generates a PARSEME.md file—a README.md for AI agents. This file provides comprehensive context documentation that helps AI assistants understand your codebase structure, architecture, and patterns. By providing persistent, reusable context, PARSEME prevents AI agents from repeatedly analyzing your codebase from scratch—saving valuable tokens and improving efficiency for every interaction.
|
|
6
7
|
|
|
8
|
+
## Table of Contents
|
|
9
|
+
|
|
10
|
+
- [Development Status](#development-status)
|
|
11
|
+
- [Features](#features)
|
|
12
|
+
- [What PARSEME Detects](#what-parseme-detects)
|
|
13
|
+
- [Language Support](#language-support)
|
|
14
|
+
- [Supported Projects](#supported-projects)
|
|
15
|
+
- [Installation](#installation)
|
|
16
|
+
- [Quick Start](#quick-start)
|
|
17
|
+
- [Automation Options](#automation-options)
|
|
18
|
+
- [Option 1: Manual Execution](#option-1-manual-execution)
|
|
19
|
+
- [Option 2: Automatic Local Generation](#option-2-automatic-local-generation)
|
|
20
|
+
- [Option 3: Automatic Local and Remote Generation (Advanced Git Hooks)](#option-3-automatic-local-and-remote-generation-advanced-git-hooks)
|
|
21
|
+
- [Option 4: GitHub Actions for Remote Generation paired with Local Generation](#option-4-github-actions-for-remote-generation-paired-with-local-generation)
|
|
22
|
+
- [Configuration](#configuration)
|
|
23
|
+
- [Configuration File Formats & Priority](#configuration-file-formats--priority)
|
|
24
|
+
- [Configuration Priority](#configuration-priority)
|
|
25
|
+
- [Configuration Options](#configuration-options)
|
|
26
|
+
- [CLI Options](#cli-options)
|
|
27
|
+
- [Interactive Configuration](#interactive-configuration)
|
|
28
|
+
- [CLI Commands](#cli-commands)
|
|
29
|
+
- [Programmatic API](#programmatic-api)
|
|
30
|
+
- [Output Format](#output-format)
|
|
31
|
+
- [AI Agent Integration](#ai-agent-integration)
|
|
32
|
+
- [Requirements](#requirements)
|
|
33
|
+
- [License](#license)
|
|
34
|
+
|
|
7
35
|
## Development Status
|
|
8
36
|
|
|
9
|
-
**This project is currently in active development
|
|
37
|
+
**This project is currently in active development.**
|
|
10
38
|
|
|
11
39
|
The core functionality is working, but expect:
|
|
12
40
|
|
|
13
|
-
- Breaking changes in configuration format
|
|
14
41
|
- API modifications as the interface gets refined
|
|
15
42
|
- Additional features being added regularly
|
|
16
43
|
- Possible bugs and edge cases
|
|
@@ -88,6 +115,8 @@ PARSEME aims to automatically analyse any JavaScript or TypeScript project like:
|
|
|
88
115
|
- **Desktop apps** - Main processes, renderers, IPC handlers
|
|
89
116
|
- **Testing utilities** - Test functions, mocks, utilities, custom matchers
|
|
90
117
|
|
|
118
|
+
**Note:** PARSEME provides specialized analysis for **Express.js**, **NestJS**, and **Fastify**, including route detection, middleware identification, and decorator analysis. All other frameworks benefit from universal AST-based analysis.
|
|
119
|
+
|
|
91
120
|
## Installation
|
|
92
121
|
|
|
93
122
|
```bash
|
|
@@ -114,21 +143,10 @@ npm install --save-dev parseme
|
|
|
114
143
|
- How to add parseme script to package.json
|
|
115
144
|
- How to integrate with git hooks
|
|
116
145
|
- README section to help AI agents find context
|
|
146
|
+
- AI agent configuration files to reference PARSEME.md
|
|
117
147
|
|
|
118
|
-
2. **
|
|
119
|
-
|
|
120
|
-
```json
|
|
121
|
-
{
|
|
122
|
-
"scripts": {
|
|
123
|
-
"parseme": "parseme generate"
|
|
124
|
-
}
|
|
125
|
-
}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
3. **Generate context**:
|
|
148
|
+
2. **Generate context**:
|
|
129
149
|
```bash
|
|
130
|
-
npm run parseme
|
|
131
|
-
# or
|
|
132
150
|
npx parseme generate
|
|
133
151
|
# or use the alias
|
|
134
152
|
npx parseme g
|
|
@@ -137,7 +155,317 @@ npm install --save-dev parseme
|
|
|
137
155
|
This creates:
|
|
138
156
|
|
|
139
157
|
- `PARSEME.md` - Main overview with links to context files
|
|
140
|
-
- `parseme-context/` - Structured data files (
|
|
158
|
+
- `parseme-context/` - Structured data files (file list, AST structure, routes, git diff)
|
|
159
|
+
|
|
160
|
+
## Automation Options
|
|
161
|
+
|
|
162
|
+
PARSEME can be integrated into your workflow in several ways, from manual execution to fully automated generation. Choose the approach that best fits your needs:
|
|
163
|
+
|
|
164
|
+
### Option 1: Manual Execution
|
|
165
|
+
|
|
166
|
+
Run parseme manually whenever you need updated context.
|
|
167
|
+
|
|
168
|
+
**Setup:**
|
|
169
|
+
|
|
170
|
+
Add to your `package.json` scripts (optional, for convenience):
|
|
171
|
+
|
|
172
|
+
```json
|
|
173
|
+
{
|
|
174
|
+
"scripts": {
|
|
175
|
+
"parseme": "parseme generate"
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
**Usage:**
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
npm run parseme
|
|
184
|
+
# or directly
|
|
185
|
+
npx parseme generate
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**Best for:** Small projects, occasional updates, or when you prefer full control over when context is generated.
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
### Option 2: Automatic Local Generation
|
|
193
|
+
|
|
194
|
+
Automatically generate parseme files locally after every commit. Files are committed to the repository.
|
|
195
|
+
|
|
196
|
+
**Setup with Husky:**
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
# Install Husky (if not already installed)
|
|
200
|
+
npm install --save-dev husky
|
|
201
|
+
npx husky init
|
|
202
|
+
|
|
203
|
+
# Create post-commit hook
|
|
204
|
+
cat > .husky/post-commit << 'EOF'
|
|
205
|
+
#!/bin/sh
|
|
206
|
+
|
|
207
|
+
# Generate PARSEME files locally after commit
|
|
208
|
+
npx parseme generate
|
|
209
|
+
EOF
|
|
210
|
+
|
|
211
|
+
# Make hook executable
|
|
212
|
+
chmod +x .husky/post-commit
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
**Setup with manual git hooks:**
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
cat > .git/hooks/post-commit << 'EOF'
|
|
219
|
+
#!/bin/sh
|
|
220
|
+
|
|
221
|
+
npx parseme generate
|
|
222
|
+
EOF
|
|
223
|
+
|
|
224
|
+
chmod +x .git/hooks/post-commit
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
**How it works:**
|
|
228
|
+
|
|
229
|
+
- After each commit, parseme automatically generates context files with full git info
|
|
230
|
+
- Files are ready to be staged and committed with your next commit
|
|
231
|
+
- Simple setup with minimal configuration
|
|
232
|
+
|
|
233
|
+
**Best for:** Solo developers or small teams wanting automatic local updates with committed parseme files.
|
|
234
|
+
|
|
235
|
+
**Note:** If using a custom `contextDir`, ensure the path is consistent across your team's configuration.
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
### Option 3: Automatic Local and Remote Generation (Advanced Git Hooks)
|
|
240
|
+
|
|
241
|
+
Automatically update parseme files locally and remotely with git hooks. Keeps the remote version clean (without git-specific info) while maintaining full context locally. Uses multiple git hooks to manage local vs remote state.
|
|
242
|
+
|
|
243
|
+
**Setup with Husky:**
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
# Install Husky (if not already installed)
|
|
247
|
+
npm install --save-dev husky
|
|
248
|
+
npx husky init
|
|
249
|
+
|
|
250
|
+
# Create post-commit hook
|
|
251
|
+
cat > .husky/post-commit << 'EOF'
|
|
252
|
+
#!/bin/sh
|
|
253
|
+
|
|
254
|
+
npx parseme generate
|
|
255
|
+
EOF
|
|
256
|
+
|
|
257
|
+
# Create pre-push hook
|
|
258
|
+
cat > .husky/pre-push << 'EOF'
|
|
259
|
+
#!/bin/sh
|
|
260
|
+
|
|
261
|
+
# Regenerate without git info for clean remote state
|
|
262
|
+
npx parseme generate --no-git-info
|
|
263
|
+
|
|
264
|
+
# Stage parseme files
|
|
265
|
+
git add parseme-context/ PARSEME.md
|
|
266
|
+
|
|
267
|
+
# Amend the commit with updated parseme files
|
|
268
|
+
git commit --amend --no-edit --no-verify
|
|
269
|
+
EOF
|
|
270
|
+
|
|
271
|
+
# Create post-push hook
|
|
272
|
+
cat > .husky/post-push << 'EOF'
|
|
273
|
+
#!/bin/sh
|
|
274
|
+
|
|
275
|
+
# Regenerate with git info for local development
|
|
276
|
+
npx parseme generate
|
|
277
|
+
EOF
|
|
278
|
+
|
|
279
|
+
# Make hooks executable
|
|
280
|
+
chmod +x .husky/post-commit .husky/pre-push .husky/post-push
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
**Setup with manual git hooks:**
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
# Post-commit: Generate context with git info after each commit
|
|
287
|
+
cat > .git/hooks/post-commit << 'EOF'
|
|
288
|
+
#!/bin/sh
|
|
289
|
+
|
|
290
|
+
npx parseme generate
|
|
291
|
+
EOF
|
|
292
|
+
|
|
293
|
+
# Pre-push: Regenerate without git info and amend before pushing
|
|
294
|
+
cat > .git/hooks/pre-push << 'EOF'
|
|
295
|
+
#!/bin/sh
|
|
296
|
+
|
|
297
|
+
# Regenerate without git info for clean remote state
|
|
298
|
+
npx parseme generate --no-git-info
|
|
299
|
+
|
|
300
|
+
# Stage parseme files
|
|
301
|
+
git add parseme-context/ PARSEME.md
|
|
302
|
+
|
|
303
|
+
# Amend the commit with updated parseme files
|
|
304
|
+
git commit --amend --no-edit --no-verify
|
|
305
|
+
EOF
|
|
306
|
+
|
|
307
|
+
# Post-push: Restore git info locally after push completes
|
|
308
|
+
cat > .git/hooks/post-push << 'EOF'
|
|
309
|
+
#!/bin/sh
|
|
310
|
+
|
|
311
|
+
# Regenerate with git info for local development
|
|
312
|
+
npx parseme generate
|
|
313
|
+
EOF
|
|
314
|
+
|
|
315
|
+
# Make hooks executable
|
|
316
|
+
chmod +x .git/hooks/post-commit .git/hooks/pre-push .git/hooks/post-push
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
**How it works:**
|
|
320
|
+
|
|
321
|
+
1. **post-commit**: Generates context files with full git info locally
|
|
322
|
+
2. **pre-push**: Regenerates without git info and amends the commit before pushing
|
|
323
|
+
3. **post-push**: Restores full git info locally after push completes
|
|
324
|
+
|
|
325
|
+
The `--no-verify` flag in pre-push prevents an infinite loop by skipping hook execution on the amend.
|
|
326
|
+
|
|
327
|
+
**Best for:** Teams that want detailed local context for development while keeping clean, portable context in the repository.
|
|
328
|
+
|
|
329
|
+
**Note:** If using a custom `contextDir`, update the `git add` path in the pre-push hook (e.g., `git add docs/context/ PARSEME.md`).
|
|
330
|
+
|
|
331
|
+
---
|
|
332
|
+
|
|
333
|
+
### Option 4: GitHub Actions for Remote Generation paired with Local Generation
|
|
334
|
+
|
|
335
|
+
Use GitHub Actions to automatically manage remote parseme files while keeping them updated locally with git hooks. This is the recommended approach for teams using GitHub.
|
|
336
|
+
|
|
337
|
+
**Setup:**
|
|
338
|
+
|
|
339
|
+
**1. Add parseme files to `.gitignore`:**
|
|
340
|
+
|
|
341
|
+
```gitignore
|
|
342
|
+
# Parseme documentation (generated locally and by CI)
|
|
343
|
+
parseme-context/
|
|
344
|
+
PARSEME.md
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
**2. Create `.github/workflows/parseme-update.yml`:**
|
|
348
|
+
|
|
349
|
+
```yaml
|
|
350
|
+
name: Update PARSEME Documentation
|
|
351
|
+
|
|
352
|
+
on:
|
|
353
|
+
push:
|
|
354
|
+
branches:
|
|
355
|
+
- main
|
|
356
|
+
|
|
357
|
+
jobs:
|
|
358
|
+
update-parseme:
|
|
359
|
+
runs-on: ubuntu-latest
|
|
360
|
+
permissions:
|
|
361
|
+
contents: write
|
|
362
|
+
env:
|
|
363
|
+
GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
|
|
364
|
+
|
|
365
|
+
steps:
|
|
366
|
+
- name: Check if pusher is service account
|
|
367
|
+
id: check_pusher
|
|
368
|
+
run: |
|
|
369
|
+
if [ "${{ github.event.pusher.name }}" = "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}" ]; then
|
|
370
|
+
echo "is_bot=true" >> $GITHUB_OUTPUT
|
|
371
|
+
else
|
|
372
|
+
echo "is_bot=false" >> $GITHUB_OUTPUT
|
|
373
|
+
fi
|
|
374
|
+
|
|
375
|
+
- name: Checkout code
|
|
376
|
+
if: steps.check_pusher.outputs.is_bot == 'false'
|
|
377
|
+
uses: actions/checkout@v4
|
|
378
|
+
with:
|
|
379
|
+
fetch-depth: 0
|
|
380
|
+
token: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
|
|
381
|
+
|
|
382
|
+
- name: Setup Node.js
|
|
383
|
+
if: steps.check_pusher.outputs.is_bot == 'false'
|
|
384
|
+
uses: actions/setup-node@v4
|
|
385
|
+
with:
|
|
386
|
+
node-version: '22'
|
|
387
|
+
cache: 'npm'
|
|
388
|
+
|
|
389
|
+
- name: Configure Git
|
|
390
|
+
if: steps.check_pusher.outputs.is_bot == 'false'
|
|
391
|
+
run: |
|
|
392
|
+
git config user.name "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}"
|
|
393
|
+
git config user.email "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}@users.noreply.github.com"
|
|
394
|
+
|
|
395
|
+
- name: Install dependencies
|
|
396
|
+
if: steps.check_pusher.outputs.is_bot == 'false'
|
|
397
|
+
run: npm ci
|
|
398
|
+
|
|
399
|
+
- name: Generate ParseMe documentation
|
|
400
|
+
if: steps.check_pusher.outputs.is_bot == 'false'
|
|
401
|
+
run: npx parseme generate --no-git-info
|
|
402
|
+
|
|
403
|
+
- name: Force add parseme files (ignored in .gitignore)
|
|
404
|
+
if: steps.check_pusher.outputs.is_bot == 'false'
|
|
405
|
+
run: git add -f parseme-context/ PARSEME.md
|
|
406
|
+
|
|
407
|
+
- name: Check for changes
|
|
408
|
+
if: steps.check_pusher.outputs.is_bot == 'false'
|
|
409
|
+
id: check_changes
|
|
410
|
+
run: |
|
|
411
|
+
if git diff --cached --quiet; then
|
|
412
|
+
echo "changes=false" >> $GITHUB_OUTPUT
|
|
413
|
+
else
|
|
414
|
+
echo "changes=true" >> $GITHUB_OUTPUT
|
|
415
|
+
fi
|
|
416
|
+
|
|
417
|
+
- name: Commit and amend
|
|
418
|
+
if: steps.check_pusher.outputs.is_bot == 'false' && steps.check_changes.outputs.changes == 'true'
|
|
419
|
+
run: |
|
|
420
|
+
git commit --amend --no-edit --no-verify
|
|
421
|
+
git push --force-with-lease
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
**3. Configure GitHub secrets:**
|
|
425
|
+
|
|
426
|
+
- `GH_SERVICE_ACCOUNT_TOKEN`: A GitHub personal access token with repo write permissions
|
|
427
|
+
- `GH_SERVICE_ACCOUNT_USERNAME`: The username of your service account (to prevent infinite loops)
|
|
428
|
+
|
|
429
|
+
**4. Setup local git hooks with Husky:**
|
|
430
|
+
|
|
431
|
+
```bash
|
|
432
|
+
# Install Husky (if not already installed)
|
|
433
|
+
npm install --save-dev husky
|
|
434
|
+
npx husky init
|
|
435
|
+
|
|
436
|
+
# Create post-commit hook
|
|
437
|
+
cat > .husky/post-commit << 'EOF'
|
|
438
|
+
#!/bin/sh
|
|
439
|
+
|
|
440
|
+
# Generate PARSEME files locally after commit
|
|
441
|
+
npx parseme generate
|
|
442
|
+
EOF
|
|
443
|
+
|
|
444
|
+
# Create post-merge hook
|
|
445
|
+
cat > .husky/post-merge << 'EOF'
|
|
446
|
+
#!/bin/sh
|
|
447
|
+
|
|
448
|
+
# Untrack parseme files after merge/pull to keep them gitignored locally
|
|
449
|
+
git rm --cached -r parseme-context/ PARSEME.md 2>/dev/null || true
|
|
450
|
+
EOF
|
|
451
|
+
|
|
452
|
+
# Make hooks executable
|
|
453
|
+
chmod +x .husky/post-commit .husky/post-merge
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
**How it works:**
|
|
457
|
+
|
|
458
|
+
1. **Local development**: Parseme files are generated locally after each commit with full git info
|
|
459
|
+
2. **Ignored by git**: Files are listed in `.gitignore` so they're not committed manually
|
|
460
|
+
3. **Remote updates**: GitHub Actions automatically generates and commits parseme files (without git info) when pushing to main
|
|
461
|
+
4. **After pull/merge**: The post-merge hook ensures parseme files stay untracked locally, preventing conflicts
|
|
462
|
+
|
|
463
|
+
**Best for:** Teams using GitHub that want automated CI-managed remote updates with local context for development.
|
|
464
|
+
|
|
465
|
+
**Notes:**
|
|
466
|
+
|
|
467
|
+
- The workflow only runs on the `main` branch (adjust as needed for your branching strategy)
|
|
468
|
+
- If using a custom `contextDir`, update both the `.gitignore` entry, the workflow's `git add -f` path, and the post-merge hook's `git rm --cached -r` path accordingly
|
|
141
469
|
|
|
142
470
|
## Configuration
|
|
143
471
|
|
|
@@ -298,20 +626,38 @@ Toggle which sections to include in the output (all default to `true`):
|
|
|
298
626
|
|
|
299
627
|
- `limits.maxFilesPerContext` - Maximum number of files to analyze (default: `5000`)
|
|
300
628
|
|
|
301
|
-
|
|
629
|
+
### CLI Options
|
|
302
630
|
|
|
303
|
-
|
|
631
|
+
#### Generate Command (`parseme generate` or `parseme g`)
|
|
304
632
|
|
|
305
|
-
-
|
|
306
|
-
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
633
|
+
- `-c, --config <path>` - Config file path
|
|
634
|
+
- `-o, --output <path>` - Output file path
|
|
635
|
+
- `-r, --root <path>` - Root directory to analyze
|
|
636
|
+
- `--context-dir <path>` - Context directory path (default: parseme-context)
|
|
637
|
+
- `--file-types <types...>` - File types to analyze (e.g., ts tsx js jsx)
|
|
638
|
+
- `--exclude <patterns...>` - Additional exclude patterns (glob, in git repositories on top of git-tracked files)
|
|
639
|
+
- `--no-git-info` - Disable git info generation (keeps git for file discovery)
|
|
640
|
+
- `--no-git-files` - Disable git for file discovery (uses filesystem crawling instead)
|
|
641
|
+
- `--max-depth <number>` - Maximum directory depth
|
|
313
642
|
|
|
314
|
-
|
|
643
|
+
#### Init Command (`parseme init` or `parseme i`)
|
|
644
|
+
|
|
645
|
+
- `-f, --force` - Overwrite existing config
|
|
646
|
+
- `--format <format>` - Config format: json, ts, or js (default: json)
|
|
647
|
+
|
|
648
|
+
### Interactive Configuration
|
|
649
|
+
|
|
650
|
+
When running `parseme init` interactively (TTY, not CI), you'll be prompted to configure:
|
|
651
|
+
|
|
652
|
+
- **Context directory** - Where to store context files (default: `parseme-context`)
|
|
653
|
+
- **Exclude patterns** - Comma-separated glob patterns (default: `node_modules/**`, `dist/**`, `.git/**` - in git repositories, additional patterns on top of git-tracked files)
|
|
654
|
+
|
|
655
|
+
After initialization, setup tips are displayed:
|
|
656
|
+
|
|
657
|
+
- Package.json script suggestion
|
|
658
|
+
- Git hook integration suggestion
|
|
659
|
+
- README.md section suggestion for AI agents
|
|
660
|
+
- AI agent configuration files to reference PARSEME.md
|
|
315
661
|
|
|
316
662
|
## CLI Commands
|
|
317
663
|
|
|
@@ -355,60 +701,6 @@ npx parseme generate --no-git-info --no-git-files
|
|
|
355
701
|
npx parseme generate --file-types ts js --exclude "**/*.test.ts"
|
|
356
702
|
```
|
|
357
703
|
|
|
358
|
-
### CLI Options
|
|
359
|
-
|
|
360
|
-
#### Generate Command (`parseme generate` or `parseme g`)
|
|
361
|
-
|
|
362
|
-
- `-c, --config <path>` - Config file path
|
|
363
|
-
- `-o, --output <path>` - Output file path
|
|
364
|
-
- `-r, --root <path>` - Root directory to analyze
|
|
365
|
-
- `--context-dir <path>` - Context directory path (default: parseme-context)
|
|
366
|
-
- `--file-types <types...>` - File types to analyze (e.g., ts tsx js jsx)
|
|
367
|
-
- `--exclude <patterns...>` - Additional exclude patterns (glob, in git repositories on top of git-tracked files)
|
|
368
|
-
- `--no-git-info` - Disable git info generation (keeps git for file discovery)
|
|
369
|
-
- `--no-git-files` - Disable git for file discovery (uses filesystem crawling instead)
|
|
370
|
-
- `--max-depth <number>` - Maximum directory depth
|
|
371
|
-
|
|
372
|
-
#### Init Command (`parseme init` or `parseme i`)
|
|
373
|
-
|
|
374
|
-
- `-f, --force` - Overwrite existing config
|
|
375
|
-
- `--format <format>` - Config format: json, ts, or js (default: json)
|
|
376
|
-
|
|
377
|
-
### Interactive Configuration
|
|
378
|
-
|
|
379
|
-
When running `parseme init` interactively (TTY, not CI), you'll be prompted to configure:
|
|
380
|
-
|
|
381
|
-
- **Context directory** - Where to store context files (default: `parseme-context`)
|
|
382
|
-
- **Exclude patterns** - Comma-separated glob patterns (default: `node_modules/**`, `dist/**`, `.git/**` - in git repositories, additional patterns on top of git-tracked files)
|
|
383
|
-
|
|
384
|
-
After initialization, setup tips are displayed:
|
|
385
|
-
|
|
386
|
-
- Package.json script suggestion
|
|
387
|
-
- Git hook integration suggestion
|
|
388
|
-
- README.md section suggestion for AI agents
|
|
389
|
-
|
|
390
|
-
## Framework Support
|
|
391
|
-
|
|
392
|
-
PARSEME automatically detects and provides specialized analysis for:
|
|
393
|
-
|
|
394
|
-
### Express.js
|
|
395
|
-
|
|
396
|
-
- Route detection (`app.get`, `router.post`, etc.)
|
|
397
|
-
- Middleware identification
|
|
398
|
-
- Request handler mapping
|
|
399
|
-
|
|
400
|
-
### NestJS
|
|
401
|
-
|
|
402
|
-
- Controller and decorator analysis
|
|
403
|
-
- Module structure detection w
|
|
404
|
-
- Dependency injection mapping
|
|
405
|
-
|
|
406
|
-
### Fastify
|
|
407
|
-
|
|
408
|
-
- Route registration detection
|
|
409
|
-
- Plugin identification
|
|
410
|
-
- Hook analysis
|
|
411
|
-
|
|
412
704
|
## Programmatic API
|
|
413
705
|
|
|
414
706
|
You can also use PARSEME programmatically:
|
|
@@ -423,80 +715,54 @@ const context = await generator.generate();
|
|
|
423
715
|
await generator.generateToFile('./output/PARSEME.md');
|
|
424
716
|
```
|
|
425
717
|
|
|
426
|
-
##
|
|
427
|
-
|
|
428
|
-
Keep your AI context automatically updated by integrating parseme with git hooks. The recommended setup uses three hooks to ensure context files always have git info locally but stay clean on remote:
|
|
429
|
-
|
|
430
|
-
### Recommended Hook Setup
|
|
431
|
-
|
|
432
|
-
#### Manual Setup
|
|
718
|
+
## Output Format
|
|
433
719
|
|
|
434
|
-
|
|
435
|
-
# 1. Post-commit: Generate context with git info after each commit
|
|
436
|
-
cat > .git/hooks/post-commit << 'EOF'
|
|
437
|
-
#!/bin/sh
|
|
720
|
+
PARSEME generates the following output files:
|
|
438
721
|
|
|
439
|
-
|
|
440
|
-
|
|
722
|
+
- `PARSEME.md` - Main overview with links to context files and project summary (Markdown)
|
|
723
|
+
- Context directory (default: `parseme-context/`) with structured data files:
|
|
724
|
+
- `files.md` - Complete list of all project files (Markdown)
|
|
725
|
+
- `structure.json` - AST analysis with exports, imports, functions, classes, and route references (JSON)
|
|
726
|
+
- `routes.json` - API routes with methods, paths, and handlers (JSON, only if routes detected)
|
|
727
|
+
- `gitDiff.md` - Git diff statistics from generation time (Markdown, only if git is enabled and changes exist)
|
|
441
728
|
|
|
442
|
-
|
|
443
|
-
cat > .git/hooks/pre-push << 'EOF'
|
|
444
|
-
#!/bin/sh
|
|
729
|
+
The context directory location can be customized via the `contextDir` configuration option.
|
|
445
730
|
|
|
446
|
-
|
|
447
|
-
npx parseme generate --no-git-info
|
|
731
|
+
## AI Agent Integration
|
|
448
732
|
|
|
449
|
-
|
|
450
|
-
git add parseme-context/ PARSEME.md
|
|
733
|
+
To help AI coding assistants efficiently understand your codebase structure and context, add instructions to your agent configuration files:
|
|
451
734
|
|
|
452
|
-
|
|
453
|
-
git commit --amend --no-edit --no-verify
|
|
454
|
-
EOF
|
|
735
|
+
### Claude Code (`.claude/README.md` or `.claude/instructions.md`)
|
|
455
736
|
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
737
|
+
```markdown
|
|
738
|
+
Read PARSEME.md and parseme-context/ to understand the codebase structure and context.
|
|
739
|
+
```
|
|
459
740
|
|
|
460
|
-
|
|
461
|
-
npx parseme generate
|
|
462
|
-
EOF
|
|
741
|
+
### GitHub Copilot (`.github/copilot-instructions.md`)
|
|
463
742
|
|
|
464
|
-
|
|
465
|
-
|
|
743
|
+
```markdown
|
|
744
|
+
Read PARSEME.md and parseme-context/ to understand the codebase structure and context.
|
|
466
745
|
```
|
|
467
746
|
|
|
468
|
-
|
|
747
|
+
### Cursor (`.cursorrules`)
|
|
469
748
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
```json
|
|
473
|
-
// package.json
|
|
474
|
-
{
|
|
475
|
-
"husky": {
|
|
476
|
-
"hooks": {
|
|
477
|
-
"post-commit": "npx parseme generate",
|
|
478
|
-
"pre-push": "npx parseme generate --no-git-info && git add parseme-context/ PARSEME.md && git commit --amend --no-edit --no-verify",
|
|
479
|
-
"post-push": "npx parseme generate"
|
|
480
|
-
}
|
|
481
|
-
}
|
|
482
|
-
}
|
|
749
|
+
```
|
|
750
|
+
Read PARSEME.md and parseme-context/ to understand the codebase structure and context.
|
|
483
751
|
```
|
|
484
752
|
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
### How It Works
|
|
753
|
+
### ChatGPT / Custom GPT
|
|
488
754
|
|
|
489
|
-
|
|
490
|
-
2. **pre-push**: Before pushing, parseme regenerates without git info (`--no-git-info` flag) and amends the commit to keep remote clean
|
|
491
|
-
3. **post-push**: After push completes, parseme regenerates with git info again so your local working copy maintains full context
|
|
755
|
+
Add to project instructions or system prompt:
|
|
492
756
|
|
|
493
|
-
|
|
757
|
+
```
|
|
758
|
+
Read PARSEME.md and parseme-context/ to understand the codebase structure and context.
|
|
759
|
+
```
|
|
494
760
|
|
|
495
|
-
This
|
|
761
|
+
This ensures AI assistants use your pre-generated context for efficient codebase understanding.
|
|
496
762
|
|
|
497
763
|
## Requirements
|
|
498
764
|
|
|
499
|
-
- Node.js ≥20.19.5
|
|
765
|
+
- Node.js ≥20.19.5 <21 || ≥22.21.1
|
|
500
766
|
- npm ≥10.8.2
|
|
501
767
|
|
|
502
768
|
## License
|
package/dist/cli/cli.js
CHANGED
|
@@ -126,7 +126,13 @@ program
|
|
|
126
126
|
console.log('## Instructions For AI Agents');
|
|
127
127
|
console.log('This project includes AI-optimized documentation for efficient context providing:');
|
|
128
128
|
console.log('- `PARSEME.md` - Project overview with links to detailed context files');
|
|
129
|
-
console.log('- `parseme-context/` - Structured data files (
|
|
129
|
+
console.log('- `parseme-context/` - Structured data files (file list, AST structure, routes, git diff)');
|
|
130
|
+
console.log('');
|
|
131
|
+
console.log('Tip: Add references to PARSEME.md in your AI agent config files for efficient context gathering:');
|
|
132
|
+
console.log(' - Claude Code: .claude/README.md or .claude/instructions.md');
|
|
133
|
+
console.log(' - GitHub Copilot: .github/copilot-instructions.md');
|
|
134
|
+
console.log(' - Cursor: .cursorrules');
|
|
135
|
+
console.log(' - Example instruction: "Read PARSEME.md and parseme-context/ to understand the codebase structure and context."');
|
|
130
136
|
console.log('');
|
|
131
137
|
}
|
|
132
138
|
catch (error) {
|
|
@@ -156,7 +156,7 @@ A comprehensive list of all discovered API routes is available at [${linkPath}/r
|
|
|
156
156
|
return content;
|
|
157
157
|
}
|
|
158
158
|
buildFilesList(allFiles) {
|
|
159
|
-
let content = `# Project Files\n`;
|
|
159
|
+
let content = `# Project Files\n\n`;
|
|
160
160
|
allFiles.forEach((file) => {
|
|
161
161
|
content += `- ${file}\n`;
|
|
162
162
|
});
|
package/dist/core/generator.js
CHANGED
|
@@ -75,12 +75,16 @@ export class ParsemeGenerator {
|
|
|
75
75
|
// Clear the directory if it exists, then recreate it
|
|
76
76
|
await rm(parsemeDir, { recursive: true, force: true });
|
|
77
77
|
await mkdir(parsemeDir, { recursive: true });
|
|
78
|
-
|
|
78
|
+
const parsemeContent = context.parseme.endsWith('\n')
|
|
79
|
+
? context.parseme
|
|
80
|
+
: context.parseme + '\n';
|
|
81
|
+
await writeFile(finalOutputPath, parsemeContent);
|
|
79
82
|
if (context.context) {
|
|
80
83
|
for (const [filename, content] of Object.entries(context.context)) {
|
|
81
84
|
// Use .md extension for markdown files, .json for others
|
|
82
85
|
const extension = filename === 'gitDiff' || filename === 'files' ? '.md' : '.json';
|
|
83
|
-
|
|
86
|
+
const fileContent = content.endsWith('\n') ? content : content + '\n';
|
|
87
|
+
await writeFile(join(parsemeDir, `${filename}${extension}`), fileContent);
|
|
84
88
|
}
|
|
85
89
|
}
|
|
86
90
|
}
|
package/package.json
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@parseme/cli",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "0.1.0",
|
|
4
4
|
"description": "Adds a PARSEME.md file—a README.md for AI agents—to your project, providing context and structure for automated tools.",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"
|
|
7
|
-
|
|
6
|
+
"exports": {
|
|
7
|
+
".": {
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"default": "./dist/index.js"
|
|
10
|
+
},
|
|
11
|
+
"./package.json": "./package.json"
|
|
12
|
+
},
|
|
8
13
|
"bin": {
|
|
9
14
|
"parseme": "dist/cli/cli.js"
|
|
10
15
|
},
|
|
@@ -15,7 +20,7 @@
|
|
|
15
20
|
],
|
|
16
21
|
"engines": {
|
|
17
22
|
"npm": ">=10.8.2",
|
|
18
|
-
"node": ">=20.19.5"
|
|
23
|
+
"node": ">=20.19.5 <21 || >=22.21.1"
|
|
19
24
|
},
|
|
20
25
|
"scripts": {
|
|
21
26
|
"build": "tsc -p tsconfig.json",
|
|
@@ -53,7 +58,7 @@
|
|
|
53
58
|
"bugs": {
|
|
54
59
|
"url": "https://github.com/citrus551/parseme-modules/issues"
|
|
55
60
|
},
|
|
56
|
-
"homepage": "https://
|
|
61
|
+
"homepage": "https://parseme.ai",
|
|
57
62
|
"dependencies": {
|
|
58
63
|
"@babel/core": "^7.28.4",
|
|
59
64
|
"@babel/parser": "^7.28.4",
|