Metadata-Version: 2.4
Name: spec-probe
Version: 0.1.10
Summary: Verify C/C++ modules implement functional requirements from spec (LangGraph + LLM)
Author: taikt
License-Expression: MIT
Project-URL: Homepage, https://github.com/taikt/spec-probe
Project-URL: Documentation, https://github.com/taikt/spec-probe/blob/main/QUICKSTART.md
Project-URL: Repository, https://github.com/taikt/spec-probe
Project-URL: Issues, https://github.com/taikt/spec-probe/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph>=0.2
Requires-Dist: langchain-core>=0.3
Requires-Dist: langchain-openai>=0.2
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: loguru>=0.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: requests>=2.31
Requires-Dist: markitdown>=0.1
Requires-Dist: mammoth>=1.8
Requires-Dist: atlassian-python-api>=3.40
Requires-Dist: markdown>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Provides-Extra: rag
Requires-Dist: langchain-community>=0.3; extra == "rag"
Requires-Dist: langchain-huggingface>=0.1; extra == "rag"
Requires-Dist: sentence-transformers>=3.0; extra == "rag"
Requires-Dist: faiss-cpu>=1.8; extra == "rag"
Dynamic: license-file

# spec-probe

Check code against functional requirements in a spec (`.md` / `.docx` / `.pdf`). Use **VS Code Copilot** chat (`/spec-cover`, …) or the **`spec-probe`** CLI.

---

## Workflow Overview


| Type                         | Step                | Action                                                | Description                                               |
| :----------------------------- | :-------------------- | :------------------------------------------------------ | :---------------------------------------------------------- |
| **One-time** *(Run once)*    | 1. Install & Skills | `pip install spec-probe && spec-probe-skill --vscode` | Sets up package,`.venv`, and Copilot skills               |
|                              | 2. Auth             | `spec-probe-copilot-login`                            | Authenticates Copilot token via Device Flow               |
|                              | 3. Configure        | `~/.config/spec-probe/config.yaml`                    | Sets`module_path`, `spec_path`, `related_modules`         |
|                              | 4. Index Code       | `spec-probe-codegraph`                                | Builds symbol & call-graph index (excluding tests/mocks)  |
|                              | 5. Domain Pack      | `/spec-pack` *(in chat)*                              | Extracts domain glossary, acronyms, and heuristics        |
|                              | 6. Parse Spec       | `/spec-cover parse spec summary` *(in chat)*          | Parses spec into requirements catalog in`reports/specs/`  |
| **Daily** *(Run repeatedly)* | 1. Verify FRs       | `/spec-cover verify FR ...` *(in chat)*               | Verifies functional requirements against source code      |
|                              | 2. Export Report    | `/spec-cover write report` *(in chat)*                | Exports full markdown report to`reports/verifications/`   |
|                              | 3. Audit Report     | `/spec-audit` *(in chat)*                             | Audits coverage, validates evidence chains, confirms gaps |

---

## 1. One-Time Setup

### Step 1: Install & Skills

```bash
pip install spec-probe
spec-probe-skill --vscode
```

- Installs `spec-probe` and sets up Copilot skills in `~/.copilot/skills/`.
- Initializes user directory and `.venv` under `~/.config/spec-probe/`.
- **Reload VS Code** after running `spec-probe-skill`.

Optional for Linux: `sudo apt install ripgrep` (faster grep search).

### Step 2: Authenticate & API Keys (`.env`)

#### GitHub Copilot Token

```bash
spec-probe-copilot-login
```

1. Open `https://github.com/login/device` in your browser.
2. Enter the 8-character code displayed in the terminal.
3. Token is saved automatically to `COPILOT_GITHUB_TOKEN` in `~/.config/spec-probe/.env`.

#### Exacode API Key (Optional)

Used for auxiliary LLM jobs (`enrich`, `translate`, `wiki`, `report`).

1. Open `http://exacode-chat.lge.com/key/` (or clear and re-create your key).
2. Copy **Key 2 (EXACODE SWE API)**.
3. Add to `~/.config/spec-probe/.env`:
   ```bash
   EXACODE_API_KEY="your_key_2_here"
   EXACODE_BASE_URL="http://exacode-chat.lge.com/v1"
   ```

*(Details: [Exacode for Copilot Chat](http://collab.lge.com/main/spaces/~tai2.tran/pages/3695262088/Exacode+for+Copilot+Chat))*

### Step 3: Configure Target Paths (`config.yaml`)

Edit `~/.config/spec-probe/config.yaml` (use absolute paths):

```yaml
input:
  module_path: /abs/path/to/your/app
  spec_path: /abs/path/to/spec.docx
  related_modules:
    # paths:
    #   - /abs/path/to/shared/service
```

### Step 4: Index Code with Codegraph (Optional)

Accelerates symbol search and call-graph expansion across large C/C++ codebases:

```bash
spec-probe-codegraph
```

*Reads `module_path` and `related_modules.paths` from `config.yaml` automatically. You can also specify paths directly: `spec-probe-codegraph /path1 /path2`. Tests and mocks are excluded automatically. Re-running syncs changes.*

### Step 5: Draft Domain Pack (Run once per module)

In VS Code Copilot chat:

```
/spec-pack
```

Scans your module code and draft a domain pack with keywords, architecture layers, and terminology under `~/.config/spec-probe/packs/`.

### Step 6: Parse Spec (Run once per spec)

In VS Code Copilot chat:

```
/spec-cover parse spec summary
```

Parses the requirements document into a structured catalog cached under `~/.config/spec-probe/reports/specs/` so subsequent verifications are fast.

---

## 2. Daily Workflow (VS Code Copilot Chat)

Once one-time setup is complete, use chat for regular verification:

### Step 1: Verify Requirements (`/spec-cover`)

- Verify a specific requirement:
  ```
  /spec-cover verify FR-001
  ```
- Or verify by requirement text:
  ```
  /spec-cover check requirement: The module shall initialize within 500ms
  ```
- Or verify a section:
  ```
  /spec-cover verify section 3.2
  ```

*(Note: In Copilot chat, typing naturally without `/spec-cover` like `verify FR-001` also works via auto-intent matching, but `/spec-cover ...` is recommended for explicit routing).*

### Step 2: Export Report File

After verification completes in chat, type:

```
/spec-cover write report
```

Generates a full Markdown report under `~/.config/spec-probe/reports/verifications/` with clickable file links and evidence snippets.

### Step 3: Audit Report (`/spec-audit`)

```
/spec-audit
```

Treats tool verdicts as hypotheses, validates evidence chains directly against source code, and confirms any actual implementation gaps.

---

## CLI (optional)

```bash
spec-probe verify --module /abs/app --spec /abs/spec.md --fr FR-001
spec-probe check "The module shall …"
spec-probe parse --spec /abs/spec.md --summary
```

Paths default from `~/.config/spec-probe/config.yaml` when omitted.
