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.
Files changed (70) hide show
  1. package/.env.example +24 -0
  2. package/LICENSE +21 -0
  3. package/README.md +774 -2
  4. package/bin/cli.js +2 -0
  5. package/dist/build-manifest.json +136 -0
  6. package/dist/cli/commands/check.js +56 -0
  7. package/dist/cli/commands/doctor.js +55 -0
  8. package/dist/cli/commands/find.js +31 -0
  9. package/dist/cli/commands/init-files.js +13 -0
  10. package/dist/cli/commands/init.js +50 -0
  11. package/dist/cli/commands/optimize.js +53 -0
  12. package/dist/cli/commands/scan.js +47 -0
  13. package/dist/cli/index.js +62 -0
  14. package/dist/cli/output.js +4 -0
  15. package/dist/context.js +11 -0
  16. package/dist/core/ast/analysis.js +455 -0
  17. package/dist/core/ast/cached-info.js +46 -0
  18. package/dist/core/ast/discovery.js +485 -0
  19. package/dist/core/ast/extract-js.js +531 -0
  20. package/dist/core/ast/extract-py.js +298 -0
  21. package/dist/core/ast/graph.js +92 -0
  22. package/dist/core/ast/health.js +338 -0
  23. package/dist/core/ast/indexer.js +286 -0
  24. package/dist/core/ast/packages.js +343 -0
  25. package/dist/core/ast/parser.js +91 -0
  26. package/dist/core/ast/report.js +154 -0
  27. package/dist/core/ast/resolver.js +392 -0
  28. package/dist/core/ast/rules.js +37 -0
  29. package/dist/core/ast/scope-js.js +191 -0
  30. package/dist/core/ast/shared-index.js +131 -0
  31. package/dist/core/ast/tsconfig.js +301 -0
  32. package/dist/core/ast/types.js +1 -0
  33. package/dist/core/ast/util.js +156 -0
  34. package/dist/core/git/git.js +430 -0
  35. package/dist/core/llm/policy.js +35 -0
  36. package/dist/core/llm/provider.js +199 -0
  37. package/dist/core/prompt/compressor.js +118 -0
  38. package/dist/core/prompt/criteria.js +36 -0
  39. package/dist/core/prompt/find.js +47 -0
  40. package/dist/core/prompt/guidelines.js +22 -0
  41. package/dist/core/prompt/model-output.js +178 -0
  42. package/dist/core/prompt/refiner.js +194 -0
  43. package/dist/core/prompt/relevance.js +265 -0
  44. package/dist/core/prompt/untrusted.js +57 -0
  45. package/dist/core/security/masker.js +330 -0
  46. package/dist/core/security/outbound.js +40 -0
  47. package/dist/core/security/safe-file.js +396 -0
  48. package/dist/core/security/sandbox.js +181 -0
  49. package/dist/core/validation/baseline.js +121 -0
  50. package/dist/core/validation/delta.js +243 -0
  51. package/dist/core/validation/policy.js +123 -0
  52. package/dist/db/cache-key.js +221 -0
  53. package/dist/db/client.js +563 -0
  54. package/dist/db/schema-check.js +149 -0
  55. package/dist/db/schema.js +36 -0
  56. package/dist/db/windows-acl.js +150 -0
  57. package/dist/index.js +55 -0
  58. package/dist/mcp/server.js +20 -0
  59. package/dist/mcp/tools/find-reusable.js +22 -0
  60. package/dist/mcp/tools/get-context.js +39 -0
  61. package/dist/mcp/tools/optimize-prompt.js +31 -0
  62. package/dist/mcp/tools/result.js +31 -0
  63. package/dist/mcp/tools/validate-rules.js +28 -0
  64. package/dist/utils/config.js +117 -0
  65. package/dist/utils/errors.js +9 -0
  66. package/dist/utils/logger.js +19 -0
  67. package/dist/utils/pace.js +19 -0
  68. package/dist/utils/text.js +22 -0
  69. package/dist/utils/tokens.js +14 -0
  70. package/package.json +69 -4
package/README.md CHANGED
@@ -1,3 +1,775 @@
1
- # Temporary Holding Version
1
+ # GuardStack AI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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).