PR #7: Command Cleanup & Documentation

README.md

@@ -94,30 +94,144 @@ Read the [official documentation](https://codepathfinder.dev/), or run `pathfind
 
 ## Usage
 
+### Scan Command (Interactive)
+
+```bash
+# Basic scan
+pathfinder scan --rules rules/ --project /path/to/project
+
+# With verbose output
+pathfinder scan --rules rules/ --project . --verbose
+
+# With debug output
+pathfinder scan --rules rules/ --project . --debug
+
+# Fail on specific severities
+pathfinder scan --rules rules/ --project . --fail-on=critical,high
+```
+
+### CI Command (Machine-Readable)
+
+```bash
+# JSON output
+pathfinder ci --rules rules/ --project . --output json > results.json
+
+# CSV output
+pathfinder ci --rules rules/ --project . --output csv > results.csv
+
+# SARIF output (GitHub Code Scanning)
+pathfinder ci --rules rules/ --project . --output sarif > results.sarif
+
+# With failure control
+pathfinder ci --rules rules/ --project . --output json --fail-on=critical
+```
+
+## Output Formats
+
+### Text Output (Default for scan)
+
+```
+Code Pathfinder Security Scan
+
+Results:
+
+Critical Issues (1):
+
+  [critical] [Taint-Local] command-injection: Command Injection
+    CWE-78 | A1:2017
+
+    auth/login.py:127
+      > 125 |     user_input = request.form['username']
+        126 |     # Process input
+      > 127 |     os.system(f"echo {user_input}")
+
+    Flow: user_input (line 125) -> os.system (line 127)
+    Confidence: High | Detection: Intra-procedural taint analysis
+
+Summary:
+  1 findings across 10 rules
+  1 critical
+```
+
+### JSON Output
+
+```json
+{
+  "tool": {
+    "name": "Code Pathfinder",
+    "version": "0.0.25"
+  },
+  "scan": {
+    "target": "/path/to/project",
+    "rules_executed": 10
+  },
+  "results": [
+    {
+      "rule_id": "command-injection",
+      "severity": "critical",
+      "location": {
+        "file": "auth/login.py",
+        "line": 127
+      },
+      "detection": {
+        "type": "taint-local",
+        "source": {"line": 125, "variable": "user_input"},
+        "sink": {"line": 127, "call": "os.system"}
+      }
+    }
+  ],
+  "summary": {
+    "total": 1,
+    "by_severity": {"critical": 1}
+  }
+}
+```
+
+### CSV Output
+
+```csv
+severity,confidence,rule_id,rule_name,cwe,owasp,file,line,column,function,message,detection_type,detection_scope,source_line,sink_line,tainted_var,sink_call
+critical,high,command-injection,Command Injection,CWE-78,A1:2017,auth/login.py,127,8,login,User input flows to shell,taint-local,local,125,127,user_input,os.system
+```
+
+### SARIF Output
+
+SARIF 2.1.0 compatible output for GitHub Code Scanning integration.
+
 ```bash
-$ cd sourcecode-parser
-
-$ gradle buildGo (or) npm install -g codepathfinder
-
-$ ./pathfinder query --project <path_to_project> --stdin
-2024/06/30 21:35:29 Graph built successfully
-Path-Finder Query Console: 
->FROM method_declaration AS md 
- WHERE md.getName() == "getPaneChanges"
- SELECT md, "query for pane changes layout methods"
-Executing query: FROM method_declaration AS md WHERE md.getName() == "getPaneChanges"
-
-┌───┬──────────────────────────────────────────┬─────────────┬────────────────────┬────────────────┬──────────────────────────────────────────────────────────────┐
-│ # │ FILE                                     │ LINE NUMBER │ TYPE               │ NAME           │ CODE SNIPPET                                                 │
-├───┼──────────────────────────────────────────┼─────────────┼────────────────────┼────────────────┼──────────────────────────────────────────────────────────────┤
-│ 1 │ /Users/shiva/src/code-pathfinder/test-sr │         148 │ method_declaration │ getPaneChanges │ protected void getPaneChanges() throws ClassCastException {  │
-│   │ c/android/app/src/main/java/com/ivb/udac │             │                    │                │         mTwoPane = findViewById(R.id.movie_detail_container) │
-│   │ ity/movieListActivity.java               │             │                    │                │  != null;                                                    │
-│   │                                          │             │                    │                │     }                                                        │
-└───┴──────────────────────────────────────────┴─────────────┴────────────────────┴────────────────┴──────────────────────────────────────────────────────────────┘
-Path-Finder Query Console: 
->:quit
-Okay, Bye!
+# Upload to GitHub Code Scanning
+gh api /repos/:owner/:repo/code-scanning/sarifs -F [email protected]
+```
+
+## Verbosity Levels
+
+| Flag | Output |
+|------|--------|
+| (default) | Clean results only |
+| `--verbose` | Results + progress + statistics |
+| `--debug` | All output + timestamps |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (no findings, or findings without --fail-on match) |
+| 1 | Findings match --fail-on severities |
+| 2 | Configuration or execution error |
+
+### Examples
+
+```bash
+# Default: always exit 0
+pathfinder scan --rules rules/ --project .
+echo $?  # 0 even with findings
+
+# Fail on critical or high
+pathfinder scan --rules rules/ --project . --fail-on=critical,high
+echo $?  # 1 if critical/high found, 0 otherwise
+
+# Fail on any finding
+pathfinder scan --rules rules/ --project . --fail-on=critical,high,medium,low
 ```
 
 ## Acknowledgements

sourcecode-parser/cli.md

@@ -0,0 +1,163 @@
+# CLI Reference
+
+## Commands
+
+### scan
+
+Interactive security scanning with human-readable output.
+
+**Usage**:
+```bash
+pathfinder scan --rules <path> --project <path> [flags]
+```
+
+**Required Flags**:
+- `--rules, -r` - Path to rules file or directory
+- `--project, -p` - Path to project to scan
+
+**Optional Flags**:
+- `--verbose, -v` - Show progress and statistics
+- `--debug` - Show debug diagnostics with timestamps
+- `--fail-on` - Fail with exit code 1 if findings match severities
+
+**Examples**:
+```bash
+# Basic scan
+pathfinder scan --rules rules/security.py --project /app
+
+# Verbose scan
+pathfinder scan -r rules/ -p . -v
+
+# CI-style failure
+pathfinder scan -r rules/ -p . --fail-on=critical,high
+```
+
+---
+
+### ci
+
+CI/CD optimized scanning with machine-readable output.
+
+**Usage**:
+```bash
+pathfinder ci --rules <path> --project <path> --output <format> [flags]
+```
+
+**Required Flags**:
+- `--rules, -r` - Path to rules file or directory
+- `--project, -p` - Path to project to scan
+- `--output, -o` - Output format: json, csv, sarif
+
+**Optional Flags**:
+- `--verbose, -v` - Show progress and statistics (to stderr)
+- `--debug` - Show debug diagnostics
+- `--fail-on` - Fail with exit code 1 if findings match severities
+
+**Examples**:
+```bash
+# JSON output
+pathfinder ci -r rules/ -p . -o json > results.json
+
+# SARIF for GitHub
+pathfinder ci -r rules/ -p . -o sarif > results.sarif
+
+# CSV with failure control
+pathfinder ci -r rules/ -p . -o csv --fail-on=critical > results.csv
+```
+
+---
+
+### diagnose
+
+Diagnostic mode for debugging rule behavior.
+
+**Usage**:
+```bash
+pathfinder diagnose --rules <path> --project <path> [flags]
+```
+
+---
+
+### version
+
+Display version information.
+
+**Usage**:
+```bash
+pathfinder version
+```
+
+---
+
+## Output Format Reference
+
+### JSON Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tool.name` | string | "Code Pathfinder" |
+| `tool.version` | string | Tool version |
+| `scan.target` | string | Project path |
+| `scan.rules_executed` | int | Number of rules |
+| `results[]` | array | Detection results |
+| `results[].rule_id` | string | Rule identifier |
+| `results[].severity` | string | critical/high/medium/low |
+| `results[].location.file` | string | File path |
+| `results[].location.line` | int | Line number |
+| `results[].detection.type` | string | pattern/taint-local/taint-global |
+| `summary.total` | int | Total findings |
+| `summary.by_severity` | object | Count by severity |
+
+### CSV Columns
+
+1. severity
+2. confidence
+3. rule_id
+4. rule_name
+5. cwe
+6. owasp
+7. file
+8. line
+9. column
+10. function
+11. message
+12. detection_type
+13. detection_scope
+14. source_line
+15. sink_line
+16. tainted_var
+17. sink_call
+
+### SARIF 2.1.0
+
+Compliant with [SARIF 2.1.0 specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html).
+
+Features:
+- Rule metadata with help text
+- Code flows for taint analysis
+- Related locations for sources
+- Security severity scores
+- URI base ID for portable paths
+
+---
+
+## Exit Code Reference
+
+| Code | Constant | Description |
+|------|----------|-------------|
+| 0 | ExitCodeSuccess | No findings, or findings without --fail-on match |
+| 1 | ExitCodeFindings | Findings match at least one --fail-on severity |
+| 2 | ExitCodeError | Configuration or execution error |
+
+### --fail-on Syntax
+
+```bash
+--fail-on=<severity>[,<severity>...]
+```
+
+Valid severities: `critical`, `high`, `medium`, `low`, `info`
+
+Examples:
+- `--fail-on=critical` - Fail only on critical
+- `--fail-on=critical,high` - Fail on critical or high
+- `--fail-on=critical,high,medium,low` - Fail on any finding