plumber-linter 1.1.0 → 1.1.1

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 (2) hide show
  1. package/README.md +142 -80
  2. package/package.json +41 -29
package/README.md CHANGED
@@ -1,80 +1,142 @@
1
- # Plumber — Code Leak, Clog, and AI Slop Inspector
2
-
3
- [![npm version](https://img.shields.io/npm/v/plumber-linter.svg)](https://npmjs.com/package/plumber-linter)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
5
-
6
- **Plumber** is a deterministic, offline-capable code quality and anti-slop linter for the AI-agent era. It inspects codebases in milliseconds without requiring an LLM.
7
-
8
- ---
9
-
10
- ## Quick Start
11
-
12
- No global installation required:
13
- ```bash
14
- # Scan current repository
15
- npx plumber-linter scan .
16
-
17
- # Enforce quality gate (exit 1 on HIGH or CRITICAL issues)
18
- npx plumber-linter scan . --fail-on high
19
-
20
- # Export report as Markdown or JSON
21
- npx plumber-linter scan . --format md
22
- npx plumber-linter scan . --format json
23
-
24
- # View all active inspection rules
25
- npx plumber-linter rules
26
- ```
27
-
28
- ---
29
-
30
- ## Block Bad Commits
31
-
32
- Install a git pre-commit hook that blocks any commit containing API keys, hardcoded
33
- secrets, `.env` files, or unreachable dead code:
34
-
35
- ```bash
36
- npx plumber-linter install-hook
37
- ```
38
-
39
- The hook inspects only staged files (read from the git index, so partially staged
40
- changes are honored). Leaks and `.env` files always block; other findings block at
41
- `HIGH` by default. Tune the threshold or remove the hook:
42
-
43
- ```bash
44
- npx plumber-linter install-hook --fail-on critical
45
- npx plumber-linter uninstall-hook
46
- git commit --no-verify # bypass once
47
- ```
48
-
49
- ---
50
-
51
- ## Remove Dead Code
52
-
53
- ```bash
54
- # Preview unreachable lines (no writes)
55
- npx plumber-linter clean .
56
-
57
- # Delete them
58
- npx plumber-linter clean . --write
59
- ```
60
-
61
- ---
62
-
63
- ## Claude Code & Cursor
64
-
65
- ### Claude Code
66
- Add to your project's `CLAUDE.md`:
67
- ```bash
68
- npx plumber-linter scan . --fail-on high
69
- ```
70
-
71
- ### Cursor
72
- Add to `.cursorrules` and run from the integrated terminal:
73
- ```bash
74
- npx plumber-linter scan .
75
- ```
76
-
77
- ---
78
-
79
- ## License
80
- MIT License.
1
+ # Plumber
2
+
3
+ CI/CD pipeline linter that flags hardcoded secrets, leaked credentials, and dead code — with fixes in plain English.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/plumber-linter.svg)](https://www.npmjs.com/package/plumber-linter)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/parasraju/plumber/blob/main/LICENSE)
7
+
8
+ Plumber inspects codebases and git repositories in milliseconds without requiring an LLM. It enforces quality and security gates in CI/CD pipelines and git pre-commit hooks, exiting with non-zero status when critical or high-severity issues are found.
9
+
10
+ ---
11
+
12
+ ## Installation
13
+
14
+ ```bash
15
+ # Local project dependency
16
+ npm install --save-dev plumber-linter
17
+
18
+ # Global installation
19
+ npm install -g plumber-linter
20
+ ```
21
+
22
+ ---
23
+
24
+ ## Quick Start
25
+
26
+ Run instantly with `npx` (no install required):
27
+
28
+ ```bash
29
+ # Scan current repository
30
+ npx plumber-linter scan .
31
+
32
+ # Enforce quality gate in CI (exit 1 on HIGH or CRITICAL issues)
33
+ npx plumber-linter scan . --fail-on high
34
+
35
+ # Export report as Markdown or JSON
36
+ npx plumber-linter scan . --format md
37
+ npx plumber-linter scan . --format json
38
+
39
+ # View all 21 inspection rules
40
+ npx plumber-linter rules
41
+ ```
42
+
43
+ ### In GitHub Actions
44
+
45
+ ```yaml
46
+ - name: Run Plumber Linter
47
+ run: npx plumber-linter scan . --fail-on high
48
+ ```
49
+
50
+ ### In GitLab CI
51
+
52
+ ```yaml
53
+ plumber-lint:
54
+ image: node:18
55
+ script:
56
+ - npx plumber-linter scan . --fail-on high
57
+ ```
58
+
59
+ ### Git Pre-Commit Hook
60
+
61
+ Install a pre-commit hook that blocks commits containing secrets, `.env` files, or dead code:
62
+
63
+ ```bash
64
+ # Install hook (blocks staged secrets and issues >= HIGH)
65
+ npx plumber-linter install-hook --fail-on high
66
+
67
+ # Uninstall hook
68
+ npx plumber-linter uninstall-hook
69
+ ```
70
+
71
+ ---
72
+
73
+ ## What It Checks
74
+
75
+ ### 1. Leaked Secrets & API Keys (`leak/api-key`, `leak/hardcoded-secret`)
76
+ Detects exposed OpenAI (`sk-...`), GitHub (`ghp_...`), AWS (`AKIA...`), Slack tokens, and database credentials.
77
+ - **Vulnerable:** `const client = new OpenAI({ apiKey: "sk-live1234567890abcdef1234567890" });`
78
+ - **Fixed:** `const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });`
79
+
80
+ ### 2. Committed Environment Files (`leak/committed-env`)
81
+ Prevents committing `.env` files containing live secrets to version control.
82
+ - **Vulnerable:** `.env` committed with production credentials.
83
+ - **Fixed:** Add `.env` to `.gitignore` and commit `.env.example` with blank placeholders.
84
+
85
+ ### 3. Swallowed Exceptions (`clog/swallowed-error`)
86
+ Flags silent failure blocks that swallow exceptions and hide failures in CI/CD pipelines.
87
+ - **Vulnerable:** `try { doWork(); } catch (err) {}`
88
+ - **Fixed:** `try { doWork(); } catch (err) { logger.error(err); throw err; }`
89
+
90
+ ### 4. Unreachable Dead Code (`clog/dead-code`)
91
+ Detects unreachable statements following returns or inside constant-false branches.
92
+ - **Vulnerable:** `return result; console.log("Done");`
93
+ - **Fixed:** Delete unreachable statement (or run `npx plumber-linter clean . --write`).
94
+
95
+ ### 5. AI-Elided Code Snippets (`clog/elided-code`)
96
+ Flags lazy AI elision comments like `// ... existing code ...` left behind in source files.
97
+ - **Vulnerable:** `// ... existing code ...`
98
+ - **Fixed:** Restore the full function or component implementation.
99
+
100
+ ### 6. Non-Semantic / Inaccessible Elements (`joint/clickable-div`)
101
+ Identifies non-semantic clickable elements lacking accessible keyboard and screen-reader controls.
102
+ - **Vulnerable:** `<div onClick={handleClick}>Submit</div>`
103
+ - **Fixed:** `<button type="button" onClick={handleClick}>Submit</button>`
104
+
105
+ ### 7. Hallucinated / Undeclared Dependencies (`pipe/phantom-import`)
106
+ Spots hallucinated library imports invented by LLMs or packages missing from project manifests.
107
+ - **Vulnerable:** `import { useFeature } from "next-auth-v5-helpers";`
108
+ - **Fixed:** Use standard verified libraries and declare dependencies in manifests.
109
+
110
+ ---
111
+
112
+ ## Example Output
113
+
114
+ ```text
115
+ ================================================================
116
+ PLUMBER INSPECTION REPORT: my-service
117
+ Health Score: 87.4/100 | Grade: B | Files: 18
118
+ Issues Detected: 2
119
+ ================================================================
120
+
121
+ [FILE] src/config.ts
122
+ L14 [CRITICAL] Leaked OpenAI / Model API Key
123
+ Found: const key = "sk-live9876543210..."
124
+ Fix: Move secret to environment variable (.env).
125
+
126
+ [FILE] src/pipeline.ts
127
+ L58 [HIGH] Swallowed Exception (Silent Failure)
128
+ Found: catch (e) {}
129
+ Fix: Log the error or properly re-raise/handle it.
130
+
131
+ ================================================================
132
+
133
+ [FAILED] Found issues at or above severity: HIGH
134
+ ```
135
+
136
+ ---
137
+
138
+ ## Links
139
+
140
+ - **npm Package:** [https://www.npmjs.com/package/plumber-linter](https://www.npmjs.com/package/plumber-linter)
141
+ - **Website & Documentation:** [https://plumber-7dv.pages.dev/](https://plumber-7dv.pages.dev/)
142
+ - **GitHub Repository:** [https://github.com/parasraju/plumber](https://github.com/parasraju/plumber)
package/package.json CHANGED
@@ -1,29 +1,41 @@
1
- {
2
- "name": "plumber-linter",
3
- "version": "1.1.0",
4
- "description": "Deterministic Code Leak, Clog, and AI Slop Inspector for the AI-agent era",
5
- "main": "bin/plumber.js",
6
- "bin": {
7
- "plumber": "bin/plumber.js",
8
- "plumber-linter": "bin/plumber.js"
9
- },
10
- "keywords": [
11
- "linter",
12
- "ai-slop",
13
- "mcp",
14
- "mcp-server",
15
- "code-quality",
16
- "secrets-detection",
17
- "claude-code",
18
- "cursor"
19
- ],
20
- "author": "Paras Raju",
21
- "license": "MIT",
22
- "engines": {
23
- "node": ">=18.0.0"
24
- },
25
- "files": [
26
- "bin",
27
- "README.md"
28
- ]
29
- }
1
+ {
2
+ "name": "plumber-linter",
3
+ "version": "1.1.1",
4
+ "description": "CI/CD pipeline linter that flags hardcoded secrets, leaked credentials, and dead code — with fixes in plain English.",
5
+ "main": "bin/plumber.js",
6
+ "bin": {
7
+ "plumber": "bin/plumber.js",
8
+ "plumber-linter": "bin/plumber.js"
9
+ },
10
+ "keywords": [
11
+ "linter",
12
+ "github-actions",
13
+ "gitlab",
14
+ "ci-cd",
15
+ "pipeline-security",
16
+ "secrets-detection",
17
+ "code-quality",
18
+ "devsecops",
19
+ "security",
20
+ "github",
21
+ "workflow",
22
+ "cli"
23
+ ],
24
+ "author": "Paras Raju",
25
+ "license": "MIT",
26
+ "repository": {
27
+ "type": "git",
28
+ "url": "git+https://github.com/parasraju/plumber.git"
29
+ },
30
+ "bugs": {
31
+ "url": "https://github.com/parasraju/plumber/issues"
32
+ },
33
+ "homepage": "https://github.com/parasraju/plumber#readme",
34
+ "engines": {
35
+ "node": ">=18.0.0"
36
+ },
37
+ "files": [
38
+ "bin",
39
+ "README.md"
40
+ ]
41
+ }