wia-agent 0.1.1__tar.gz
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.
- wia_agent-0.1.1/PKG-INFO +295 -0
- wia_agent-0.1.1/README.md +268 -0
- wia_agent-0.1.1/pyproject.toml +53 -0
- wia_agent-0.1.1/setup.cfg +4 -0
- wia_agent-0.1.1/wia/__init__.py +7 -0
- wia_agent-0.1.1/wia/__main__.py +7 -0
- wia_agent-0.1.1/wia/analyzers/__init__.py +1 -0
- wia_agent-0.1.1/wia/analyzers/code/__init__.py +1 -0
- wia_agent-0.1.1/wia/analyzers/code/ast_parser.py +178 -0
- wia_agent-0.1.1/wia/analyzers/dependency/__init__.py +1 -0
- wia_agent-0.1.1/wia/analyzers/dependency/conflict_detector.py +60 -0
- wia_agent-0.1.1/wia/analyzers/dependency/manifest_parser.py +258 -0
- wia_agent-0.1.1/wia/analyzers/git/__init__.py +5 -0
- wia_agent-0.1.1/wia/analyzers/git/git_analyzer.py +142 -0
- wia_agent-0.1.1/wia/analyzers/security/__init__.py +5 -0
- wia_agent-0.1.1/wia/analyzers/security/secret_scanner.py +197 -0
- wia_agent-0.1.1/wia/cli/__init__.py +1 -0
- wia_agent-0.1.1/wia/cli/app.py +105 -0
- wia_agent-0.1.1/wia/cli/commands/__init__.py +1 -0
- wia_agent-0.1.1/wia/cli/commands/analyze_cmd.py +125 -0
- wia_agent-0.1.1/wia/cli/commands/architecture_cmd.py +115 -0
- wia_agent-0.1.1/wia/cli/commands/ask_cmd.py +36 -0
- wia_agent-0.1.1/wia/cli/commands/doctor_cmd.py +61 -0
- wia_agent-0.1.1/wia/cli/commands/explain_cmd.py +35 -0
- wia_agent-0.1.1/wia/cli/commands/files_cmd.py +44 -0
- wia_agent-0.1.1/wia/cli/commands/impact_cmd.py +77 -0
- wia_agent-0.1.1/wia/cli/commands/index_cmd.py +56 -0
- wia_agent-0.1.1/wia/cli/commands/info_cmd.py +49 -0
- wia_agent-0.1.1/wia/cli/commands/init_cmd.py +38 -0
- wia_agent-0.1.1/wia/cli/commands/report_cmd.py +41 -0
- wia_agent-0.1.1/wia/cli/commands/search_cmd.py +55 -0
- wia_agent-0.1.1/wia/cli/commands/status_cmd.py +60 -0
- wia_agent-0.1.1/wia/cli/commands/summary_cmd.py +43 -0
- wia_agent-0.1.1/wia/cli/commands/version_cmd.py +10 -0
- wia_agent-0.1.1/wia/cli/formatting.py +49 -0
- wia_agent-0.1.1/wia/cli/main.py +0 -0
- wia_agent-0.1.1/wia/constants.py +16 -0
- wia_agent-0.1.1/wia/core/architecture.py +427 -0
- wia_agent-0.1.1/wia/core/batch_planner.py +50 -0
- wia_agent-0.1.1/wia/core/change_detector.py +73 -0
- wia_agent-0.1.1/wia/core/chunker.py +96 -0
- wia_agent-0.1.1/wia/core/config.py +78 -0
- wia_agent-0.1.1/wia/core/discovery.py +101 -0
- wia_agent-0.1.1/wia/core/filter.py +116 -0
- wia_agent-0.1.1/wia/core/framework.py +160 -0
- wia_agent-0.1.1/wia/core/gitignore.py +66 -0
- wia_agent-0.1.1/wia/core/hashing.py +48 -0
- wia_agent-0.1.1/wia/core/impact.py +215 -0
- wia_agent-0.1.1/wia/core/index_model.py +124 -0
- wia_agent-0.1.1/wia/core/language.py +123 -0
- wia_agent-0.1.1/wia/core/metadata.py +60 -0
- wia_agent-0.1.1/wia/core/rag_context.py +169 -0
- wia_agent-0.1.1/wia/core/search_engine.py +101 -0
- wia_agent-0.1.1/wia/core/validator.py +105 -0
- wia_agent-0.1.1/wia/exceptions.py +28 -0
- wia_agent-0.1.1/wia/knowledge/embeddings.py +58 -0
- wia_agent-0.1.1/wia/knowledge/graph.py +229 -0
- wia_agent-0.1.1/wia/knowledge/vector_store.py +108 -0
- wia_agent-0.1.1/wia/llm/__init__.py +6 -0
- wia_agent-0.1.1/wia/llm/base.py +162 -0
- wia_agent-0.1.1/wia/llm/service.py +22 -0
- wia_agent-0.1.1/wia/models/__init__.py +0 -0
- wia_agent-0.1.1/wia/models/schemas.py +0 -0
- wia_agent-0.1.1/wia/scanner/__init__.py +0 -0
- wia_agent-0.1.1/wia/scanner/detector.py +0 -0
- wia_agent-0.1.1/wia/scanner/hasher.py +0 -0
- wia_agent-0.1.1/wia/scanner/ignore.py +0 -0
- wia_agent-0.1.1/wia/scanner/scanner.py +0 -0
- wia_agent-0.1.1/wia/services/__init__.py +1 -0
- wia_agent-0.1.1/wia/services/base.py +36 -0
- wia_agent-0.1.1/wia/services/explanation_service.py +886 -0
- wia_agent-0.1.1/wia/services/indexing_service.py +264 -0
- wia_agent-0.1.1/wia/services/init_service.py +69 -0
- wia_agent-0.1.1/wia/services/inspection_service.py +103 -0
- wia_agent-0.1.1/wia/services/status_service.py +135 -0
- wia_agent-0.1.1/wia/storage/__init__.py +1 -0
- wia_agent-0.1.1/wia/storage/repository.py +54 -0
- wia_agent-0.1.1/wia/storage/serializer.py +49 -0
- wia_agent-0.1.1/wia/storage/sqlite_store.py +248 -0
- wia_agent-0.1.1/wia/utils/__init__.py +0 -0
- wia_agent-0.1.1/wia/utils/logger.py +30 -0
- wia_agent-0.1.1/wia/utils/report_generator.py +700 -0
- wia_agent-0.1.1/wia_agent.egg-info/PKG-INFO +295 -0
- wia_agent-0.1.1/wia_agent.egg-info/SOURCES.txt +86 -0
- wia_agent-0.1.1/wia_agent.egg-info/dependency_links.txt +1 -0
- wia_agent-0.1.1/wia_agent.egg-info/entry_points.txt +2 -0
- wia_agent-0.1.1/wia_agent.egg-info/requires.txt +6 -0
- wia_agent-0.1.1/wia_agent.egg-info/top_level.txt +1 -0
wia_agent-0.1.1/PKG-INFO
ADDED
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: wia-agent
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Workspace Intelligence Agent โ Indexing and understanding software repositories
|
|
5
|
+
Author: WIA Developer Team
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Yashwanth112004/Workspace-Intelligence-Agent
|
|
8
|
+
Project-URL: Repository, https://github.com/Yashwanth112004/Workspace-Intelligence-Agent.git
|
|
9
|
+
Project-URL: Bug Tracker, https://github.com/Yashwanth112004/Workspace-Intelligence-Agent/issues
|
|
10
|
+
Keywords: workspace,code intelligence,cli,indexer,developer-tools
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
Requires-Dist: click>=8.1.0
|
|
23
|
+
Requires-Dist: pathspec>=0.11.0
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest>=7.4.0; extra == "dev"
|
|
26
|
+
Requires-Dist: build>=1.0.0; extra == "dev"
|
|
27
|
+
|
|
28
|
+
# WIA โ Workspace Intelligence Agent
|
|
29
|
+
|
|
30
|
+
> **AI-powered workspace intelligence engine for analyzing, understanding, reporting on, and reasoning over software codebases.**
|
|
31
|
+
|
|
32
|
+
[](https://www.python.org/)
|
|
33
|
+
[](https://pypi.org/project/wia-agent/)
|
|
34
|
+
[](https://github.com/Yashwanth112004/Workspace-Intelligence-Agent)
|
|
35
|
+
[](https://github.com/Yashwanth112004/Workspace-Intelligence-Agent/tree/main/tests)
|
|
36
|
+
|
|
37
|
+
WIA (Workspace Intelligence Agent) is a **CLI-first repository intelligence platform** designed to analyze software repositories, build a structured **Workspace Knowledge Model**, detect change impacts, evaluate architectural boundaries, track dependencies, scan for security leaks, and provide grounded AI reasoning.
|
|
38
|
+
|
|
39
|
+
Unlike simple chatbot assistants that read raw text snippets, WIA parses abstract syntax trees (AST), constructs directed entity relationship graphs (`IMPORTS`, `DEFINES`, `CALLS`, `DEPENDS_ON`), tracks incremental file hashing, and synthesizes developer explanations grounded in empirical workspace evidence.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## โก Key Highlights & Core Capabilities
|
|
44
|
+
|
|
45
|
+
* ๐ **Multi-Stage Indexing Pipeline**: Crawls workspace, respects `.gitignore`, computes SHA-256 content hashes, detects programming languages & tech stacks, and runs specialized analyzers.
|
|
46
|
+
* ๐ณ **AST & Symbol Parser**: Extracts classes, functions, methods, parameters, docstrings, parent classes, and import statements across multi-language codebases.
|
|
47
|
+
* ๐ธ๏ธ **Workspace Knowledge Graph**: Maps directional dependency edges (`IMPORTS`, `DEFINES`, `CALLS`, `DEPENDS_ON`) between files and symbols in a persistent SQLite relational store.
|
|
48
|
+
* ๐ฆ **Dependency Manifest & Conflict Detection**: Parses package manifests (`pyproject.toml`, `requirements.txt`, `package.json`, `Cargo.toml`, `go.mod`), normalizes package names, categorizes dependency types (`runtime`, `dev`, `optional`, `build`), and flags version mismatches.
|
|
49
|
+
* ๐ **Security Secret Scanner with 100% Masking**: Identifies exposed credentials (AWS keys, RSA private keys, GitHub PATs, API tokens, Slack webhooks), classifies test fixtures vs real secrets, and enforces 100% secret masking (`AKIA************MPLE`).
|
|
50
|
+
* ๐ **Architecture Boundary & Cycle Intelligence**: Maps 9 system component boundaries, detects circular import dependencies via DFS traversal, computes high fan-in/fan-out metrics, and identifies main entrypoints.
|
|
51
|
+
* ๐ฅ **Symbol Refactoring Impact Analysis**: Evaluates symbol callers and file importers, resolves same-name symbols, differentiates direct callers from file importers, and assigns risk classifications (`LOW`, `MEDIUM`, `HIGH`).
|
|
52
|
+
* ๐ง **Intent-Grounded AI Reasoning Agent**: Answers developer queries (`wia ask`) using lightweight query intent classification (`ARCHITECTURE`, `WORKFLOW`, `COMPONENT`, `STORAGE`, `FILE_SYMBOL`, `GENERAL`) and custom RAG context retrieval.
|
|
53
|
+
* ๐ **Developer-Level Code Explanation**: Explains target files and symbols (`wia explain`), detailing purpose, architectural role, symbols breakdown, used-by dependents, and likely modification consequences.
|
|
54
|
+
* ๐ **Persistent HTML Narrative Dashboard**: Generates self-contained, batch-accumulating HTML reports (`wia-report.html`) with executive narrative summaries, component architecture cards, and file intelligence tables.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## ๐ป Quickstart & Installation
|
|
59
|
+
|
|
60
|
+
### 1. Installation
|
|
61
|
+
|
|
62
|
+
Install **WIA** from PyPI:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pip install wia-agent
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Or install locally for development:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
pip install -e .
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Verify installation:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
wia --version
|
|
78
|
+
wia --help
|
|
79
|
+
wia doctor
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## ๐ ๏ธ Complete CLI Command Reference Manual
|
|
85
|
+
|
|
86
|
+
### 1. `wia init` โ Initialize Workspace
|
|
87
|
+
|
|
88
|
+
Initializes the `.wia/` metadata directory and creates `config.json` inside the specified target directory.
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
wia init [PATH]
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
* **Arguments**: `PATH` (Optional, defaults to current working directory).
|
|
95
|
+
* **Behavior**: Prepares the workspace for indexing and configures default file limit thresholds.
|
|
96
|
+
|
|
97
|
+
**Example**:
|
|
98
|
+
```bash
|
|
99
|
+
wia init .
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
### 2. `wia index` โ Run Indexing & Multi-Analyzer Pipeline
|
|
105
|
+
|
|
106
|
+
Executes file discovery, `.gitignore` filtering, SHA-256 change detection, language & framework detection, AST parsing, dependency manifest analysis, Git hotspot tracking, secret scanning, graph building, and SQLite database persistence.
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
wia index [PATH] [--force-reindex]
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
* **Flags**:
|
|
113
|
+
* `--force-reindex`, `-f`: Clears existing index state and forces a full re-indexing of all files.
|
|
114
|
+
* **Behavior**: Processes files in deterministic batches, skipping unchanged files via hash comparison. Automatically excludes generated artifacts (`wia-report.html`, `.wia/`, `__pycache__/`, `*.pyc`).
|
|
115
|
+
|
|
116
|
+
**Example**:
|
|
117
|
+
```bash
|
|
118
|
+
wia index --force-reindex
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
### 3. `wia status` โ Check Workspace Synchronization Status
|
|
124
|
+
|
|
125
|
+
Compares the last completed index state against the current filesystem to detect added, modified, or deleted files without mutating index data.
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
wia status [PATH]
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
* **States**:
|
|
132
|
+
* `NOT_INITIALIZED`: Workspace lacks `.wia/` directory.
|
|
133
|
+
* `NO_INDEX`: Workspace initialized but not yet indexed.
|
|
134
|
+
* `UP_TO_DATE`: Workspace is synchronized with the filesystem.
|
|
135
|
+
* `CHANGES_DETECTED`: Files have been added, modified, or deleted since last index.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
### 4. `wia files` โ List Indexed Workspace Files
|
|
140
|
+
|
|
141
|
+
Lists all files currently indexed in the workspace with metadata.
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
wia files [PATH] [--language LANG]
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
* **Flags**:
|
|
148
|
+
* `--language`, `-l`: Filter listed files by language (e.g. `Python`, `Markdown`, `TOML`).
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
### 5. `wia info` โ Workspace Overview & Statistics
|
|
153
|
+
|
|
154
|
+
Displays file counts, language distribution percentages, detected frameworks, and index metadata.
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
wia info [PATH]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
### 6. `wia analyze` โ Run Specialized Workspace Analyzers
|
|
163
|
+
|
|
164
|
+
Executes targeted security, dependency, or Git repository analyzers.
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
# Package Manifest & Dependency Conflicts
|
|
168
|
+
wia analyze deps [--workspace PATH]
|
|
169
|
+
|
|
170
|
+
# Git Commit History & File Churn Hotspots
|
|
171
|
+
wia analyze git [--workspace PATH] [--max-commits 50] [--top-hotspots 10]
|
|
172
|
+
|
|
173
|
+
# Security Hardcoded Secret Scanner
|
|
174
|
+
wia analyze security [--workspace PATH]
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
### 7. `wia architecture` โ System Subsystem & Component Boundary Map
|
|
180
|
+
|
|
181
|
+
Analyzes the workspace to produce a factually grounded architectural explanation, mapping subsystem boundaries, entrypoints, circular import cycles (DFS), high fan-in/fan-out metrics, and directory hierarchy.
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
wia architecture [--workspace PATH]
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
### 8. `wia impact` โ Refactoring Impact Analysis
|
|
190
|
+
|
|
191
|
+
Evaluates downstream callers and file importers for a given target symbol or file, assigning an evidence-backed change risk classification (`LOW`, `MEDIUM`, `HIGH`).
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
wia impact <symbol_or_file> [--workspace PATH]
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
### 9. `wia explain` โ Developer-Level Code & Symbol Explanation
|
|
200
|
+
|
|
201
|
+
Generates a complete technical explanation answering: *"What is this code, what does it do, why does it exist, how does it work, how does it fit into the project, what depends on it, and what should a developer know before modifying it?"*
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
wia explain <file_or_symbol> [--workspace PATH]
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
### 10. `wia ask` โ Grounded AI Reasoning Agent
|
|
210
|
+
|
|
211
|
+
Answers natural language developer questions grounded in indexed workspace evidence using query intent classification (`ARCHITECTURE`, `WORKFLOW`, `COMPONENT`, `STORAGE`, `FILE_SYMBOL`, `GENERAL`).
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
wia ask "<question>" [--workspace PATH]
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
### 11. `wia report` โ Generate HTML Intelligence Dashboard
|
|
220
|
+
|
|
221
|
+
Compiles all workspace intelligence into a self-contained, batch-accumulating HTML report (`wia-report.html`).
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
wia report [--workspace PATH] [--output FILE]
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
### 12. `wia search` โ Query Workspace Symbols & Files
|
|
230
|
+
|
|
231
|
+
Executes relevance-scored search across declared AST symbols, function definitions, classes, and file paths.
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
wia search <query> [--workspace PATH] [--language LANG] [--type TYPE] [--limit N]
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
### 13. `wia summary` โ Export LLM RAG Context Markdown
|
|
240
|
+
|
|
241
|
+
Exports a structured Markdown summary of the workspace suitable for prompt context injection into external LLMs.
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
wia summary [--workspace PATH] [--output summary.md]
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
### 14. `wia doctor` โ Environment Health Diagnostic Check
|
|
250
|
+
|
|
251
|
+
Runs system diagnostics verifying Python version, installed package entrypoints, SQLite database connectivity, and Git CLI availability.
|
|
252
|
+
|
|
253
|
+
```bash
|
|
254
|
+
wia doctor
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## ๐งช Testing & Quality Assurance
|
|
260
|
+
|
|
261
|
+
WIA includes a comprehensive automated suite of 154 unit, CLI, and integration tests using `pytest`.
|
|
262
|
+
|
|
263
|
+
To run the complete test suite:
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
python -m pytest
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
**Current Test Status**: `154 passed`.
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## ๐๏ธ Architecture & Internal Subsystem Design
|
|
274
|
+
|
|
275
|
+
```text
|
|
276
|
+
WIA CLI (app.py)
|
|
277
|
+
โ
|
|
278
|
+
โผ
|
|
279
|
+
Service Layer Orchestration
|
|
280
|
+
(IndexingService, StatusService, ExplanationService)
|
|
281
|
+
โ
|
|
282
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
283
|
+
โผ โผ โผ
|
|
284
|
+
Core Inspection Specialized Analyzers Knowledge & Storage
|
|
285
|
+
- FileDiscovery - ASTParser (Python AST) - WorkspaceIndex
|
|
286
|
+
- FileFilter & Gitignore - ManifestParser (pyproject) - WorkspaceGraph
|
|
287
|
+
- FileHasher (SHA-256) - SecretScanner (Masking) - SQLiteStore
|
|
288
|
+
- LanguageDetector - GitAnalyzer - VectorStore
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## ๐ License
|
|
294
|
+
|
|
295
|
+
Distributed under the MIT License. See `LICENSE` for more information.
|
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
# WIA โ Workspace Intelligence Agent
|
|
2
|
+
|
|
3
|
+
> **AI-powered workspace intelligence engine for analyzing, understanding, reporting on, and reasoning over software codebases.**
|
|
4
|
+
|
|
5
|
+
[](https://www.python.org/)
|
|
6
|
+
[](https://pypi.org/project/wia-agent/)
|
|
7
|
+
[](https://github.com/Yashwanth112004/Workspace-Intelligence-Agent)
|
|
8
|
+
[](https://github.com/Yashwanth112004/Workspace-Intelligence-Agent/tree/main/tests)
|
|
9
|
+
|
|
10
|
+
WIA (Workspace Intelligence Agent) is a **CLI-first repository intelligence platform** designed to analyze software repositories, build a structured **Workspace Knowledge Model**, detect change impacts, evaluate architectural boundaries, track dependencies, scan for security leaks, and provide grounded AI reasoning.
|
|
11
|
+
|
|
12
|
+
Unlike simple chatbot assistants that read raw text snippets, WIA parses abstract syntax trees (AST), constructs directed entity relationship graphs (`IMPORTS`, `DEFINES`, `CALLS`, `DEPENDS_ON`), tracks incremental file hashing, and synthesizes developer explanations grounded in empirical workspace evidence.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## โก Key Highlights & Core Capabilities
|
|
17
|
+
|
|
18
|
+
* ๐ **Multi-Stage Indexing Pipeline**: Crawls workspace, respects `.gitignore`, computes SHA-256 content hashes, detects programming languages & tech stacks, and runs specialized analyzers.
|
|
19
|
+
* ๐ณ **AST & Symbol Parser**: Extracts classes, functions, methods, parameters, docstrings, parent classes, and import statements across multi-language codebases.
|
|
20
|
+
* ๐ธ๏ธ **Workspace Knowledge Graph**: Maps directional dependency edges (`IMPORTS`, `DEFINES`, `CALLS`, `DEPENDS_ON`) between files and symbols in a persistent SQLite relational store.
|
|
21
|
+
* ๐ฆ **Dependency Manifest & Conflict Detection**: Parses package manifests (`pyproject.toml`, `requirements.txt`, `package.json`, `Cargo.toml`, `go.mod`), normalizes package names, categorizes dependency types (`runtime`, `dev`, `optional`, `build`), and flags version mismatches.
|
|
22
|
+
* ๐ **Security Secret Scanner with 100% Masking**: Identifies exposed credentials (AWS keys, RSA private keys, GitHub PATs, API tokens, Slack webhooks), classifies test fixtures vs real secrets, and enforces 100% secret masking (`AKIA************MPLE`).
|
|
23
|
+
* ๐ **Architecture Boundary & Cycle Intelligence**: Maps 9 system component boundaries, detects circular import dependencies via DFS traversal, computes high fan-in/fan-out metrics, and identifies main entrypoints.
|
|
24
|
+
* ๐ฅ **Symbol Refactoring Impact Analysis**: Evaluates symbol callers and file importers, resolves same-name symbols, differentiates direct callers from file importers, and assigns risk classifications (`LOW`, `MEDIUM`, `HIGH`).
|
|
25
|
+
* ๐ง **Intent-Grounded AI Reasoning Agent**: Answers developer queries (`wia ask`) using lightweight query intent classification (`ARCHITECTURE`, `WORKFLOW`, `COMPONENT`, `STORAGE`, `FILE_SYMBOL`, `GENERAL`) and custom RAG context retrieval.
|
|
26
|
+
* ๐ **Developer-Level Code Explanation**: Explains target files and symbols (`wia explain`), detailing purpose, architectural role, symbols breakdown, used-by dependents, and likely modification consequences.
|
|
27
|
+
* ๐ **Persistent HTML Narrative Dashboard**: Generates self-contained, batch-accumulating HTML reports (`wia-report.html`) with executive narrative summaries, component architecture cards, and file intelligence tables.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## ๐ป Quickstart & Installation
|
|
32
|
+
|
|
33
|
+
### 1. Installation
|
|
34
|
+
|
|
35
|
+
Install **WIA** from PyPI:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pip install wia-agent
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Or install locally for development:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pip install -e .
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Verify installation:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
wia --version
|
|
51
|
+
wia --help
|
|
52
|
+
wia doctor
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## ๐ ๏ธ Complete CLI Command Reference Manual
|
|
58
|
+
|
|
59
|
+
### 1. `wia init` โ Initialize Workspace
|
|
60
|
+
|
|
61
|
+
Initializes the `.wia/` metadata directory and creates `config.json` inside the specified target directory.
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
wia init [PATH]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
* **Arguments**: `PATH` (Optional, defaults to current working directory).
|
|
68
|
+
* **Behavior**: Prepares the workspace for indexing and configures default file limit thresholds.
|
|
69
|
+
|
|
70
|
+
**Example**:
|
|
71
|
+
```bash
|
|
72
|
+
wia init .
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
### 2. `wia index` โ Run Indexing & Multi-Analyzer Pipeline
|
|
78
|
+
|
|
79
|
+
Executes file discovery, `.gitignore` filtering, SHA-256 change detection, language & framework detection, AST parsing, dependency manifest analysis, Git hotspot tracking, secret scanning, graph building, and SQLite database persistence.
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
wia index [PATH] [--force-reindex]
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
* **Flags**:
|
|
86
|
+
* `--force-reindex`, `-f`: Clears existing index state and forces a full re-indexing of all files.
|
|
87
|
+
* **Behavior**: Processes files in deterministic batches, skipping unchanged files via hash comparison. Automatically excludes generated artifacts (`wia-report.html`, `.wia/`, `__pycache__/`, `*.pyc`).
|
|
88
|
+
|
|
89
|
+
**Example**:
|
|
90
|
+
```bash
|
|
91
|
+
wia index --force-reindex
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
### 3. `wia status` โ Check Workspace Synchronization Status
|
|
97
|
+
|
|
98
|
+
Compares the last completed index state against the current filesystem to detect added, modified, or deleted files without mutating index data.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
wia status [PATH]
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
* **States**:
|
|
105
|
+
* `NOT_INITIALIZED`: Workspace lacks `.wia/` directory.
|
|
106
|
+
* `NO_INDEX`: Workspace initialized but not yet indexed.
|
|
107
|
+
* `UP_TO_DATE`: Workspace is synchronized with the filesystem.
|
|
108
|
+
* `CHANGES_DETECTED`: Files have been added, modified, or deleted since last index.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
### 4. `wia files` โ List Indexed Workspace Files
|
|
113
|
+
|
|
114
|
+
Lists all files currently indexed in the workspace with metadata.
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
wia files [PATH] [--language LANG]
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
* **Flags**:
|
|
121
|
+
* `--language`, `-l`: Filter listed files by language (e.g. `Python`, `Markdown`, `TOML`).
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
### 5. `wia info` โ Workspace Overview & Statistics
|
|
126
|
+
|
|
127
|
+
Displays file counts, language distribution percentages, detected frameworks, and index metadata.
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
wia info [PATH]
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
### 6. `wia analyze` โ Run Specialized Workspace Analyzers
|
|
136
|
+
|
|
137
|
+
Executes targeted security, dependency, or Git repository analyzers.
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
# Package Manifest & Dependency Conflicts
|
|
141
|
+
wia analyze deps [--workspace PATH]
|
|
142
|
+
|
|
143
|
+
# Git Commit History & File Churn Hotspots
|
|
144
|
+
wia analyze git [--workspace PATH] [--max-commits 50] [--top-hotspots 10]
|
|
145
|
+
|
|
146
|
+
# Security Hardcoded Secret Scanner
|
|
147
|
+
wia analyze security [--workspace PATH]
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
### 7. `wia architecture` โ System Subsystem & Component Boundary Map
|
|
153
|
+
|
|
154
|
+
Analyzes the workspace to produce a factually grounded architectural explanation, mapping subsystem boundaries, entrypoints, circular import cycles (DFS), high fan-in/fan-out metrics, and directory hierarchy.
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
wia architecture [--workspace PATH]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
### 8. `wia impact` โ Refactoring Impact Analysis
|
|
163
|
+
|
|
164
|
+
Evaluates downstream callers and file importers for a given target symbol or file, assigning an evidence-backed change risk classification (`LOW`, `MEDIUM`, `HIGH`).
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
wia impact <symbol_or_file> [--workspace PATH]
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
### 9. `wia explain` โ Developer-Level Code & Symbol Explanation
|
|
173
|
+
|
|
174
|
+
Generates a complete technical explanation answering: *"What is this code, what does it do, why does it exist, how does it work, how does it fit into the project, what depends on it, and what should a developer know before modifying it?"*
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
wia explain <file_or_symbol> [--workspace PATH]
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
### 10. `wia ask` โ Grounded AI Reasoning Agent
|
|
183
|
+
|
|
184
|
+
Answers natural language developer questions grounded in indexed workspace evidence using query intent classification (`ARCHITECTURE`, `WORKFLOW`, `COMPONENT`, `STORAGE`, `FILE_SYMBOL`, `GENERAL`).
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
wia ask "<question>" [--workspace PATH]
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
### 11. `wia report` โ Generate HTML Intelligence Dashboard
|
|
193
|
+
|
|
194
|
+
Compiles all workspace intelligence into a self-contained, batch-accumulating HTML report (`wia-report.html`).
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
wia report [--workspace PATH] [--output FILE]
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
### 12. `wia search` โ Query Workspace Symbols & Files
|
|
203
|
+
|
|
204
|
+
Executes relevance-scored search across declared AST symbols, function definitions, classes, and file paths.
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
wia search <query> [--workspace PATH] [--language LANG] [--type TYPE] [--limit N]
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
### 13. `wia summary` โ Export LLM RAG Context Markdown
|
|
213
|
+
|
|
214
|
+
Exports a structured Markdown summary of the workspace suitable for prompt context injection into external LLMs.
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
wia summary [--workspace PATH] [--output summary.md]
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
### 14. `wia doctor` โ Environment Health Diagnostic Check
|
|
223
|
+
|
|
224
|
+
Runs system diagnostics verifying Python version, installed package entrypoints, SQLite database connectivity, and Git CLI availability.
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
wia doctor
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## ๐งช Testing & Quality Assurance
|
|
233
|
+
|
|
234
|
+
WIA includes a comprehensive automated suite of 154 unit, CLI, and integration tests using `pytest`.
|
|
235
|
+
|
|
236
|
+
To run the complete test suite:
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
python -m pytest
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
**Current Test Status**: `154 passed`.
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## ๐๏ธ Architecture & Internal Subsystem Design
|
|
247
|
+
|
|
248
|
+
```text
|
|
249
|
+
WIA CLI (app.py)
|
|
250
|
+
โ
|
|
251
|
+
โผ
|
|
252
|
+
Service Layer Orchestration
|
|
253
|
+
(IndexingService, StatusService, ExplanationService)
|
|
254
|
+
โ
|
|
255
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
256
|
+
โผ โผ โผ
|
|
257
|
+
Core Inspection Specialized Analyzers Knowledge & Storage
|
|
258
|
+
- FileDiscovery - ASTParser (Python AST) - WorkspaceIndex
|
|
259
|
+
- FileFilter & Gitignore - ManifestParser (pyproject) - WorkspaceGraph
|
|
260
|
+
- FileHasher (SHA-256) - SecretScanner (Masking) - SQLiteStore
|
|
261
|
+
- LanguageDetector - GitAnalyzer - VectorStore
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
## ๐ License
|
|
267
|
+
|
|
268
|
+
Distributed under the MIT License. See `LICENSE` for more information.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "wia-agent"
|
|
7
|
+
version = "0.1.1"
|
|
8
|
+
description = "Workspace Intelligence Agent โ Indexing and understanding software repositories"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "WIA Developer Team" }
|
|
14
|
+
]
|
|
15
|
+
keywords = ["workspace", "code intelligence", "cli", "indexer", "developer-tools"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"License :: OSI Approved :: MIT License",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
26
|
+
]
|
|
27
|
+
dependencies = [
|
|
28
|
+
"click>=8.1.0",
|
|
29
|
+
"pathspec>=0.11.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/Yashwanth112004/Workspace-Intelligence-Agent"
|
|
34
|
+
Repository = "https://github.com/Yashwanth112004/Workspace-Intelligence-Agent.git"
|
|
35
|
+
"Bug Tracker" = "https://github.com/Yashwanth112004/Workspace-Intelligence-Agent/issues"
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
dev = [
|
|
39
|
+
"pytest>=7.4.0",
|
|
40
|
+
"build>=1.0.0",
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[project.scripts]
|
|
44
|
+
wia = "wia.cli.app:cli_entrypoint"
|
|
45
|
+
|
|
46
|
+
[tool.setuptools.packages.find]
|
|
47
|
+
where = ["."]
|
|
48
|
+
include = ["wia*"]
|
|
49
|
+
|
|
50
|
+
[tool.pytest.ini_options]
|
|
51
|
+
minversion = "7.0"
|
|
52
|
+
addopts = "-ra -q"
|
|
53
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Code analyzers package for WIA."""
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Code structural intelligence analyzer package."""
|