dsh-vet 0.2.0 → 0.2.2

package/README.md

@@ -1,5 +1,7 @@
 # dsh-vet
 
+[![dsh-vet](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/rogerdigital/dsh-vet/main/.dsh-vet/badge.json)](https://github.com/rogerdigital/dsh-vet/blob/main/.dsh-vet/report.json)
+
 Security vetting for DeepSeek Harness (DSH) plugins: permission & supply-chain
 audits before install, graded via the open [`dsh-vet/v1`](docs/dsh-vet-v1.md)
 report standard.

package/docs/rules/perm.undeclared-fs-write.md

@@ -17,8 +17,19 @@ in-scope paths are not.
   for destructive operations outside any declared scope.
 - Non-destructive writes with a literal out-of-scope absolute path:
   **high / high.**
-- Writes whose target is a runtime value: **medium / low** (ROADMAP D2 —
-  runtime-dependent findings never lower a grade on their own).
+- Writes whose target is a runtime value: **low / low** — reported as
+  "scope not statically verifiable", never as an out-of-scope claim the
+  scanner cannot make, and never grade-affecting (ROADMAP D2). Normal
+  plugins write dynamic paths constantly; this tier is a review prompt,
+  not an accusation.
+
+The runtime-value tier deliberately does **not** attempt the path-derivation
+dataflow some disputes have asked for: constraint chains are usually
+interprocedural (derive-and-validate in one function, delete in another),
+beyond best-effort static analysis. The honest position is "unresolvable —
+review the derivation", which is what the finding now says. Clarified via
+[dispute #10](https://github.com/rogerdigital/dsh-vet/issues/10), whose
+guarded managed-directory removal is the canonical well-reviewed case.
 
 ## False positives
 

package/docs/rules/scan.empty-audit.md

@@ -0,0 +1,27 @@
+# scan.empty-audit
+
+No analyzable JavaScript found in the target.
+
+## What it looks for
+
+The scanner found zero `.js`/`.mjs`/`.cjs` files (or Node-shebang bin
+scripts) in the audited tree. This rule fires on behalf of the report's
+readers: a scan that audited nothing must not read as a clean pass.
+
+## Severity / confidence policy
+
+**medium / high.** Nothing was analyzed — that is a fact, and a grade of A
+here would be vacuous. Found live during v0.2 activation: a
+TypeScript-source repository scanned as a local path ships no `.js` in its
+working tree, so `.` audits nothing while the badge reads green.
+
+## False positives
+
+Targets that genuinely contain no JavaScript at all (a data package, a
+documentation bundle). If that is you, the finding is still correct — you
+are advertising an audit that cannot say anything.
+
+## Remediation
+
+Audit what actually ships: pass the npm package specifier (or a directory
+containing the built output) instead of the source tree.

package/lib/index.d.mts

@@ -271,7 +271,7 @@ declare function runRules(analysis: Analysis, only?: string[]): VetFinding[];
 //#endregion
 //#region src/scanner.d.ts
 /** Kept in lockstep with package.json; a test asserts they match. */
-declare const SCANNER_VERSION = "0.2.0";
+declare const SCANNER_VERSION = "0.2.2";
 interface ScanOptions extends ResolveOptions {
   /** Injectable clock for deterministic tests/reports. */
   now?: () => string;

package/lib/index.mjs

@@ -1463,14 +1463,16 @@ const undeclaredFsWrite = {
 			}));
 		}
 		if (dynamic.length > 0) findings.push(finding(this, {
-			severity: "medium",
+			title: "Write/delete target is a runtime value — scope not statically verifiable",
+			severity: "low",
 			confidence: "low",
 			evidence: capEvidence(dynamic.map((use) => ({
 				file: use.file,
 				line: use.line,
-				snippet: use.snippet
+				snippet: use.snippet,
+				note: "review how the target is derived; the scanner cannot resolve it statically"
 			})), 5),
-			remediation: "Use fixed, reviewable paths; runtime-computed write targets cannot be audited statically.",
+			remediation: "Keep the derivation next to the call, test the invariant (fixed child of a validated root), and document the managed scope so reviewers can verify it.",
 			references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.undeclared-fs-write.md"]
 		}));
 		return findings;
@@ -1601,9 +1603,31 @@ function runRules(analysis, only) {
 * over the same artifact with the same version are identical.
 */
 /** Kept in lockstep with package.json; a test asserts they match. */
-const SCANNER_VERSION = "0.2.0";
+const SCANNER_VERSION = "0.2.2";
+/**
+* A scan that audited zero JavaScript files must not read as a clean pass —
+* a TypeScript source tree scanned as a local path has no `.js` to analyze,
+* and silence there would be an A-by-vacuity. (Found live during v0.2
+* activation; docs/rules/scan.empty-audit.md.)
+*/
+function emptyAuditFinding(targetSpecifier) {
+	return {
+		id: "scan.empty-audit",
+		title: "No analyzable JavaScript found in the target",
+		severity: "medium",
+		confidence: "high",
+		evidence: [{
+			file: ".",
+			note: `zero .js/.mjs/.cjs files (or Node-shebang bin scripts) found under ${targetSpecifier}`
+		}],
+		remediation: "Audit what actually ships: pass the npm package specifier (or a directory containing the built output) instead of the source tree.",
+		references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/scan.empty-audit.md"]
+	};
+}
 async function scanDirectory(dir, options = {}) {
 	const analysis = analyze(dir);
+	const findings = options.rules ? runRules(analysis, options.rules) : runRules(analysis);
+	if (analysis.files.length === 0) findings.push(emptyAuditFinding(dir));
 	return createReport({
 		target: {
 			kind: "local-path",
@@ -1614,13 +1638,15 @@ async function scanDirectory(dir, options = {}) {
 			version: SCANNER_VERSION,
 			ranAt: options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString()
 		},
-		findings: options.rules ? runRules(analysis, options.rules) : runRules(analysis)
+		findings
 	});
 }
 async function scan(specifier, options = {}) {
 	const resolved = await resolveTarget(specifier, options);
 	try {
 		const analysis = analyze(resolved.rootDir);
+		const findings = options.rules ? runRules(analysis, options.rules) : runRules(analysis);
+		if (analysis.files.length === 0) findings.push(emptyAuditFinding(specifier));
 		return createReport({
 			target: resolved.target,
 			scanner: {
@@ -1628,7 +1654,7 @@ async function scan(specifier, options = {}) {
 				version: SCANNER_VERSION,
 				ranAt: options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString()
 			},
-			findings: options.rules ? runRules(analysis, options.rules) : runRules(analysis)
+			findings
 		});
 	} finally {
 		resolved.cleanup();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vet",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Security vetting for DeepSeek Harness (DSH) plugins: permission & supply-chain audits before install, graded via the open dsh-vet/v1 report standard.",
   "dsh": {
     "seams": ["fs", "shell", "web"]