dsh-vet 0.1.0 → 0.2.1

package/README.md

@@ -1,12 +1,15 @@
 # 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.
 
-> **Status: v0.1 complete.** Contract draft, reference scanner + CLI, rule
-> set with public rationales, and an 11-package calibration sweep are in;
-> the `0.1.0` npm release is the remaining step.
+> **Status: v0.1 shipped.** [`dsh-vet@0.1.0` is live on npm](https://www.npmjs.com/package/dsh-vet) —
+> reference scanner, 15 calibrated rules, public rule rationales, and an
+> 11-package ecosystem sweep record. v0.2 (author-side CI + badges) is next
+> on the [roadmap](ROADMAP.md).
 
 ## Install
 
@@ -50,6 +53,25 @@ from the exact tarball that ships (`npm pack` → scan), seams declared in
 package.json. It is not an A-by-cheating report — every signal the scanner
 finds in itself is in there.
 
+## CI & badge for plugin authors
+
+Audit your plugin on every push and PR, and publish your grade from the
+report committed to your repository — shields.io reads the badge straight
+from your repo, so its value is auditable through git history and no badge
+service is involved:
+
+```yaml
+- uses: rogerdigital/dsh-vet/action@v0.2.0
+  with:
+    specifier: '.'
+    commit-report: true
+```
+
+Every run uploads the full report as an artifact; PRs get a single
+edited-in-place findings comment. Badge snippet and all inputs:
+[`action/README.md`](action/README.md). The `dsh-vet badge <report.json>`
+command renders the shields endpoint JSON if you wire CI yourself.
+
 ## Why
 
 DSH's everything-is-a-plugin architecture is its greatest strength and its

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.1.0";
+declare const SCANNER_VERSION = "0.2.1";
 interface ScanOptions extends ResolveOptions {
   /** Injectable clock for deterministic tests/reports. */
   now?: () => string;
@@ -281,6 +281,16 @@ interface ScanOptions extends ResolveOptions {
 declare function scanDirectory(dir: string, options?: ScanOptions): Promise<VetReport>;
 declare function scan(specifier: string, options?: ScanOptions): Promise<VetReport>;
 //#endregion
+//#region src/badge.d.ts
+interface ShieldsEndpointBadge {
+  schemaVersion: 1;
+  label: string;
+  message: string;
+  color: string;
+  isError?: boolean;
+}
+declare function renderBadge(report: VetReport): ShieldsEndpointBadge;
+//#endregion
 //#region src/cli.d.ts
 /**
  * CLI (ROADMAP T4). Exit semantics per the dsh-vet/v1 spec: `0` for any
@@ -294,4 +304,4 @@ interface CliIo {
 /** Parse and run; returns the process exit code. */
 declare function runCli(argv: string[], io: CliIo): Promise<number>;
 //#endregion
-export { type Analysis, type Capability, type CapabilityUse, type CharcodeCall, type CliIo, type CreateReportInput, type DynamicImportUse, type EncodedLiteral, type EvalUse, type FindingInit, type ImportRef, type NetUse, type PkgJson, RULES, RULE_ID_PATTERN, type ResolveOptions, type ResolvedTarget, type Rule, type RuleContext, SCANNER_VERSION, SCHEMA_ID, type ScanOptions, type SourceFile, type SpecifierKind, type VetConfidence, VetError, type VetEvidence, type VetFinding, type VetGrade, type VetReport, type VetScanner, type VetSeverity, type VetSummary, type VetSummaryCounts, type VetTarget, type VetTargetKind, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory };
+export { type Analysis, type Capability, type CapabilityUse, type CharcodeCall, type CliIo, type CreateReportInput, type DynamicImportUse, type EncodedLiteral, type EvalUse, type FindingInit, type ImportRef, type NetUse, type PkgJson, RULES, RULE_ID_PATTERN, type ResolveOptions, type ResolvedTarget, type Rule, type RuleContext, SCANNER_VERSION, SCHEMA_ID, type ScanOptions, type ShieldsEndpointBadge, type SourceFile, type SpecifierKind, type VetConfidence, VetError, type VetEvidence, type VetFinding, type VetGrade, type VetReport, type VetScanner, type VetSeverity, type VetSummary, type VetSummaryCounts, type VetTarget, type VetTargetKind, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, renderBadge, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory };

package/lib/index.mjs

@@ -1601,9 +1601,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.1.0";
+const SCANNER_VERSION = "0.2.1";
+/**
+* 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 +1636,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,13 +1652,33 @@ 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();
 	}
 }
 //#endregion
+//#region src/badge.ts
+const GRADE_COLOR = {
+	A: "brightgreen",
+	B: "green",
+	C: "yellow",
+	D: "orange",
+	F: "red",
+	X: "lightgrey"
+};
+function renderBadge(report) {
+	const grade = report.summary.grade;
+	return {
+		schemaVersion: 1,
+		label: "dsh-vet",
+		message: grade === "X" ? "scan failed" : `grade ${grade}`,
+		color: GRADE_COLOR[grade],
+		...grade === "X" ? { isError: true } : {}
+	};
+}
+//#endregion
 //#region src/cli.ts
 /**
 * CLI (ROADMAP T4). Exit semantics per the dsh-vet/v1 spec: `0` for any
@@ -1642,6 +1686,7 @@ async function scan(specifier, options = {}) {
 * `--strict`/`--fail-on` turn threshold breaches into exit code 1.
 */
 const USAGE = `usage: dsh-vet <specifier> [options]
+       dsh-vet badge <report.json>
 
   specifier            npm package (name[@version]), git URL, or local path
 
@@ -1650,7 +1695,11 @@ const USAGE = `usage: dsh-vet <specifier> [options]
   --fail-on <sev>      override the --strict threshold (critical|high|medium|low)
   --rules <ids>        comma-separated rule ids to run
   --version            print version
-  --help               this text`;
+  --help               this text
+
+  badge                render a shields.io endpoint badge (JSON) from a
+                       dsh-vet/v1 report file; used by CI to publish a grade
+                       badge whose value is the committed report`;
 const SEVERITY_ORDER = [
 	"critical",
 	"high",
@@ -1685,6 +1734,7 @@ function humanSummary(report) {
 }
 /** Parse and run; returns the process exit code. */
 async function runCli(argv, io) {
+	if (argv[0] === "badge") return runBadge(argv.slice(1), io);
 	let args;
 	try {
 		args = parseArgs({
@@ -1737,5 +1787,25 @@ async function runCli(argv, io) {
 		return 2;
 	}
 }
+function runBadge(argv, io) {
+	const path = argv[0];
+	if (!path || argv.length > 1 || path === "--help") {
+		io.stderr(`usage: dsh-vet badge <report.json>\n\nRender a shields.io endpoint badge from a dsh-vet/v1 report.`);
+		return 2;
+	}
+	let report;
+	try {
+		report = JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		io.stderr(`dsh-vet badge: cannot read report: ${err.message}`);
+		return 2;
+	}
+	if (report.schema !== "dsh-vet/v1") {
+		io.stderr(`dsh-vet badge: not a ${SCHEMA_ID} report (schema: ${String(report.schema)})`);
+		return 2;
+	}
+	io.stdout(JSON.stringify(renderBadge(report)));
+	return 0;
+}
 //#endregion
-export { RULES, RULE_ID_PATTERN, SCANNER_VERSION, SCHEMA_ID, VetError, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory };
+export { RULES, RULE_ID_PATTERN, SCANNER_VERSION, SCHEMA_ID, VetError, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, renderBadge, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vet",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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"]