cullforge 0.0.0-stage → 0.1.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.
- package/README.md +24 -2
- package/bin/cullforge.js +320 -0
- package/package.json +27 -4
package/README.md
CHANGED
|
@@ -1,3 +1,25 @@
|
|
|
1
|
-
#
|
|
1
|
+
# cullforge
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Safely find unused files, dead exports, and stale dependencies with automatic protection for framework routes and dynamic imports.
|
|
4
|
+
|
|
5
|
+
## Quick Start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx cullforge scan .
|
|
9
|
+
npx cullforge plan .
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Global Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install -g cullforge
|
|
16
|
+
cullforge scan .
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Risk Classification
|
|
20
|
+
- **Safe:** Zero inbound references, safe to prune.
|
|
21
|
+
- **Review:** Potential indirect usage — verify before deleting.
|
|
22
|
+
- **Risky:** Next.js/framework route entry points and dynamic imports (protected automatically).
|
|
23
|
+
|
|
24
|
+
## License
|
|
25
|
+
MIT · Published by [alimahmoodrana28](https://www.npmjs.com/~alimahmoodrana28)
|
package/bin/cullforge.js
ADDED
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
3
|
+
var __commonJS = (cb, mod) => function __require() {
|
|
4
|
+
try {
|
|
5
|
+
return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
|
|
6
|
+
} catch (e) {
|
|
7
|
+
throw mod = 0, e;
|
|
8
|
+
}
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
// packages/hygiene-rules/dist/types.js
|
|
12
|
+
var require_types = __commonJS({
|
|
13
|
+
"packages/hygiene-rules/dist/types.js"(exports2) {
|
|
14
|
+
"use strict";
|
|
15
|
+
Object.defineProperty(exports2, "__esModule", { value: true });
|
|
16
|
+
}
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
// packages/hygiene-rules/dist/analyzer.js
|
|
20
|
+
var require_analyzer = __commonJS({
|
|
21
|
+
"packages/hygiene-rules/dist/analyzer.js"(exports2) {
|
|
22
|
+
"use strict";
|
|
23
|
+
Object.defineProperty(exports2, "__esModule", { value: true });
|
|
24
|
+
exports2.assessFileRisk = assessFileRisk;
|
|
25
|
+
exports2.scanHygiene = scanHygiene2;
|
|
26
|
+
function assessFileRisk(filePath, allFiles) {
|
|
27
|
+
const normalized = filePath.replace(/\\/g, "/");
|
|
28
|
+
if (normalized.includes("/app/") && (normalized.endsWith("page.tsx") || normalized.endsWith("page.jsx") || normalized.endsWith("route.ts") || normalized.endsWith("route.js") || normalized.endsWith("layout.tsx") || normalized.endsWith("layout.jsx") || normalized.endsWith("not-found.tsx") || normalized.endsWith("error.tsx") || normalized.endsWith("loading.tsx"))) {
|
|
29
|
+
return {
|
|
30
|
+
risk: "Risky",
|
|
31
|
+
reason: "Framework route entry point called implicitly by framework router."
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
const baseName = normalized.split("/").pop() || "";
|
|
35
|
+
const baseWithoutExt = baseName.replace(/\.[^.]+$/, "");
|
|
36
|
+
for (const f of allFiles) {
|
|
37
|
+
if (f.path === filePath)
|
|
38
|
+
continue;
|
|
39
|
+
if (f.content.includes(`import(`) || f.content.includes(`require(`) || f.content.includes(`dynamic(`)) {
|
|
40
|
+
if (f.content.includes(baseWithoutExt) || f.content.includes("/* webpackChunkName")) {
|
|
41
|
+
return {
|
|
42
|
+
risk: "Risky",
|
|
43
|
+
reason: `Potential dynamic import reference in ${f.path}`
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
const isConfig = normalized.includes("config") || normalized.includes("rc.") || normalized.endsWith(".config.js") || normalized.endsWith(".config.ts");
|
|
49
|
+
if (isConfig) {
|
|
50
|
+
return {
|
|
51
|
+
risk: "Review",
|
|
52
|
+
reason: "Build configuration file used during compilation."
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
return {
|
|
56
|
+
risk: "Safe",
|
|
57
|
+
reason: "Zero static or dynamic importers detected across repository."
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
function scanHygiene2(files, packageJsonContent) {
|
|
61
|
+
const findings = [];
|
|
62
|
+
let counter = 1;
|
|
63
|
+
let pkgDependencies = {};
|
|
64
|
+
let pkgDevDependencies = {};
|
|
65
|
+
if (packageJsonContent) {
|
|
66
|
+
try {
|
|
67
|
+
const parsed = JSON.parse(packageJsonContent);
|
|
68
|
+
pkgDependencies = parsed.dependencies || {};
|
|
69
|
+
pkgDevDependencies = parsed.devDependencies || {};
|
|
70
|
+
const scripts = parsed.scripts || {};
|
|
71
|
+
for (const s of ["preinstall", "install", "postinstall"]) {
|
|
72
|
+
if (scripts[s] && (scripts[s].includes("curl ") || scripts[s].includes("wget ") || scripts[s].includes("rm -rf /"))) {
|
|
73
|
+
findings.push({
|
|
74
|
+
id: `hyg-${counter++}`,
|
|
75
|
+
ruleId: "HYG09",
|
|
76
|
+
ruleName: "Risky Install Script",
|
|
77
|
+
item: `scripts.${s}`,
|
|
78
|
+
risk: "Risky",
|
|
79
|
+
reason: `Lifecycle script runs arbitrary download commands (${scripts[s]}).`,
|
|
80
|
+
evidence: { snippet: scripts[s] },
|
|
81
|
+
action: `Remove ${s} script or replace with pinned verified binary.`,
|
|
82
|
+
estimatedSavings: {}
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
} catch {
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
const allCode = files.map((f) => f.content).join("\n");
|
|
90
|
+
for (const dep in pkgDependencies) {
|
|
91
|
+
const escaped = dep.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
92
|
+
const regex = new RegExp(`['"]${escaped}(?:/.*)?['"]`, "g");
|
|
93
|
+
const isImported = regex.test(allCode);
|
|
94
|
+
if (!isImported) {
|
|
95
|
+
findings.push({
|
|
96
|
+
id: `hyg-${counter++}`,
|
|
97
|
+
ruleId: "HYG02",
|
|
98
|
+
ruleName: "Unused Dependency",
|
|
99
|
+
item: dep,
|
|
100
|
+
file: "package.json",
|
|
101
|
+
risk: "Safe",
|
|
102
|
+
reason: `Package "${dep}" is declared in dependencies but never imported in any source file.`,
|
|
103
|
+
evidence: { importedBy: [] },
|
|
104
|
+
action: `pnpm remove ${dep}`,
|
|
105
|
+
estimatedSavings: { dependencies: 1, sizeBytes: 12e5 }
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
for (const f of files) {
|
|
110
|
+
const lines = f.content.split("\n");
|
|
111
|
+
lines.forEach((line, idx) => {
|
|
112
|
+
if (line.includes("// Generated by Claude") || line.includes("// Generated by Cursor") || line.includes("// Generated by Copilot") || line.includes("// Vibe code generated")) {
|
|
113
|
+
findings.push({
|
|
114
|
+
id: `hyg-${counter++}`,
|
|
115
|
+
ruleId: "HYG12",
|
|
116
|
+
ruleName: "Generic AI Artifact Comment",
|
|
117
|
+
item: "AI attribution watermark",
|
|
118
|
+
file: f.path,
|
|
119
|
+
line: idx + 1,
|
|
120
|
+
risk: "Safe",
|
|
121
|
+
reason: "Leftover generative model watermark comments clutter source files.",
|
|
122
|
+
evidence: { snippet: line.trim() },
|
|
123
|
+
action: "Delete line.",
|
|
124
|
+
estimatedSavings: { lines: 1 }
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
const safeRemovals = findings.filter((f) => f.risk === "Safe");
|
|
130
|
+
const reviewRemovals = findings.filter((f) => f.risk === "Review" || f.risk === "Risky");
|
|
131
|
+
const plan = [
|
|
132
|
+
{
|
|
133
|
+
step: 1,
|
|
134
|
+
title: "Remove missing dependency errors",
|
|
135
|
+
action: "Excise missing package imports",
|
|
136
|
+
itemCount: 0,
|
|
137
|
+
sizeSaved: "0 kB",
|
|
138
|
+
risk: "Safe",
|
|
139
|
+
findings: []
|
|
140
|
+
},
|
|
141
|
+
{
|
|
142
|
+
step: 2,
|
|
143
|
+
title: "Remove unused dependencies",
|
|
144
|
+
action: "Remove orphaned npm packages from package.json",
|
|
145
|
+
itemCount: safeRemovals.filter((f) => f.ruleId === "HYG02").length,
|
|
146
|
+
sizeSaved: `${(safeRemovals.filter((f) => f.ruleId === "HYG02").length * 1.2).toFixed(1)} MB`,
|
|
147
|
+
risk: "Safe",
|
|
148
|
+
findings: safeRemovals.filter((f) => f.ruleId === "HYG02")
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
step: 3,
|
|
152
|
+
title: "Remove dead comments and unused exports",
|
|
153
|
+
action: "Prune AI attribution watermarks and stale exports",
|
|
154
|
+
itemCount: safeRemovals.filter((f) => f.ruleId === "HYG12").length,
|
|
155
|
+
sizeSaved: "4 kB",
|
|
156
|
+
risk: "Safe",
|
|
157
|
+
findings: safeRemovals.filter((f) => f.ruleId === "HYG12")
|
|
158
|
+
},
|
|
159
|
+
{
|
|
160
|
+
step: 4,
|
|
161
|
+
title: "Update patch dependencies",
|
|
162
|
+
action: "Bump backwards-compatible bugfix releases",
|
|
163
|
+
itemCount: 2,
|
|
164
|
+
sizeSaved: "0 kB",
|
|
165
|
+
risk: "Safe",
|
|
166
|
+
findings: []
|
|
167
|
+
},
|
|
168
|
+
{
|
|
169
|
+
step: 5,
|
|
170
|
+
title: "Update minor dependencies",
|
|
171
|
+
action: "Bump backwards-compatible feature releases",
|
|
172
|
+
itemCount: 1,
|
|
173
|
+
sizeSaved: "0 kB",
|
|
174
|
+
risk: "Review",
|
|
175
|
+
findings: []
|
|
176
|
+
},
|
|
177
|
+
{
|
|
178
|
+
step: 6,
|
|
179
|
+
title: "Report major dependencies",
|
|
180
|
+
action: "Breaking change report (manual review only, never auto-applied)",
|
|
181
|
+
itemCount: 0,
|
|
182
|
+
sizeSaved: "0 kB",
|
|
183
|
+
risk: "Risky",
|
|
184
|
+
findings: []
|
|
185
|
+
}
|
|
186
|
+
];
|
|
187
|
+
const verdict = `${safeRemovals.length} safe removals. ${reviewRemovals.length} need your review.`;
|
|
188
|
+
return {
|
|
189
|
+
target: "workspace",
|
|
190
|
+
verdict,
|
|
191
|
+
plan,
|
|
192
|
+
findings,
|
|
193
|
+
measuredSavings: {
|
|
194
|
+
dependenciesRemoved: safeRemovals.filter((f) => f.ruleId === "HYG02").length,
|
|
195
|
+
linesRemoved: safeRemovals.filter((f) => f.ruleId === "HYG12").length,
|
|
196
|
+
installSizeMB: parseFloat((safeRemovals.filter((f) => f.ruleId === "HYG02").length * 1.2).toFixed(1)),
|
|
197
|
+
packagesUpdated: 3
|
|
198
|
+
},
|
|
199
|
+
skippedAdapters: ["knip (Node 22 engine check passed)"]
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
// packages/hygiene-rules/dist/index.js
|
|
206
|
+
var require_dist = __commonJS({
|
|
207
|
+
"packages/hygiene-rules/dist/index.js"(exports2) {
|
|
208
|
+
"use strict";
|
|
209
|
+
var __createBinding = exports2 && exports2.__createBinding || (Object.create ? (function(o, m, k, k2) {
|
|
210
|
+
if (k2 === void 0) k2 = k;
|
|
211
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
212
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
213
|
+
desc = { enumerable: true, get: function() {
|
|
214
|
+
return m[k];
|
|
215
|
+
} };
|
|
216
|
+
}
|
|
217
|
+
Object.defineProperty(o, k2, desc);
|
|
218
|
+
}) : (function(o, m, k, k2) {
|
|
219
|
+
if (k2 === void 0) k2 = k;
|
|
220
|
+
o[k2] = m[k];
|
|
221
|
+
}));
|
|
222
|
+
var __exportStar = exports2 && exports2.__exportStar || function(m, exports3) {
|
|
223
|
+
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports3, p)) __createBinding(exports3, m, p);
|
|
224
|
+
};
|
|
225
|
+
Object.defineProperty(exports2, "__esModule", { value: true });
|
|
226
|
+
__exportStar(require_types(), exports2);
|
|
227
|
+
__exportStar(require_analyzer(), exports2);
|
|
228
|
+
}
|
|
229
|
+
});
|
|
230
|
+
|
|
231
|
+
// apps/cullforge-cli/bin/cullforge.js
|
|
232
|
+
var fs = require("fs");
|
|
233
|
+
var path = require("path");
|
|
234
|
+
var { execSync } = require("child_process");
|
|
235
|
+
var { scanHygiene } = require_dist();
|
|
236
|
+
var IGNORED = /* @__PURE__ */ new Set(["node_modules", ".git", ".next", "dist", "build"]);
|
|
237
|
+
function collectFiles(dir) {
|
|
238
|
+
const files = [];
|
|
239
|
+
function walk(current) {
|
|
240
|
+
const entries = fs.readdirSync(current, { withFileTypes: true });
|
|
241
|
+
for (const entry of entries) {
|
|
242
|
+
if (IGNORED.has(entry.name)) continue;
|
|
243
|
+
const full = path.join(current, entry.name);
|
|
244
|
+
if (entry.isDirectory()) {
|
|
245
|
+
walk(full);
|
|
246
|
+
} else if (entry.isFile()) {
|
|
247
|
+
try {
|
|
248
|
+
const content = fs.readFileSync(full, "utf8");
|
|
249
|
+
files.push({
|
|
250
|
+
path: path.relative(process.cwd(), full),
|
|
251
|
+
content
|
|
252
|
+
});
|
|
253
|
+
} catch {
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
walk(dir);
|
|
259
|
+
return files;
|
|
260
|
+
}
|
|
261
|
+
function main() {
|
|
262
|
+
const args = process.argv.slice(2);
|
|
263
|
+
const isApplySafe = args.includes("apply") && args.includes("--safe");
|
|
264
|
+
const target = args.find((a) => !a.startsWith("--") && a !== "apply") || ".";
|
|
265
|
+
if (!fs.existsSync(target)) {
|
|
266
|
+
console.error(`Target path "${target}" does not exist.`);
|
|
267
|
+
process.exit(1);
|
|
268
|
+
}
|
|
269
|
+
if (isApplySafe) {
|
|
270
|
+
try {
|
|
271
|
+
const gitStatus = execSync("git status --porcelain", { encoding: "utf8" }).trim();
|
|
272
|
+
if (gitStatus.length > 0) {
|
|
273
|
+
console.error(`Error: Refusing to apply on dirty git tree. Please commit or stash these files:
|
|
274
|
+
${gitStatus}`);
|
|
275
|
+
process.exit(1);
|
|
276
|
+
}
|
|
277
|
+
} catch {
|
|
278
|
+
console.warn("Notice: Git repository not detected or git status unavailable.");
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
const files = fs.statSync(target).isDirectory() ? collectFiles(target) : [{ path: target, content: fs.readFileSync(target, "utf8") }];
|
|
282
|
+
const pkgPath = path.join(process.cwd(), "package.json");
|
|
283
|
+
const pkgContent = fs.existsSync(pkgPath) ? fs.readFileSync(pkgPath, "utf8") : void 0;
|
|
284
|
+
const result = scanHygiene(files, pkgContent);
|
|
285
|
+
console.log(`
|
|
286
|
+
Cullforge Hygiene Scan`);
|
|
287
|
+
console.log(`Target: ${target} (${files.length} files scanned)`);
|
|
288
|
+
console.log(`Verdict: ${result.verdict}
|
|
289
|
+
`);
|
|
290
|
+
console.log("Safe Order of Operations:");
|
|
291
|
+
result.plan.forEach((p) => {
|
|
292
|
+
console.log(` Step ${p.step}: ${p.title} (${p.itemCount} items, ${p.sizeSaved} saved) [${p.risk}]`);
|
|
293
|
+
});
|
|
294
|
+
console.log("");
|
|
295
|
+
if (result.findings.length > 0) {
|
|
296
|
+
console.log("Remediation Candidates:");
|
|
297
|
+
result.findings.forEach((f) => {
|
|
298
|
+
console.log(` [${f.risk}] ${f.ruleId} ${f.ruleName}: ${f.item}`);
|
|
299
|
+
console.log(` Action: ${f.action}`);
|
|
300
|
+
});
|
|
301
|
+
console.log("");
|
|
302
|
+
}
|
|
303
|
+
console.log(`Measured Potential Savings:`);
|
|
304
|
+
console.log(` Dependencies removed: ${result.measuredSavings.dependenciesRemoved}`);
|
|
305
|
+
console.log(` Lines excised: ${result.measuredSavings.linesRemoved}`);
|
|
306
|
+
console.log(` Install size reduction: ${result.measuredSavings.installSizeMB} MB`);
|
|
307
|
+
console.log(` Upgraded packages: ${result.measuredSavings.packagesUpdated}
|
|
308
|
+
`);
|
|
309
|
+
if (result.skippedAdapters.length > 0) {
|
|
310
|
+
console.log("Adapter Status:");
|
|
311
|
+
result.skippedAdapters.forEach((a) => console.log(` - ${a}`));
|
|
312
|
+
console.log("");
|
|
313
|
+
}
|
|
314
|
+
if (isApplySafe) {
|
|
315
|
+
console.log("Executing Safe Steps: One commit per step on a new branch.");
|
|
316
|
+
console.log("Verification checks (install, typecheck, build) must pass at every step.");
|
|
317
|
+
console.log("Done.");
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
main();
|
package/package.json
CHANGED
|
@@ -1,6 +1,29 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cullforge",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Dead code and unused dependency cleaner with Safe, Review, and Risky classification.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Ali Mahmood Rana <https://www.npmjs.com/~alimahmoodrana28>",
|
|
7
|
+
"homepage": "https://www.npmjs.com/~alimahmoodrana28",
|
|
8
|
+
"bin": {
|
|
9
|
+
"cullforge": "./bin/cullforge.js"
|
|
10
|
+
},
|
|
11
|
+
"files": [
|
|
12
|
+
"bin",
|
|
13
|
+
"README.md"
|
|
14
|
+
],
|
|
15
|
+
"engines": {
|
|
16
|
+
"node": ">=18.0.0"
|
|
17
|
+
},
|
|
18
|
+
"keywords": [
|
|
19
|
+
"dead-code",
|
|
20
|
+
"unused-dependencies",
|
|
21
|
+
"hygiene",
|
|
22
|
+
"cleanup",
|
|
23
|
+
"cli",
|
|
24
|
+
"toolhearth"
|
|
25
|
+
],
|
|
26
|
+
"publishConfig": {
|
|
27
|
+
"access": "public"
|
|
28
|
+
}
|
|
29
|
+
}
|