code-guardian-ai 0.0.0-stage → 0.3.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/.env.example +24 -0
- package/LICENSE +21 -0
- package/README.md +774 -2
- package/bin/cli.js +2 -0
- package/dist/build-manifest.json +136 -0
- package/dist/cli/commands/check.js +56 -0
- package/dist/cli/commands/doctor.js +55 -0
- package/dist/cli/commands/find.js +31 -0
- package/dist/cli/commands/init-files.js +13 -0
- package/dist/cli/commands/init.js +50 -0
- package/dist/cli/commands/optimize.js +53 -0
- package/dist/cli/commands/scan.js +47 -0
- package/dist/cli/index.js +62 -0
- package/dist/cli/output.js +4 -0
- package/dist/context.js +11 -0
- package/dist/core/ast/analysis.js +455 -0
- package/dist/core/ast/cached-info.js +46 -0
- package/dist/core/ast/discovery.js +485 -0
- package/dist/core/ast/extract-js.js +531 -0
- package/dist/core/ast/extract-py.js +298 -0
- package/dist/core/ast/graph.js +92 -0
- package/dist/core/ast/health.js +338 -0
- package/dist/core/ast/indexer.js +286 -0
- package/dist/core/ast/packages.js +343 -0
- package/dist/core/ast/parser.js +91 -0
- package/dist/core/ast/report.js +154 -0
- package/dist/core/ast/resolver.js +392 -0
- package/dist/core/ast/rules.js +37 -0
- package/dist/core/ast/scope-js.js +191 -0
- package/dist/core/ast/shared-index.js +131 -0
- package/dist/core/ast/tsconfig.js +301 -0
- package/dist/core/ast/types.js +1 -0
- package/dist/core/ast/util.js +156 -0
- package/dist/core/git/git.js +430 -0
- package/dist/core/llm/policy.js +35 -0
- package/dist/core/llm/provider.js +199 -0
- package/dist/core/prompt/compressor.js +118 -0
- package/dist/core/prompt/criteria.js +36 -0
- package/dist/core/prompt/find.js +47 -0
- package/dist/core/prompt/guidelines.js +22 -0
- package/dist/core/prompt/model-output.js +178 -0
- package/dist/core/prompt/refiner.js +194 -0
- package/dist/core/prompt/relevance.js +265 -0
- package/dist/core/prompt/untrusted.js +57 -0
- package/dist/core/security/masker.js +330 -0
- package/dist/core/security/outbound.js +40 -0
- package/dist/core/security/safe-file.js +396 -0
- package/dist/core/security/sandbox.js +181 -0
- package/dist/core/validation/baseline.js +121 -0
- package/dist/core/validation/delta.js +243 -0
- package/dist/core/validation/policy.js +123 -0
- package/dist/db/cache-key.js +221 -0
- package/dist/db/client.js +563 -0
- package/dist/db/schema-check.js +149 -0
- package/dist/db/schema.js +36 -0
- package/dist/db/windows-acl.js +150 -0
- package/dist/index.js +55 -0
- package/dist/mcp/server.js +20 -0
- package/dist/mcp/tools/find-reusable.js +22 -0
- package/dist/mcp/tools/get-context.js +39 -0
- package/dist/mcp/tools/optimize-prompt.js +31 -0
- package/dist/mcp/tools/result.js +31 -0
- package/dist/mcp/tools/validate-rules.js +28 -0
- package/dist/utils/config.js +117 -0
- package/dist/utils/errors.js +9 -0
- package/dist/utils/logger.js +19 -0
- package/dist/utils/pace.js +19 -0
- package/dist/utils/text.js +22 -0
- package/dist/utils/tokens.js +14 -0
- package/package.json +69 -4
package/README.md
CHANGED
|
@@ -1,3 +1,775 @@
|
|
|
1
|
-
#
|
|
1
|
+
# GuardStack AI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
GuardStack AI is a local MCP server and CLI for helping AI coding assistants work with an existing codebase.
|
|
4
|
+
|
|
5
|
+
It provides tools to find reusable code, retrieve relevant project context, prepare coding prompts, and check changes for issues such as duplicate implementations, circular dependencies, and unused code.
|
|
6
|
+
|
|
7
|
+
Analysis runs locally. An optional LLM step can be enabled for prompt clarification, with outbound data restricted and masked before it is sent.
|
|
8
|
+
|
|
9
|
+
**Package:** `code-guardian-ai`
|
|
10
|
+
**CLI:** `guardian`
|
|
11
|
+
**Runtime:** Node.js 22 or later
|
|
12
|
+
**License:** MIT
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## What it does
|
|
17
|
+
|
|
18
|
+
AI coding assistants often work with incomplete knowledge of a project. They may recreate utilities that already exist, introduce another implementation of an existing feature, or make changes that weaken the project's existing checks.
|
|
19
|
+
|
|
20
|
+
GuardStack AI gives an assistant access to structured information about the codebase and a way to validate changes against it.
|
|
21
|
+
|
|
22
|
+
| Capability | Description |
|
|
23
|
+
|---|---|
|
|
24
|
+
| Reusable code search | Find existing functions and classes relevant to a task |
|
|
25
|
+
| Codebase context | Retrieve a compact map of files, exports, functions, classes, and types |
|
|
26
|
+
| Prompt optimization | Add relevant project context and reuse constraints to a coding request |
|
|
27
|
+
| Change validation | Identify newly introduced code-quality findings |
|
|
28
|
+
| Local analysis | Parse and analyze supported source files without sending their contents to an external model |
|
|
29
|
+
|
|
30
|
+
GuardStack AI supports TypeScript, JavaScript, and Python analysis.
|
|
31
|
+
|
|
32
|
+
It is designed to work through MCP. The assistant decides when to call its tools; GuardStack AI does not intercept prompts or independently control the assistant's actions.
|
|
33
|
+
|
|
34
|
+
## Requirements
|
|
35
|
+
|
|
36
|
+
- Node.js 22 or later
|
|
37
|
+
- Git, for change validation against a base revision
|
|
38
|
+
- An MCP-compatible coding assistant, if using the MCP server
|
|
39
|
+
|
|
40
|
+
The CLI can be used independently of an MCP client.
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
After the package is published to npm:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm install -g code-guardian-ai
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Check the installation:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
guardian --version
|
|
54
|
+
guardian doctor
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`guardian doctor` checks the local runtime, native modules, parsers, and Git availability.
|
|
58
|
+
|
|
59
|
+
## Quick start
|
|
60
|
+
|
|
61
|
+
Run the following commands from the root of the project you want to analyze.
|
|
62
|
+
|
|
63
|
+
### 1. Initialize the workspace
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
guardian init
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
This prepares the workspace for GuardStack AI:
|
|
70
|
+
|
|
71
|
+
- Creates `.guardianrc` if it does not already exist.
|
|
72
|
+
- Prepares the local `.guardian/` cache directory.
|
|
73
|
+
- Adds `.guardian/` to `.gitignore` when needed.
|
|
74
|
+
- Displays the active privacy policy.
|
|
75
|
+
- Prints MCP configuration examples for supported clients.
|
|
76
|
+
- Prints an instruction that can be added to your assistant's project instructions.
|
|
77
|
+
|
|
78
|
+
Existing `.guardianrc` files are preserved rather than overwritten.
|
|
79
|
+
|
|
80
|
+
### 2. Inspect the codebase
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
guardian scan
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The scan reports findings such as duplicate implementations, circular dependencies, unused imports, orphan files, and dead exports.
|
|
87
|
+
|
|
88
|
+
For structured output:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
guardian scan --json
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
For evidence and suggested actions:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
guardian scan --explain
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### 3. Search for existing code
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
guardian find "authentication middleware"
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
This performs local retrieval over indexed code. It does not require an external LLM.
|
|
107
|
+
|
|
108
|
+
### 4. Check your changes
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
guardian check
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
In a Git repository, this compares findings against the selected base revision and reports newly introduced issues by default.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Connect an MCP client
|
|
119
|
+
|
|
120
|
+
GuardStack AI exposes its functionality through an MCP server using standard input and output (stdio).
|
|
121
|
+
|
|
122
|
+
Initialize the workspace first:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
guardian init
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Use the MCP configuration printed by the command for your client. The generated configuration contains the resolved CLI path and workspace root.
|
|
129
|
+
|
|
130
|
+
The server configuration has this general form:
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"mcpServers": {
|
|
135
|
+
"codeguardian": {
|
|
136
|
+
"command": "node",
|
|
137
|
+
"args": [
|
|
138
|
+
"/absolute/path/to/code-guardian-ai/bin/cli.js",
|
|
139
|
+
"serve",
|
|
140
|
+
"--root",
|
|
141
|
+
"/absolute/path/to/your-project"
|
|
142
|
+
]
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Use the actual paths printed by `guardian init`; the paths above are illustrative.
|
|
149
|
+
|
|
150
|
+
### Claude Code
|
|
151
|
+
|
|
152
|
+
`guardian init` prints a Claude Code registration command. Run the generated command from your terminal.
|
|
153
|
+
|
|
154
|
+
### Claude Desktop and Cursor
|
|
155
|
+
|
|
156
|
+
Add the generated `mcpServers` entry to the MCP configuration used by your client.
|
|
157
|
+
|
|
158
|
+
Restart or reload the client after changing its MCP configuration.
|
|
159
|
+
|
|
160
|
+
### Add project instructions
|
|
161
|
+
|
|
162
|
+
MCP tools are called at the assistant's discretion. To make their intended use clearer, add the instruction printed by `guardian init` to your project's `CLAUDE.md` or `.cursorrules` file.
|
|
163
|
+
|
|
164
|
+
The instruction asks the assistant to:
|
|
165
|
+
|
|
166
|
+
1. Search for reusable code before writing new helpers.
|
|
167
|
+
2. Use the existing implementations where appropriate.
|
|
168
|
+
3. Validate its changes after implementation.
|
|
169
|
+
|
|
170
|
+
These instructions guide the assistant; they are not an enforcement mechanism.
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## CLI reference
|
|
175
|
+
|
|
176
|
+
Run `guardian --help` or `guardian <command> --help` for command-specific options.
|
|
177
|
+
|
|
178
|
+
| Command | Purpose |
|
|
179
|
+
|---|---|
|
|
180
|
+
| `guardian init` | Initialize a workspace and print MCP configuration |
|
|
181
|
+
| `guardian serve` | Start the MCP server over stdio |
|
|
182
|
+
| `guardian doctor` | Check runtime dependencies and local setup |
|
|
183
|
+
| `guardian scan` | Analyze the workspace |
|
|
184
|
+
| `guardian scan --json` | Print the scan report as JSON |
|
|
185
|
+
| `guardian scan --explain` | Include evidence and recommended actions |
|
|
186
|
+
| `guardian check` | Validate changes against a Git base revision |
|
|
187
|
+
| `guardian find <query>` | Search locally for reusable code |
|
|
188
|
+
| `guardian optimize [prompt]` | Add relevant codebase context to a coding request |
|
|
189
|
+
|
|
190
|
+
### Workspace selection
|
|
191
|
+
|
|
192
|
+
All commands accept:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
--root <dir>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
This selects the workspace to operate on. If omitted, the current directory is used, unless overridden by the configured workspace environment.
|
|
199
|
+
|
|
200
|
+
### `guardian check` options
|
|
201
|
+
|
|
202
|
+
| Option | Description |
|
|
203
|
+
|---|---|
|
|
204
|
+
| `--base <ref>` | Compare against a Git reference instead of `HEAD` |
|
|
205
|
+
| `--all` | Include pre-existing findings |
|
|
206
|
+
| `--json` | Print structured JSON output |
|
|
207
|
+
| `--fail-on <severity>` | Exit with code 1 when a new finding reaches the selected severity (`high`, `medium`, or `low`) |
|
|
208
|
+
| `--fail-on-partial` | Exit with code 1 when validation is partial |
|
|
209
|
+
| `--config-policy <policy>` | Choose how weakened analysis configuration is handled: `warn`, `fail`, or `approve` |
|
|
210
|
+
|
|
211
|
+
By default, `check` focuses on newly introduced findings. In a Git repository, it considers staged, unstaged, and untracked changes.
|
|
212
|
+
|
|
213
|
+
### `guardian find` options
|
|
214
|
+
|
|
215
|
+
| Option | Description |
|
|
216
|
+
|---|---|
|
|
217
|
+
| `--json` | Print structured results |
|
|
218
|
+
| `--limit <n>` | Maximum number of candidates to return (1–50; default 8) |
|
|
219
|
+
|
|
220
|
+
### `guardian optimize` options
|
|
221
|
+
|
|
222
|
+
| Option | Description |
|
|
223
|
+
|---|---|
|
|
224
|
+
| `--no-llm` | Disable the optional external LLM step |
|
|
225
|
+
| `--dry-run` | Print the exact masked payload that would be sent, without sending it |
|
|
226
|
+
|
|
227
|
+
If no prompt is supplied, `guardian optimize` reads the request from standard input.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## MCP tools
|
|
232
|
+
|
|
233
|
+
The MCP server exposes four tools.
|
|
234
|
+
|
|
235
|
+
### `find_reusable_code`
|
|
236
|
+
|
|
237
|
+
Searches the indexed codebase for existing functions and classes relevant to a request.
|
|
238
|
+
|
|
239
|
+
Inputs:
|
|
240
|
+
|
|
241
|
+
- `query`: search text or identifiers.
|
|
242
|
+
- `limit`: optional result limit, defaulting to 8.
|
|
243
|
+
|
|
244
|
+
The search is local and does not call an LLM. If no useful match is found, the tool reports that rather than inventing an implementation.
|
|
245
|
+
|
|
246
|
+
### `get_codebase_context`
|
|
247
|
+
|
|
248
|
+
Returns a compact representation of relevant project structure and symbols.
|
|
249
|
+
|
|
250
|
+
It can accept:
|
|
251
|
+
|
|
252
|
+
- A natural-language query.
|
|
253
|
+
- A list of workspace-relative paths.
|
|
254
|
+
- A maximum token budget.
|
|
255
|
+
|
|
256
|
+
The result prioritizes relevant files and symbols, and reports truncation, omitted files, dropped exports, token usage, and indexing notes.
|
|
257
|
+
|
|
258
|
+
It is a structural context summary, not a full dump of source files.
|
|
259
|
+
|
|
260
|
+
### `optimize_prompt`
|
|
261
|
+
|
|
262
|
+
Adds relevant codebase context to a coding request.
|
|
263
|
+
|
|
264
|
+
It can provide:
|
|
265
|
+
|
|
266
|
+
- Existing functions and modules to reuse.
|
|
267
|
+
- Constraints against unnecessary duplication and code bloat.
|
|
268
|
+
- Acceptance criteria identified in the request.
|
|
269
|
+
- Relevant project structure.
|
|
270
|
+
|
|
271
|
+
The original request is retained. Depending on the active privacy policy, an optional external LLM may be used to clarify the request.
|
|
272
|
+
|
|
273
|
+
### `validate_rules`
|
|
274
|
+
|
|
275
|
+
Checks code for selected issues, including:
|
|
276
|
+
|
|
277
|
+
- Duplicate functions.
|
|
278
|
+
- Circular dependencies.
|
|
279
|
+
- Unused imports.
|
|
280
|
+
- Orphan files.
|
|
281
|
+
- Unused exports.
|
|
282
|
+
- Suppressed type and lint checks, including patterns such as `@ts-ignore`, `eslint-disable`, `any`, `# noqa`, and `# type: ignore`.
|
|
283
|
+
|
|
284
|
+
In a Git repository, it compares against a base revision and focuses on newly introduced findings unless existing findings are explicitly requested.
|
|
285
|
+
|
|
286
|
+
Outside a Git repository, validation applies to the workspace as a whole.
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## Privacy and data handling
|
|
291
|
+
|
|
292
|
+
GuardStack AI runs locally by default.
|
|
293
|
+
|
|
294
|
+
Indexing, parsing, retrieval, caching, and static analysis do not require an external LLM provider.
|
|
295
|
+
|
|
296
|
+
### Local mode
|
|
297
|
+
|
|
298
|
+
Local mode is the default. When the optional LLM step is disabled, GuardStack AI does not send project data to Gemini or Groq.
|
|
299
|
+
|
|
300
|
+
### Optional external LLM mode
|
|
301
|
+
|
|
302
|
+
The external step is used only when all of the following conditions are met:
|
|
303
|
+
|
|
304
|
+
1. `GUARDIAN_LLM` is explicitly enabled.
|
|
305
|
+
2. `.guardianrc` allows the LLM step with `"llm": true`.
|
|
306
|
+
3. At least one supported provider API key is configured.
|
|
307
|
+
4. The operation has not explicitly disabled LLM use with `--no-llm`.
|
|
308
|
+
|
|
309
|
+
The outbound payload is limited to:
|
|
310
|
+
|
|
311
|
+
- The developer's request.
|
|
312
|
+
- Up to eight matching symbol signatures and their file paths.
|
|
313
|
+
- A folder summary.
|
|
314
|
+
|
|
315
|
+
The payload passes through the configured secret-masking layer before transmission. Source file contents and function bodies are not included in this external payload.
|
|
316
|
+
|
|
317
|
+
### Preview before sending
|
|
318
|
+
|
|
319
|
+
To inspect the exact masked payload without making an external request, use:
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
guardian optimize "Add request validation to the API" --dry-run
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
Use `--no-llm` when you want to explicitly keep an optimization operation local.
|
|
326
|
+
|
|
327
|
+
### Important privacy limitation
|
|
328
|
+
|
|
329
|
+
Secret masking reduces the risk of accidental disclosure; it cannot guarantee detection of every possible secret or sensitive value.
|
|
330
|
+
|
|
331
|
+
Review the preview before enabling external processing in a sensitive workspace.
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## Configuration
|
|
336
|
+
|
|
337
|
+
Workspace configuration is stored in `.guardianrc`.
|
|
338
|
+
|
|
339
|
+
A configuration can look like this:
|
|
340
|
+
|
|
341
|
+
```json
|
|
342
|
+
{
|
|
343
|
+
"ignore": ["generated/"],
|
|
344
|
+
"maxFiles": 5000,
|
|
345
|
+
"maxFileKb": 512,
|
|
346
|
+
"maxDiscoveryEntries": 500000,
|
|
347
|
+
"maxDiscoveryMs": 20000,
|
|
348
|
+
"maxIndexMs": 30000,
|
|
349
|
+
"contextTokens": 4000,
|
|
350
|
+
"llm": true,
|
|
351
|
+
"pythonRoots": ["", "src"],
|
|
352
|
+
"profile": "auto",
|
|
353
|
+
"entryPoints": [
|
|
354
|
+
"tools/seed.ts",
|
|
355
|
+
"src/plugins/**"
|
|
356
|
+
],
|
|
357
|
+
"rules": {
|
|
358
|
+
"similar-structure": "low",
|
|
359
|
+
"unused-import": "off"
|
|
360
|
+
},
|
|
361
|
+
"exceptions": [
|
|
362
|
+
{
|
|
363
|
+
"rule": "dead-export",
|
|
364
|
+
"path": "src/api/**",
|
|
365
|
+
"symbol": "handler"
|
|
366
|
+
}
|
|
367
|
+
],
|
|
368
|
+
"strictOutbound": false,
|
|
369
|
+
"maskPatterns": [
|
|
370
|
+
{
|
|
371
|
+
"name": "ticket",
|
|
372
|
+
"pattern": "TKT-\\d{6}"
|
|
373
|
+
}
|
|
374
|
+
],
|
|
375
|
+
"maskLiterals": [
|
|
376
|
+
"internal-host-7"
|
|
377
|
+
]
|
|
378
|
+
}
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
### Configuration options
|
|
382
|
+
|
|
383
|
+
| Option | Purpose |
|
|
384
|
+
|---|---|
|
|
385
|
+
| `ignore` | Paths to exclude from analysis |
|
|
386
|
+
| `maxFiles` | Maximum number of files to index |
|
|
387
|
+
| `maxFileKb` | Maximum file size considered for indexing |
|
|
388
|
+
| `maxDiscoveryEntries` | Maximum filesystem entries considered during discovery |
|
|
389
|
+
| `maxDiscoveryMs` | Time budget for file discovery |
|
|
390
|
+
| `maxIndexMs` | Time budget for indexing |
|
|
391
|
+
| `contextTokens` | Default token budget for retrieved context |
|
|
392
|
+
| `llm` | Allows or disables the optional external LLM step |
|
|
393
|
+
| `pythonRoots` | Additional Python import roots |
|
|
394
|
+
| `profile` | Analysis profile; `auto` selects automatically |
|
|
395
|
+
| `entryPoints` | Paths or patterns used as entry points |
|
|
396
|
+
| `rules` | Per-rule severity overrides |
|
|
397
|
+
| `exceptions` | Targeted exceptions for selected findings |
|
|
398
|
+
| `strictOutbound` | Blocks outbound payloads containing content the secret masker cannot verify |
|
|
399
|
+
| `maskPatterns` | Additional regular expressions used to mask sensitive values |
|
|
400
|
+
| `maskLiterals` | Literal values to mask in outbound text |
|
|
401
|
+
|
|
402
|
+
Configuration changes can affect analysis coverage and confidence. In particular, disabling rules or excluding paths can hide findings.
|
|
403
|
+
|
|
404
|
+
### Environment variables
|
|
405
|
+
|
|
406
|
+
| Variable | Purpose |
|
|
407
|
+
|---|---|
|
|
408
|
+
| `GUARDIAN_LLM` | Enables the optional external LLM step when explicitly set to an accepted enabled value |
|
|
409
|
+
| `GUARDIAN_STRICT` | Overrides `strictOutbound`; `1`, `on`, `true`, and `yes` enable strict mode. Any other non-empty value disables it |
|
|
410
|
+
| `GEMINI_API_KEY` | Gemini provider key |
|
|
411
|
+
| `GROQ_API_KEY` | Groq provider key |
|
|
412
|
+
| `GEMINI_MODEL` | Overrides the Gemini model |
|
|
413
|
+
| `GROQ_MODEL` | Overrides the Groq model |
|
|
414
|
+
| `GUARDIAN_LLM_TIMEOUT_MS` | Per-provider timeout in milliseconds |
|
|
415
|
+
| `GUARDIAN_LOG` | Log level: `debug`, `info`, `warn`, or `error` |
|
|
416
|
+
| `GUARDIAN_ROOT` | Workspace root override |
|
|
417
|
+
| `GUARDIAN_ENV_FILE` | Explicit environment-file path |
|
|
418
|
+
|
|
419
|
+
The optional LLM step is disabled by default.
|
|
420
|
+
|
|
421
|
+
Default provider models:
|
|
422
|
+
|
|
423
|
+
- Gemini: `gemini-3.1-flash-lite`
|
|
424
|
+
- Groq: `openai/gpt-oss-120b`
|
|
425
|
+
|
|
426
|
+
When both provider keys are configured, Gemini is attempted first and Groq is used as a fallback. If only one key is configured, only that provider is available.
|
|
427
|
+
|
|
428
|
+
The default per-provider timeout is 12 seconds. It can be configured with `GUARDIAN_LLM_TIMEOUT_MS`, within the supported range of 200 ms to 60 seconds.
|
|
429
|
+
|
|
430
|
+
### Supplying provider API keys
|
|
431
|
+
|
|
432
|
+
The recommended approach for MCP clients is to provide credentials through the MCP server's `env` configuration. Add the variables to the generated `codeguardian` server entry:
|
|
433
|
+
|
|
434
|
+
```json
|
|
435
|
+
{
|
|
436
|
+
"mcpServers": {
|
|
437
|
+
"codeguardian": {
|
|
438
|
+
"command": "node",
|
|
439
|
+
"args": [
|
|
440
|
+
"/absolute/path/to/code-guardian-ai/bin/cli.js",
|
|
441
|
+
"serve",
|
|
442
|
+
"--root",
|
|
443
|
+
"/absolute/path/to/your-project"
|
|
444
|
+
],
|
|
445
|
+
"env": {
|
|
446
|
+
"GUARDIAN_LLM": "on",
|
|
447
|
+
"GEMINI_API_KEY": "YOUR_GEMINI_API_KEY",
|
|
448
|
+
"GROQ_API_KEY": "YOUR_GROQ_API_KEY"
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
}
|
|
452
|
+
}
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
Use the actual paths printed by `guardian init`. Include only the provider keys you intend to use. Keep real keys private and never commit them to your repository. The `env` block above is an example; `guardian init` does not insert real API keys for you.
|
|
456
|
+
|
|
457
|
+
Alternatively, provide credentials through a private environment file:
|
|
458
|
+
|
|
459
|
+
- Set `GUARDIAN_ENV_FILE` to the absolute path of that file.
|
|
460
|
+
- If `GUARDIAN_ENV_FILE` is unset, GuardStack AI looks for `.env` in its package installation directory.
|
|
461
|
+
- It does not automatically load `.env` from the workspace being analysed.
|
|
462
|
+
|
|
463
|
+
The file can contain entries such as:
|
|
464
|
+
|
|
465
|
+
```dotenv
|
|
466
|
+
GEMINI_API_KEY=your_gemini_key
|
|
467
|
+
GROQ_API_KEY=your_groq_key
|
|
468
|
+
GUARDIAN_LLM=on
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
On Unix-like systems, restrict file permissions with `chmod 600 /path/to/private.env`. On Windows, use file permissions to restrict access to your user account. Do not paste real credentials into issues, logs, screenshots, or source control.
|
|
472
|
+
|
|
473
|
+
External requests are made only when all of the following are true:
|
|
474
|
+
|
|
475
|
+
1. `GUARDIAN_LLM` is explicitly set to `on`, `true`, `1`, or `yes`.
|
|
476
|
+
2. `.guardianrc` enables the optional LLM step with `"llm": true`.
|
|
477
|
+
3. At least one supported provider key is available.
|
|
478
|
+
4. The operation has not explicitly disabled the LLM step with `--no-llm`.
|
|
479
|
+
|
|
480
|
+
Having an API key configured does not enable external processing by itself. If any required condition is missing, GuardStack AI stays in local mode.
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## How analysis works
|
|
485
|
+
|
|
486
|
+
GuardStack AI uses deterministic indexing and static analysis rather than relying on an LLM to discover code-quality findings.
|
|
487
|
+
|
|
488
|
+
### 1. File discovery and indexing
|
|
489
|
+
|
|
490
|
+
The workspace is traversed in a deterministic, sorted order, subject to configured discovery and indexing limits.
|
|
491
|
+
|
|
492
|
+
File content is hashed with SHA-256. The hash is used to determine whether cached analysis remains valid.
|
|
493
|
+
|
|
494
|
+
Partial scans do not evict the entire existing cache. Resource limits are applied to prevent unexpectedly large workspaces from consuming unbounded time or memory.
|
|
495
|
+
|
|
496
|
+
### 2. Parsing and symbol extraction
|
|
497
|
+
|
|
498
|
+
Tree-sitter parsers are used to extract supported language structures.
|
|
499
|
+
|
|
500
|
+
The current supported languages are:
|
|
501
|
+
|
|
502
|
+
- TypeScript
|
|
503
|
+
- JavaScript, including JSX, ESM, and CommonJS patterns
|
|
504
|
+
- Python
|
|
505
|
+
|
|
506
|
+
The index records relevant declarations, references, imports, exports, and relationships.
|
|
507
|
+
|
|
508
|
+
Unused-import analysis includes scope-aware handling to avoid treating every textual occurrence as a valid reference.
|
|
509
|
+
|
|
510
|
+
### 3. Import resolution
|
|
511
|
+
|
|
512
|
+
Import resolution handles common project structures, including:
|
|
513
|
+
|
|
514
|
+
- Relative imports.
|
|
515
|
+
- TypeScript and JavaScript aliases.
|
|
516
|
+
- `tsconfig` and `jsconfig` path mappings.
|
|
517
|
+
- Workspace package exports.
|
|
518
|
+
- Python import roots and relative imports.
|
|
519
|
+
|
|
520
|
+
Unsupported or ambiguous resolution is reported as a limitation rather than automatically treated as a broken import.
|
|
521
|
+
|
|
522
|
+
### 4. Duplicate detection
|
|
523
|
+
|
|
524
|
+
Duplicate analysis uses more than one signal:
|
|
525
|
+
|
|
526
|
+
- Duplicate symbol detection.
|
|
527
|
+
- Duplicate function-body matching.
|
|
528
|
+
- Similarity based on structural patterns.
|
|
529
|
+
|
|
530
|
+
Similarity findings are evidence for review, not proof that two implementations are interchangeable.
|
|
531
|
+
|
|
532
|
+
### 5. Unused-code analysis
|
|
533
|
+
|
|
534
|
+
The analyzer looks for code that appears unused, including imports, exports, and files.
|
|
535
|
+
|
|
536
|
+
Findings use different confidence levels because static analysis cannot always determine how a project is used at runtime.
|
|
537
|
+
|
|
538
|
+
For example, a public API, dynamically loaded module, framework convention, or external entry point may be used without a direct reference visible to the analyzer.
|
|
539
|
+
|
|
540
|
+
Configured entry points and exceptions can help account for these patterns.
|
|
541
|
+
|
|
542
|
+
### 6. Dependency cycles
|
|
543
|
+
|
|
544
|
+
Import relationships are used to identify circular dependencies.
|
|
545
|
+
|
|
546
|
+
Resolution limitations can affect cycle detection, so unsupported import patterns are not silently treated as fully understood.
|
|
547
|
+
|
|
548
|
+
### 7. Local retrieval
|
|
549
|
+
|
|
550
|
+
Code retrieval uses lexical scoring with IDF-style weighting over indexed symbols and code metadata.
|
|
551
|
+
|
|
552
|
+
It does not require embeddings or a hosted vector database.
|
|
553
|
+
|
|
554
|
+
### 8. Change validation
|
|
555
|
+
|
|
556
|
+
In a Git repository, validation reconstructs the selected base state and compares its findings with those in the current workspace.
|
|
557
|
+
|
|
558
|
+
The comparison accounts for changed files and relevant configuration or manifest changes.
|
|
559
|
+
|
|
560
|
+
By default, pre-existing findings are not reported as new issues. Use `--all` when you want to include them.
|
|
561
|
+
|
|
562
|
+
Validation can be marked partial when the base state or changed-file coverage cannot be fully compared. Use `--fail-on-partial` in workflows where partial validation should fail the command.
|
|
563
|
+
|
|
564
|
+
### 9. Configuration weakening
|
|
565
|
+
|
|
566
|
+
Validation can identify changes that weaken analysis configuration.
|
|
567
|
+
|
|
568
|
+
The `--config-policy` option controls how these changes are handled:
|
|
569
|
+
|
|
570
|
+
- `warn`: report the change.
|
|
571
|
+
- `fail`: fail validation.
|
|
572
|
+
- `approve`: explicitly accept the configuration change.
|
|
573
|
+
|
|
574
|
+
### 10. Resource and token budgets
|
|
575
|
+
|
|
576
|
+
Discovery, indexing, file sizes, and retrieved context are bounded by configuration.
|
|
577
|
+
|
|
578
|
+
Context retrieval reports token usage and indicates when content has been omitted or truncated. Token estimates are budgeting estimates, not guarantees of a provider's exact tokenizer count.
|
|
579
|
+
|
|
580
|
+
---
|
|
581
|
+
|
|
582
|
+
## Security model
|
|
583
|
+
|
|
584
|
+
GuardStack AI is designed around local-first operation and explicit control over outbound processing.
|
|
585
|
+
|
|
586
|
+
### Workspace boundaries
|
|
587
|
+
|
|
588
|
+
Workspace operations are restricted to the selected project root. File access and configuration writes use checks intended to prevent symlink-based escapes and unsafe file handling.
|
|
589
|
+
|
|
590
|
+
Sensitive files and unsupported file types are excluded from ordinary source indexing.
|
|
591
|
+
|
|
592
|
+
Git operations use controlled process execution rather than shell-interpolated commands.
|
|
593
|
+
|
|
594
|
+
### Outbound data controls
|
|
595
|
+
|
|
596
|
+
External LLM requests pass through a central outbound-processing path.
|
|
597
|
+
|
|
598
|
+
The masking layer supports built-in detection and user-defined patterns and literals. Pattern execution is bounded. If masking fails, the outbound request is blocked rather than sending unprocessed text.
|
|
599
|
+
|
|
600
|
+
`strictOutbound` enables fail-closed outbound checks. In addition to secret masking and re-scanning, strict mode blocks payloads containing content the masker cannot verify, such as high-entropy key-like strings, encoded blobs, binary data, or text beyond its scanning limits. `GUARDIAN_STRICT` can override this setting through the environment.
|
|
601
|
+
|
|
602
|
+
### Model output
|
|
603
|
+
|
|
604
|
+
External model output is treated as untrusted input and validated before being used as an optimization result.
|
|
605
|
+
|
|
606
|
+
The model does not receive unrestricted access to the workspace or the ability to execute project commands.
|
|
607
|
+
|
|
608
|
+
### Prompt injection and limitations
|
|
609
|
+
|
|
610
|
+
Prompt-injection and secret-masking protections reduce risk; they do not guarantee detection of every malicious instruction or sensitive value.
|
|
611
|
+
|
|
612
|
+
GuardStack AI is an analysis and context tool, not a security boundary around the coding assistant. It does not intercept the assistant's actions or guarantee that the assistant follows its recommendations.
|
|
613
|
+
|
|
614
|
+
Review generated code and validate changes using your normal development and security processes.
|
|
615
|
+
|
|
616
|
+
---
|
|
617
|
+
## Resource limits and failure behaviour
|
|
618
|
+
|
|
619
|
+
GuardStack AI applies resource limits to keep workspace analysis bounded. When a limit prevents complete analysis, the result is reported as partial or degraded rather than being presented as complete.
|
|
620
|
+
|
|
621
|
+
### Indexing and parsing
|
|
622
|
+
|
|
623
|
+
- File discovery and indexing are subject to configured limits and time budgets.
|
|
624
|
+
- Files exceeding configured size or resource limits may be skipped.
|
|
625
|
+
- Syntax trees exceeding 1,000 nesting levels or 750,000 nodes are marked degraded and are not used for normal symbol extraction.
|
|
626
|
+
- Malformed or unsupported syntax can produce partial analysis or lower-confidence findings.
|
|
627
|
+
- Parser resource limits protect against excessive memory use and call-stack depth. They do not interrupt a synchronous parser while it is running.
|
|
628
|
+
|
|
629
|
+
### Local cache
|
|
630
|
+
|
|
631
|
+
The `.guardian/` directory stores workspace-specific cache data. If persistent cache initialization is unavailable, the application can use an in-memory fallback.
|
|
632
|
+
|
|
633
|
+
The cache should not be committed to version control.
|
|
634
|
+
|
|
635
|
+
### External provider failures
|
|
636
|
+
|
|
637
|
+
When external LLM mode is enabled, the provider chain uses Gemini first and Groq as a fallback when both are configured.
|
|
638
|
+
|
|
639
|
+
Provider errors, timeouts, rate limits, and unusable responses are handled through fallback and retry controls. If no provider returns a usable response, the operation uses its local result where possible.
|
|
640
|
+
|
|
641
|
+
Requests blocked by outbound-data policy are not sent.
|
|
642
|
+
|
|
643
|
+
### MCP transport
|
|
644
|
+
|
|
645
|
+
The MCP server communicates over stdio. Protocol messages are written to standard output, while diagnostic logs go to standard error so they do not corrupt the protocol stream.
|
|
646
|
+
|
|
647
|
+
---
|
|
648
|
+
|
|
649
|
+
## Known limitations
|
|
650
|
+
|
|
651
|
+
GuardStack AI uses static analysis. It cannot determine every runtime behaviour or project convention.
|
|
652
|
+
|
|
653
|
+
Important limitations include:
|
|
654
|
+
|
|
655
|
+
- Dynamic imports, reflection, plugin registries, and runtime-generated references can make code usage difficult to determine.
|
|
656
|
+
- Framework conventions and external entry points may make apparently unused code necessary.
|
|
657
|
+
- Complex aliasing and package-resolution behaviour may not be fully supported.
|
|
658
|
+
- Structural similarity does not establish that two functions have identical behaviour.
|
|
659
|
+
- Lexical retrieval can miss conceptually related code when a query uses different terminology.
|
|
660
|
+
- Python and JavaScript projects can contain dynamic patterns that static analysis cannot resolve reliably.
|
|
661
|
+
- Syntax errors and damaged source files can reduce parsing confidence.
|
|
662
|
+
- Results depend on the selected workspace, configuration, entry points, ignore rules, and resource budgets.
|
|
663
|
+
|
|
664
|
+
Source-level analysis currently focuses on TypeScript, JavaScript, and Python. Other file types do not receive equivalent source-level analysis.
|
|
665
|
+
---
|
|
666
|
+
|
|
667
|
+
## Evaluation and measured behaviour
|
|
668
|
+
|
|
669
|
+
GuardStack AI has been tested against real repositories, controlled seeded defects, and independent analysis tools.
|
|
670
|
+
|
|
671
|
+
These results describe specific test sets and environments. They are not a universal accuracy guarantee.
|
|
672
|
+
|
|
673
|
+
### Repository checks
|
|
674
|
+
|
|
675
|
+
The evaluation included:
|
|
676
|
+
|
|
677
|
+
- Express
|
|
678
|
+
- Got
|
|
679
|
+
- Zod
|
|
680
|
+
- Next Learn
|
|
681
|
+
- Requests
|
|
682
|
+
- Click
|
|
683
|
+
|
|
684
|
+
Independent-tool comparisons produced the following results:
|
|
685
|
+
|
|
686
|
+
- **TypeScript compiler:** agreed with 8 findings, with 0 missed across four checked TypeScript repositories.
|
|
687
|
+
- **Pyflakes:** matched 6 of 8 checked cases across Requests and Click.
|
|
688
|
+
|
|
689
|
+
Agreement with another tool is useful evidence for the cases tested. It does not establish that every finding is correct or that every possible issue is detected.
|
|
690
|
+
|
|
691
|
+
### Seeded-defect tests
|
|
692
|
+
|
|
693
|
+
Across six repositories containing controlled defects, GuardStack AI detected **36 of 36 seeded defects**.
|
|
694
|
+
|
|
695
|
+
This measures detection of the defects deliberately introduced for the test. It should not be interpreted as 100% accuracy on arbitrary codebases.
|
|
696
|
+
|
|
697
|
+
### Benchmark environment
|
|
698
|
+
|
|
699
|
+
The following measurements were collected on Linux x64 with a 1-vCPU Xeon environment and Node.js 22.
|
|
700
|
+
|
|
701
|
+
Values are medians across three runs. RSS includes the process baseline.
|
|
702
|
+
|
|
703
|
+
| Repository | Cold scan | Warm scan | Analysis | Retrieval | Validation | Peak RSS |
|
|
704
|
+
|---|---:|---:|---:|---:|---:|---:|
|
|
705
|
+
| Synthetic 2,000 files | 0.76 s | 0.10 s | 0.08 s | 37 ms | 0.29 s | 205 MB |
|
|
706
|
+
| Express | 0.60 s | 0.02 s | 0.01 s | 2 ms | 0.16 s | 150 MB |
|
|
707
|
+
| Got | 1.50 s | 0.01 s | 0.02 s | 15 ms | 0.45 s | 184 MB |
|
|
708
|
+
| Zod | 3.10 s | 0.06 s | 0.18 s | 47 ms | 0.78 s | 197 MB |
|
|
709
|
+
| Next Learn | 0.25 s | 0.02 s | 0.02 s | 9 ms | 0.26 s | 151 MB |
|
|
710
|
+
| Requests | 0.31 s | 0.01 s | 0.01 s | 3 ms | 0.28 s | 152 MB |
|
|
711
|
+
|
|
712
|
+
These measurements describe the tested environment and repositories. Actual results depend on hardware, project size, file types, and configuration.
|
|
713
|
+
|
|
714
|
+
### Platform testing
|
|
715
|
+
|
|
716
|
+
CI runs test, type-checking, build, and packaging checks across:
|
|
717
|
+
|
|
718
|
+
- Ubuntu
|
|
719
|
+
- macOS
|
|
720
|
+
- Windows
|
|
721
|
+
- Node.js 22 and 24
|
|
722
|
+
|
|
723
|
+
The Windows CI jobs also include platform-specific process-tree termination and ACL-related checks.
|
|
724
|
+
|
|
725
|
+
CI coverage is not exhaustive end-to-end testing on every machine or project configuration.
|
|
726
|
+
|
|
727
|
+
---
|
|
728
|
+
|
|
729
|
+
## Development
|
|
730
|
+
|
|
731
|
+
### Set up the repository
|
|
732
|
+
|
|
733
|
+
```bash
|
|
734
|
+
git clone https://github.com/Ayush8092/GuardStack-AI.git
|
|
735
|
+
cd GuardStack-AI
|
|
736
|
+
npm ci --ignore-scripts
|
|
737
|
+
```
|
|
738
|
+
|
|
739
|
+
Build the project:
|
|
740
|
+
|
|
741
|
+
```bash
|
|
742
|
+
npm run build
|
|
743
|
+
```
|
|
744
|
+
|
|
745
|
+
Check the local environment:
|
|
746
|
+
|
|
747
|
+
```bash
|
|
748
|
+
node bin/cli.js doctor
|
|
749
|
+
```
|
|
750
|
+
|
|
751
|
+
### Development commands
|
|
752
|
+
|
|
753
|
+
| Command | Purpose |
|
|
754
|
+
|---|---|
|
|
755
|
+
| `npm run typecheck` | Run TypeScript type checking |
|
|
756
|
+
| `npm test` | Run the test suite |
|
|
757
|
+
| `npm run build` | Build the project |
|
|
758
|
+
| `npm run bench` | Run analysis benchmarks |
|
|
759
|
+
| `npm run bench:mcp` | Run MCP benchmarks |
|
|
760
|
+
| `npm run pack:smoke` | Test the packed package and installation |
|
|
761
|
+
| `npm run dev -- scan --root ../some-project` | Run the CLI from the development environment |
|
|
762
|
+
|
|
763
|
+
The package smoke test checks the packed artifact and exercises installation and CLI/MCP behaviour.
|
|
764
|
+
|
|
765
|
+
### Package contents
|
|
766
|
+
|
|
767
|
+
The npm package includes the CLI, compiled output, license, environment example, and README.
|
|
768
|
+
|
|
769
|
+
Tests, source-only development files, local caches, and workspace data are not intended to be part of the published package.
|
|
770
|
+
|
|
771
|
+
---
|
|
772
|
+
|
|
773
|
+
## License
|
|
774
|
+
|
|
775
|
+
GuardStack AI is released under the [MIT License](LICENSE).
|