lockvet 0.0.0-stage → 1.0.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/CHANGELOG.md ADDED
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ All notable changes to `lockvet` will be documented in this file.
4
+
5
+ The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
6
+
7
+ ## [1.0.0] - 2026-11-22
8
+
9
+ ### Added
10
+
11
+ - Initial release of `lockvet` offline npm lockfile inspector and triaging tool.
12
+ - Support for npm lockfileVersion 2 and 3 with full node resolution algorithm.
13
+ - Deprecation rule with production vs development scope and direct dependency fix target derivation.
14
+ - Install script detection rule for preinstall, install, and postinstall hooks.
15
+ - Source validation rule for HTTPS registries, integrity hashes, and untrusted sources.
16
+ - Package version duplicate detection with dependency path reporting.
17
+ - SPDX license policy validation with `--allow-license` and `--deny-license` supporting boolean logic.
18
+ - Text, Markdown, and JSON output formats with stable schema version 1.
19
+ - CLI supporting `.lockvetrc.json` configuration, configurable exit codes, and no-color terminal output.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lalit Mittal
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,95 @@
1
- # Temporary Holding Version
1
+ # lockvet
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Fast, zero-dependency, offline npm lockfile inspector and supply-chain hygiene triager.
4
+
5
+ ## Features
6
+
7
+ - Zero runtime dependencies (Node >= 20 native ESM).
8
+ - 100% offline and deterministic.
9
+ - Supports npm lockfileVersion 2 and 3.
10
+ - Full dependency tree resolution and shortest path reporting to direct targets.
11
+ - 5 audit rules: deprecated, install-scripts, source, duplicates, licenses.
12
+ - Output formats: text, markdown, json.
13
+ - Custom rules configuration via .lockvetrc.json.
14
+
15
+ ## Installation
16
+
17
+ ```bash
18
+ npm install -g lockvet
19
+ ```
20
+
21
+ Or run directly:
22
+
23
+ ```bash
24
+ npx lockvet
25
+ ```
26
+
27
+ ## Usage
28
+
29
+ ```bash
30
+ # Check current directory lockfile
31
+ lockvet
32
+
33
+ # Check custom lockfile
34
+ lockvet path/to/package-lock.json
35
+
36
+ # Fail on warnings or errors
37
+ lockvet --fail-on warning
38
+
39
+ # Output as Markdown
40
+ lockvet --format markdown
41
+
42
+ # License enforcement
43
+ lockvet --deny-license "GPL-3.0, AGPL-3.0"
44
+ ```
45
+
46
+ ## CLI Flags
47
+
48
+ - `-f, --format <text|markdown|json>`: Output format (default: text)
49
+ - `--fail-on <level|rule>`: Exit with code 1 if matching issues are found
50
+ - `--prod-only`: Evaluate production dependencies only
51
+ - `--ignore <packages>`: Comma-separated package names or name@version to ignore
52
+ - `--deny-license <list>`: Comma-separated list of denied SPDX identifiers
53
+ - `--allow-license <list>`: Comma-separated list of allowed SPDX identifiers
54
+ - `--max-paths <number>`: Max dependency paths per issue (default: 3)
55
+ - `--no-color`: Disable color output
56
+ - `-v, --version`: Display version
57
+ - `-h, --help`: Display help
58
+
59
+ ## Configuration (.lockvetrc.json)
60
+
61
+ ```json
62
+ {
63
+ "prodOnly": false,
64
+ "format": "text",
65
+ "failOn": "error",
66
+ "maxPaths": 3,
67
+ "ignore": [],
68
+ "rules": {
69
+ "deprecated": { "enabled": true },
70
+ "install-scripts": { "enabled": true },
71
+ "source": { "enabled": true },
72
+ "duplicates": { "enabled": true },
73
+ "licenses": {
74
+ "enabled": true,
75
+ "allow": ["MIT", "Apache-2.0", "ISC", "BSD-2-Clause", "BSD-3-Clause"],
76
+ "deny": []
77
+ }
78
+ }
79
+ }
80
+ ```
81
+
82
+ ## Programmatic API
83
+
84
+ ```javascript
85
+ import { analyze, parseLockfile, formatReport } from 'lockvet';
86
+ import { readFileSync } from 'node:fs';
87
+
88
+ const lockfile = parseLockfile(readFileSync('./package-lock.json', 'utf8'));
89
+ const report = analyze(lockfile, { prodOnly: true });
90
+ console.log(formatReport(report, 'text'));
91
+ ```
92
+
93
+ ## License
94
+
95
+ MIT (c) 2026 Lalit Mittal
package/bin/lockvet.js ADDED
@@ -0,0 +1,341 @@
1
+ #!/usr/bin/env node
2
+
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import process from 'node:process';
6
+ import { analyze, formatReport, LockvetError } from '../src/index.js';
7
+
8
+ const HELP_TEXT = `
9
+ lockvet [path] [options]
10
+
11
+ Offline npm lockfile hygiene and supply chain triaging CLI.
12
+
13
+ Arguments:
14
+ path Path to package-lock.json or npm-shrinkwrap.json
15
+ (default: ./package-lock.json, then ./npm-shrinkwrap.json)
16
+
17
+ Options:
18
+ --format <fmt> Output format: text, json, markdown (default: text)
19
+ --fail-on <rules> Comma-separated list of rules that exit with code 1 if violated:
20
+ deprecated, install-scripts, source, duplicates, license, none (default: none)
21
+ --ignore <pkg> Ignore findings for package name or name@version (repeatable)
22
+ --max-paths <N> Maximum shortest paths to display per finding (default: 3)
23
+ --prod-only Only inspect production dependencies
24
+ --deny-license <ID> Deny specified SPDX license identifier (repeatable)
25
+ --allow-license <ID> Allow only specified SPDX license identifiers (repeatable)
26
+ --no-color Disable colored terminal output
27
+ -v, --version Show version number
28
+ -h, --help Show help message
29
+
30
+ Exit Codes:
31
+ 0 Clean analysis / no fail-on rules triggered
32
+ 1 One or more --fail-on rules triggered findings
33
+ 2 Command usage, file access, or parsing error
34
+ `;
35
+
36
+ function parseArgs(argv) {
37
+ const options = {
38
+ targetPath: null,
39
+ format: 'text',
40
+ failOn: null,
41
+ ignore: [],
42
+ maxPaths: 3,
43
+ prodOnly: false,
44
+ denyLicense: [],
45
+ allowLicense: [],
46
+ noColor: false,
47
+ help: false,
48
+ version: false
49
+ };
50
+
51
+ for (let i = 0; i < argv.length; i++) {
52
+ const arg = argv[i];
53
+ if (arg === '-h' || arg === '--help') {
54
+ options.help = true;
55
+ } else if (arg === '-v' || arg === '--version') {
56
+ options.version = true;
57
+ } else if (arg === '--no-color') {
58
+ options.noColor = true;
59
+ } else if (arg === '--prod-only') {
60
+ options.prodOnly = true;
61
+ } else if (arg === '--format' || arg.startsWith('--format=')) {
62
+ const val = arg.startsWith('--format=') ? arg.slice('--format='.length) : argv[++i];
63
+ if (!val || !['text', 'json', 'markdown'].includes(val)) {
64
+ throw new LockvetError(
65
+ `Invalid --format: "${val}". Must be one of text, json, markdown.`,
66
+ 'ERR_INVALID_USAGE'
67
+ );
68
+ }
69
+ options.format = val;
70
+ } else if (arg === '--fail-on' || arg.startsWith('--fail-on=')) {
71
+ const val = arg.startsWith('--fail-on=') ? arg.slice('--fail-on='.length) : argv[++i];
72
+ options.failOn = val;
73
+ } else if (arg === '--ignore' || arg.startsWith('--ignore=')) {
74
+ const val = arg.startsWith('--ignore=') ? arg.slice('--ignore='.length) : argv[++i];
75
+ if (val) options.ignore.push(val);
76
+ } else if (arg === '--deny-license' || arg.startsWith('--deny-license=')) {
77
+ const val = arg.startsWith('--deny-license=')
78
+ ? arg.slice('--deny-license='.length)
79
+ : argv[++i];
80
+ if (val) options.denyLicense.push(val);
81
+ } else if (arg === '--allow-license' || arg.startsWith('--allow-license=')) {
82
+ const val = arg.startsWith('--allow-license=')
83
+ ? arg.slice('--allow-license='.length)
84
+ : argv[++i];
85
+ if (val) options.allowLicense.push(val);
86
+ } else if (arg === '--max-paths' || arg.startsWith('--max-paths=')) {
87
+ const val = arg.startsWith('--max-paths=') ? arg.slice('--max-paths='.length) : argv[++i];
88
+ const parsed = parseInt(val, 10);
89
+ if (Number.isNaN(parsed) || parsed < 0) {
90
+ throw new LockvetError(
91
+ `Invalid --max-paths: "${val}". Must be a non-negative integer.`,
92
+ 'ERR_INVALID_USAGE'
93
+ );
94
+ }
95
+ options.maxPaths = parsed;
96
+ } else if (arg.startsWith('-')) {
97
+ throw new LockvetError(
98
+ `Unknown option: "${arg}". Use --help for usage.`,
99
+ 'ERR_INVALID_USAGE'
100
+ );
101
+ } else if (!options.targetPath) {
102
+ options.targetPath = arg;
103
+ } else {
104
+ throw new LockvetError(`Unexpected positional argument: "${arg}"`, 'ERR_INVALID_USAGE');
105
+ }
106
+ }
107
+
108
+ return options;
109
+ }
110
+
111
+ function loadConfig(dir) {
112
+ const configPath = path.join(dir, '.lockvetrc.json');
113
+ if (!fs.existsSync(configPath)) {
114
+ return null;
115
+ }
116
+ let content;
117
+ try {
118
+ content = fs.readFileSync(configPath, 'utf8');
119
+ } catch (err) {
120
+ throw new LockvetError(
121
+ `Failed to read config file at ${configPath}: ${err.message}`,
122
+ 'ERR_CONFIG_READ'
123
+ );
124
+ }
125
+
126
+ let parsed;
127
+ try {
128
+ parsed = JSON.parse(content);
129
+ } catch (err) {
130
+ throw new LockvetError(
131
+ `Invalid JSON in configuration file ${configPath}: ${err.message}`,
132
+ 'ERR_CONFIG_INVALID'
133
+ );
134
+ }
135
+
136
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
137
+ throw new LockvetError(
138
+ `Configuration file ${configPath} must be a JSON object`,
139
+ 'ERR_CONFIG_INVALID'
140
+ );
141
+ }
142
+
143
+ if (parsed.ignore !== undefined && !Array.isArray(parsed.ignore)) {
144
+ throw new LockvetError(
145
+ `"ignore" field in ${configPath} must be an array`,
146
+ 'ERR_CONFIG_INVALID'
147
+ );
148
+ }
149
+
150
+ if (
151
+ parsed.failOn !== undefined &&
152
+ !Array.isArray(parsed.failOn) &&
153
+ typeof parsed.failOn !== 'string'
154
+ ) {
155
+ throw new LockvetError(
156
+ `"failOn" field in ${configPath} must be an array or string`,
157
+ 'ERR_CONFIG_INVALID'
158
+ );
159
+ }
160
+
161
+ return parsed;
162
+ }
163
+
164
+ function resolveLockfilePath(targetPath) {
165
+ if (targetPath) {
166
+ const resolved = path.resolve(process.cwd(), targetPath);
167
+ if (!fs.existsSync(resolved)) {
168
+ throw new LockvetError(`Lockfile not found at ${resolved}`, 'ERR_FILE_NOT_FOUND');
169
+ }
170
+ return resolved;
171
+ }
172
+
173
+ const defaultLock = path.resolve(process.cwd(), 'package-lock.json');
174
+ if (fs.existsSync(defaultLock)) {
175
+ return defaultLock;
176
+ }
177
+
178
+ const shrinkwrap = path.resolve(process.cwd(), 'npm-shrinkwrap.json');
179
+ if (fs.existsSync(shrinkwrap)) {
180
+ return shrinkwrap;
181
+ }
182
+
183
+ throw new LockvetError(
184
+ 'No lockfile found. Looked for package-lock.json and npm-shrinkwrap.json in current directory.',
185
+ 'ERR_FILE_NOT_FOUND'
186
+ );
187
+ }
188
+
189
+ function getPackageVersion() {
190
+ try {
191
+ const pkgPath = new URL('../package.json', import.meta.url);
192
+ const content = fs.readFileSync(pkgPath, 'utf8');
193
+ const parsed = JSON.parse(content);
194
+ return parsed.version || '1.0.0';
195
+ } catch {
196
+ return '1.0.0';
197
+ }
198
+ }
199
+
200
+ async function main() {
201
+ let cliOpts;
202
+ try {
203
+ cliOpts = parseArgs(process.argv.slice(2));
204
+ } catch (err) {
205
+ process.stderr.write(`error: ${err.message}\n`);
206
+ process.exit(2);
207
+ }
208
+
209
+ if (cliOpts.help) {
210
+ process.stdout.write(HELP_TEXT.trim() + '\n');
211
+ process.exit(0);
212
+ }
213
+
214
+ if (cliOpts.version) {
215
+ process.stdout.write(`v${getPackageVersion()}\n`);
216
+ process.exit(0);
217
+ }
218
+
219
+ let lockfilePath;
220
+ try {
221
+ lockfilePath = resolveLockfilePath(cliOpts.targetPath);
222
+ } catch (err) {
223
+ process.stderr.write(`error: ${err.message}\n`);
224
+ process.exit(2);
225
+ }
226
+
227
+ // Load config from lockfile directory
228
+ let config = null;
229
+ try {
230
+ config = loadConfig(path.dirname(lockfilePath));
231
+ } catch (err) {
232
+ process.stderr.write(`error: ${err.message}\n`);
233
+ process.exit(2);
234
+ }
235
+
236
+ // Merge options: CLI flags override config
237
+ const ignore = [...(config?.ignore || []), ...cliOpts.ignore];
238
+ const denyLicenses = [
239
+ ...(config?.denyLicenses || config?.denyLicense || []),
240
+ ...cliOpts.denyLicense
241
+ ];
242
+ const allowLicenses = [
243
+ ...(config?.allowLicenses || config?.allowLicense || []),
244
+ ...cliOpts.allowLicense
245
+ ];
246
+ const prodOnly = cliOpts.prodOnly || Boolean(config?.prodOnly);
247
+ const maxPaths = cliOpts.maxPaths ?? config?.maxPaths ?? 3;
248
+
249
+ // Determine fail-on rules
250
+ let rawFailOn = cliOpts.failOn;
251
+ if (rawFailOn === null && config && config.failOn) {
252
+ rawFailOn = Array.isArray(config.failOn) ? config.failOn.join(',') : config.failOn;
253
+ }
254
+ if (!rawFailOn) {
255
+ rawFailOn = 'none';
256
+ }
257
+
258
+ const validRules = new Set([
259
+ 'deprecated',
260
+ 'install-scripts',
261
+ 'source',
262
+ 'duplicates',
263
+ 'license',
264
+ 'licenses',
265
+ 'none'
266
+ ]);
267
+ const failOnRules = new Set(
268
+ rawFailOn
269
+ .split(',')
270
+ .map((s) => s.trim().toLowerCase())
271
+ .filter(Boolean)
272
+ );
273
+
274
+ for (const r of failOnRules) {
275
+ if (!validRules.has(r)) {
276
+ process.stderr.write(
277
+ `error: unknown rule "${r}" specified in --fail-on. Valid rules are: deprecated, install-scripts, source, duplicates, license, none\n`
278
+ );
279
+ process.exit(2);
280
+ }
281
+ }
282
+
283
+ let lockfileContent;
284
+ try {
285
+ lockfileContent = fs.readFileSync(lockfilePath, 'utf8');
286
+ } catch (err) {
287
+ process.stderr.write(`error: Failed to read lockfile: ${err.message}\n`);
288
+ process.exit(2);
289
+ }
290
+
291
+ let report;
292
+ try {
293
+ report = analyze(lockfileContent, {
294
+ maxPaths,
295
+ prodOnly,
296
+ denyLicenses,
297
+ allowLicenses,
298
+ ignore
299
+ });
300
+ } catch (err) {
301
+ if (process.env.DEBUG === 'lockvet' && err.stack) {
302
+ process.stderr.write(err.stack + '\n');
303
+ } else {
304
+ process.stderr.write(`error: ${err.message}\n`);
305
+ }
306
+ process.exit(2);
307
+ }
308
+
309
+ const useColor =
310
+ !cliOpts.noColor && process.env.NO_COLOR === undefined && Boolean(process.stdout.isTTY);
311
+ const formatted = formatReport(report, {
312
+ format: cliOpts.format,
313
+ color: useColor
314
+ });
315
+
316
+ process.stdout.write(formatted + '\n');
317
+
318
+ // Check fail-on conditions
319
+ if (!failOnRules.has('none')) {
320
+ const failedFindings = report.findings.filter((f) => {
321
+ if (failOnRules.has(f.rule)) return true;
322
+ if (f.rule === 'license' && failOnRules.has('licenses')) return true;
323
+ return false;
324
+ });
325
+
326
+ if (failedFindings.length > 0) {
327
+ process.exit(1);
328
+ }
329
+ }
330
+
331
+ process.exit(0);
332
+ }
333
+
334
+ main().catch((err) => {
335
+ if (process.env.DEBUG === 'lockvet' && err.stack) {
336
+ process.stderr.write(err.stack + '\n');
337
+ } else {
338
+ process.stderr.write(`error: ${err.message}\n`);
339
+ }
340
+ process.exit(2);
341
+ });
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "lockvet",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "Fast offline npm lockfile inspector and hygiene triaging CLI and library",
5
+ "type": "module",
6
+ "main": "./src/index.js",
7
+ "bin": {
8
+ "lockvet": "bin/lockvet.js"
9
+ },
10
+ "exports": {
11
+ ".": "./src/index.js",
12
+ "./package.json": "./package.json"
13
+ },
14
+ "engines": {
15
+ "node": ">=20"
16
+ },
17
+ "files": [
18
+ "bin",
19
+ "src",
20
+ "README.md",
21
+ "LICENSE",
22
+ "CHANGELOG.md"
23
+ ],
24
+ "keywords": [
25
+ "npm",
26
+ "lockfile",
27
+ "package-lock",
28
+ "deprecated",
29
+ "audit",
30
+ "dependencies",
31
+ "cli",
32
+ "supply-chain"
33
+ ],
34
+ "author": "Lalit Mittal <lalit10565249@gmail.com>",
35
+ "license": "MIT",
36
+ "sideEffects": false,
37
+ "scripts": {
38
+ "test": "node --test test/**/*.test.js",
39
+ "lint": "eslint .",
40
+ "format:check": "prettier --check .",
41
+ "format": "prettier --write .",
42
+ "pack:check": "npm pack --dry-run",
43
+ "prepublishOnly": "npm run lint && npm run format:check && npm test"
44
+ },
45
+ "devDependencies": {
46
+ "@eslint/js": "^9.20.0",
47
+ "eslint": "^9.20.0",
48
+ "globals": "^15.14.0",
49
+ "prettier": "^3.5.1"
50
+ }
51
+ }
package/src/errors.js ADDED
@@ -0,0 +1,11 @@
1
+ export class LockvetError extends Error {
2
+ /**
3
+ * @param {string} message
4
+ * @param {string} code
5
+ */
6
+ constructor(message, code) {
7
+ super(message);
8
+ this.name = 'LockvetError';
9
+ this.code = code;
10
+ }
11
+ }