dsh-plugin-inspector 0.1.0

package/lib/checks/tier-c.js

@@ -0,0 +1,288 @@
+/**
+ * Tier C — how much of the package the analyzer could actually read.
+ *
+ * These checks do not describe the plugin's behavior. They describe the limits
+ * of the analysis, and that is why a Tier C hit is a finding rather than a
+ * silent internal flag: "we cannot read this" is a legitimate result and the
+ * user is entitled to see it.
+ *
+ * A Tier C hit also has a mechanical consequence. Tier B recognises a whitelist
+ * of syntactic shapes, so when code is minified, when identifiers are computed,
+ * or when the shipped artifact has no readable source, a Tier B *positive* is
+ * still true but a Tier B *negative* means nothing. `inspect.ts` reads the
+ * output of this module to lower Tier B confidence and to forbid the report
+ * from claiming nothing was found.
+ * @module dsh-plugin-inspector/checks/tier-c
+ */
+import ts from 'typescript';
+import { lineColumn, snippet } from "../files.js";
+/** A line longer than this is not written by hand. */
+const MINIFIED_LINE_LENGTH = 500;
+/** Below this many bytes, a low line count says nothing. */
+const MINIFICATION_SIZE_FLOOR = 4096;
+/** Object names whose computed member access is a dispatch, not an array index. */
+const DISPATCH_RECEIVERS = new Set(['ctx', 'context', 'globalThis', 'global']);
+/** Members whose first argument names a seam, an event, or a tool. */
+const NAMED_TARGET_CALLEES = new Set([
+    'on', 'once', 'provide', 'set', 'get', 'emit', 'waterfall', 'bail', 'parallel', 'serial',
+]);
+/**
+ * Build one Tier C finding. Confidence is `moderate`: these are heuristics
+ * about form, and a hand-written file can legitimately have one long line.
+ * @param finding - everything but the fixed fields.
+ * @returns the complete finding.
+ */
+function tierC(finding) {
+    return { ...finding, tier: 'C', confidence: 'moderate' };
+}
+/** C1 — source that is not written to be read. */
+function checkMinification(input) {
+    const findings = [];
+    for (const path of input.sourceFiles) {
+        const text = input.source.files.get(path);
+        if (text === undefined)
+            continue;
+        const lines = text.split('\n');
+        const longest = lines.reduce((max, line) => Math.max(max, line.length), 0);
+        const dense = text.length >= MINIFICATION_SIZE_FLOOR && lines.length < 5;
+        // One long line does not make a file unreadable — an embedded prompt or a
+        // base64 asset in otherwise ordinary code is one long line, and the
+        // harness's own web bundle has one. What makes a file unreadable is when
+        // the long lines are most of it.
+        const longBytes = lines.filter(line => line.length >= MINIFIED_LINE_LENGTH)
+            .reduce((sum, line) => sum + line.length, 0);
+        const dominated = longBytes * 2 >= text.length;
+        if (!dense && !dominated)
+            continue;
+        findings.push(tierC({
+            checkId: 'C1',
+            name: 'minified-source',
+            severity: 'medium',
+            title: `\`${path}\` is minified or generated`,
+            detail: `Longest line is ${longest} characters across ${lines.length} line(s), and lines that long are `
+                + `${Math.round(longBytes * 100 / Math.max(text.length, 1))}% of the file. Capability detection reads `
+                + 'syntax, and it reads minified syntax no better than a person does. Every Tier B negative for this '
+                + 'package is unreliable while this file is in it.',
+            evidence: { file: path, path: '1:1', snippet: snippet(lines[0] ?? '') },
+            bypass: 'none — this finding is about the analysis, not about the plugin',
+        }));
+    }
+    return findings;
+}
+/** C2 — names the analyzer cannot resolve without running the code. */
+function checkDynamicDispatch(input) {
+    const findings = [];
+    for (const path of input.sourceFiles) {
+        const text = input.source.files.get(path);
+        if (text === undefined)
+            continue;
+        const source = ts.createSourceFile(path, text, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS);
+        const report = (node, what) => {
+            findings.push(tierC({
+                checkId: 'C2',
+                name: 'dynamic-dispatch',
+                severity: 'high',
+                title: `\`${path}\` ${what}`,
+                detail: 'Every Tier B check matches a literal name. A name assembled at runtime defeats all of them, so no '
+                    + 'Tier B negative for this package carries any information. A Tier B positive still does — the tool saw '
+                    + 'what it saw.',
+                evidence: {
+                    file: path,
+                    path: lineColumn(text, node.getStart(source)),
+                    snippet: snippet(text.slice(node.getStart(source), node.end)),
+                },
+                bypass: 'none — this finding is about the analysis, not about the plugin',
+            }));
+        };
+        const isComputed = (node) => node !== undefined && !ts.isStringLiteral(node) && !ts.isNoSubstitutionTemplateLiteral(node);
+        const visit = (node) => {
+            if (ts.isElementAccessExpression(node) && ts.isIdentifier(node.expression)
+                && DISPATCH_RECEIVERS.has(node.expression.text) && isComputed(node.argumentExpression)) {
+                report(node, `resolves a member of \`${node.expression.text}\` from a computed name`);
+            }
+            if (ts.isCallExpression(node)) {
+                const callee = node.expression;
+                const isRequire = ts.isIdentifier(callee) && callee.text === 'require';
+                const isImport = callee.kind === ts.SyntaxKind.ImportKeyword;
+                if ((isRequire || isImport) && isComputed(node.arguments[0])) {
+                    report(node, 'loads a module from a computed specifier');
+                }
+                if (ts.isIdentifier(callee) && callee.text === 'atob') {
+                    report(node, 'decodes a base64 string at runtime');
+                }
+                if (ts.isPropertyAccessExpression(callee) && callee.name.text === 'from'
+                    && ts.isIdentifier(callee.expression) && callee.expression.text === 'Buffer'
+                    && (literalOf(node.arguments[1]) === 'base64' || literalOf(node.arguments[1]) === 'base64url')) {
+                    report(node, 'decodes a base64 string at runtime');
+                }
+                if (ts.isPropertyAccessExpression(callee) && NAMED_TARGET_CALLEES.has(callee.name.text)
+                    && isDispatchReceiver(callee.expression) && isAssembledName(node.arguments[0])) {
+                    report(node, `passes an assembled name to \`${receiverName(callee.expression)}.${callee.name.text}()\``);
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        ts.forEachChild(source, visit);
+    }
+    return findings;
+}
+/**
+ * Whether an expression names the plugin context.
+ *
+ * `.set`, `.get`, `.on` and `.emit` are the plugin API's names and also
+ * `Map`'s, `Set`'s, and every EventEmitter's. Without this guard the check
+ * reads `this.steps.set(\`${turn}:${step}\`, time)` — an ordinary composite Map
+ * key — as evasion, which alone degrades the whole report and makes every
+ * Tier B negative unreliable. Element access is already guarded this way; this
+ * makes the call form agree with it.
+ * @param node - the receiver expression.
+ * @returns true when the receiver is a known context binding.
+ */
+function isDispatchReceiver(node) {
+    if (ts.isIdentifier(node))
+        return DISPATCH_RECEIVERS.has(node.text);
+    // `this.ctx.on(…)` and `self.ctx.on(…)` are the same receiver held on a field.
+    if (ts.isPropertyAccessExpression(node))
+        return DISPATCH_RECEIVERS.has(node.name.text);
+    return false;
+}
+/**
+ * The receiver's own name, for the finding's title.
+ * @param node - the receiver expression.
+ * @returns the identifier or member name.
+ */
+function receiverName(node) {
+    if (ts.isIdentifier(node))
+        return node.text;
+    if (ts.isPropertyAccessExpression(node))
+        return node.name.text;
+    return '?';
+}
+/**
+ * Whether a node builds a string at runtime rather than naming one. A plain
+ * identifier is deliberately excluded: `ctx.on(EVENT_NAME, …)` against a module
+ * constant is ordinary code, and treating it as evasion would degrade the
+ * analysis of nearly every well-written plugin.
+ * @param node - the argument node.
+ * @returns true for concatenation, an interpolated template, or a call.
+ */
+function isAssembledName(node) {
+    if (node === undefined)
+        return false;
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken)
+        return true;
+    if (ts.isTemplateExpression(node))
+        return true;
+    return ts.isCallExpression(node);
+}
+/**
+ * The literal text of a node, or `null`.
+ * @param node - the node.
+ * @returns the literal text.
+ */
+function literalOf(node) {
+    if (node === undefined)
+        return null;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    return null;
+}
+/**
+ * Tier C checks that do **not** make a Tier B negative unreliable.
+ *
+ * Every other check here says the analyzer could not read something. C3 says
+ * the opposite: the bytes were read exactly as written and exactly as they will
+ * run — what cannot be checked is whether they match the repository that
+ * claims to have produced them. That is worth reporting and it is not a reason
+ * to distrust the parse, and treating it as one marks every ordinary published
+ * tarball `degraded`, because shipping built output and no source is what
+ * publishing a package *is*.
+ */
+export const NON_DEGRADING_CHECKS = new Set(['C3']);
+/** C3, C6 — shipped build output with nothing to compare it against. */
+function checkSourcelessBuild(input) {
+    const built = input.sourceFiles.filter(path => /^(?:lib|dist|build|out)\//.test(path));
+    const authored = input.sourceFiles.filter(path => /^(?:src|source)\//.test(path));
+    const minified = input.sourceFiles.filter(path => path.endsWith('.min.js'));
+    const findings = [];
+    if (built.length > 0 && authored.length === 0) {
+        findings.push(tierC({
+            checkId: 'C3',
+            name: 'sourceless-build-output',
+            severity: 'low',
+            title: `Ships ${built.length} built file(s) and no source`,
+            detail: 'What runs is the built output, so that is what this tool analysed — but there is nothing in the '
+                + 'package to check the build against. Whether the source that produced it matches the repository is not '
+                + 'decidable from here.',
+            evidence: { file: built[0] ?? '', snippet: snippet(built.slice(0, 5).join(', ')) },
+            bypass: 'none — this finding is about the analysis, not about the plugin',
+        }));
+    }
+    for (const path of minified) {
+        findings.push(tierC({
+            checkId: 'C6',
+            name: 'minified-artifact',
+            severity: 'low',
+            title: `\`${path}\` is a minified artifact`,
+            detail: 'A `.min.js` file is output, not source. It was still parsed, but nothing about its readability '
+                + 'supports a confident negative.',
+            evidence: { file: path },
+            bypass: 'none — this finding is about the analysis, not about the plugin',
+        }));
+    }
+    return findings;
+}
+/** C4 — files the reader refused or could not decode. */
+function checkUnreadableFiles(input) {
+    const skipped = input.source.skipped;
+    if (skipped.length === 0)
+        return [];
+    const byReason = new Map();
+    for (const entry of skipped) {
+        byReason.set(entry.reason, [...byReason.get(entry.reason) ?? [], entry.path]);
+    }
+    return [...byReason].map(([reason, paths]) => tierC({
+        checkId: 'C4',
+        name: 'unreadable-payload',
+        severity: reason === 'binary' ? 'medium' : 'low',
+        title: `${paths.length} file(s) were not analysed (${reason})`,
+        detail: reason === 'binary'
+            ? 'Binary payloads — native addons, WebAssembly, archives — are shipped code this tool cannot read at all. '
+                + 'A mounted layer can load a `.node` addon with no restriction whatsoever.'
+            : 'These files exceeded a size or count cap and were not read. Nothing is claimed about their contents.',
+        evidence: { file: paths[0] ?? '', snippet: snippet(paths.slice(0, 8).join(', ')) },
+        bypass: 'none — this finding is about the analysis, not about the plugin',
+    }));
+}
+/** C5 — a patch layer whose structure hit a walk ceiling before it was read out. */
+function checkPatchWalkLimit(input) {
+    return input.patches.filter(patch => patch.limit !== null).map(patch => tierC({
+        checkId: 'C5',
+        name: 'patch-walk-truncated',
+        severity: 'high',
+        title: `\`${patch.file}\` was only read in part (${patch.limit === 'depth' ? 'nesting' : 'node count'} ceiling)`,
+        detail: patch.limit === 'depth'
+            ? 'The layer nests deeper than any composition needs. Everything below that point is unread, so no Tier A '
+                + 'reading of this layer is complete.'
+            : 'The layer expands to more nodes than the analyzer will walk. YAML anchors make that cheap to write — a '
+                + 'few hundred bytes of `*alias` references describe a graph with billions of paths through it — and the '
+                + 'usual reason to write one is that a reader gives up before reaching what it hides. Rows past the '
+                + 'ceiling were not read.',
+        evidence: { file: patch.file },
+        bypass: 'none — this finding is about the analysis, not about the plugin',
+    }));
+}
+/**
+ * Run every Tier C check.
+ * @param input - the decoded package.
+ * @returns findings, unordered.
+ */
+export function runTierC(input) {
+    return [
+        ...checkMinification(input),
+        ...checkDynamicDispatch(input),
+        ...checkSourcelessBuild(input),
+        ...checkUnreadableFiles(input),
+        ...checkPatchWalkLimit(input),
+    ];
+}

package/lib/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * `dsh-inspect` — the command line face of the inspector.
+ *
+ * Exit codes are the CI contract and are deliberately three-valued:
+ * `0` clean, `1` findings at or above the threshold, `2` the analysis could not
+ * be performed. A job that cannot tell "the analyzer broke" from "the plugin is
+ * clean" is the failure mode that split exists to prevent.
+ * @module dsh-plugin-inspector/cli
+ */
+import process from 'node:process';
+import { exceedsThreshold, inspect, TOOL_VERSION } from "./inspect.js";
+import { SEVERITY_RANK } from "./model.js";
+import { renderHuman, renderJson } from "./report.js";
+/** Exit codes this tool uses. */
+export const EXIT = {
+    clean: 0,
+    findings: 1,
+    unanalysable: 2,
+};
+const USAGE = `dsh-inspect — know what a DeepSeek Harness plugin does before you install it
+
+Usage
+  dsh-inspect <target> [options]
+
+  <target>                A plugin directory, or an npm tarball (.tgz / .tar.gz).
+                          Nothing in the target is installed, built, or executed.
+
+Options
+  --json                  Emit the machine-readable JSON document on stdout.
+  --fail-on <severity>    Exit 1 at or above this severity.
+                          critical | high | medium | low | none    (default: high)
+  --no-color              Plain text, no ANSI.
+  --version               Print version.
+  --help                  Print this message.
+
+Exit codes
+  0  analysis completed, nothing at or above --fail-on
+  1  analysis completed, at least one finding at or above --fail-on
+  2  analysis could not be performed
+
+To inspect a published package without installing it:
+  npm pack <name>@<version> --pack-destination /tmp && dsh-inspect /tmp/<name>-<version>.tgz
+`;
+/** Raised for a malformed command line; the message is printed and the tool exits 2. */
+export class UsageError extends Error {
+}
+/**
+ * Parse argv.
+ * @param argv - arguments after the node binary and script path.
+ * @returns the parsed options, or `null` when usage or version was requested.
+ * @throws UsageError on an unrecognised or incomplete argument.
+ */
+export function parseArgs(argv) {
+    let target = null;
+    let json = false;
+    let failOn = 'high';
+    let color = process.stdout.isTTY === true;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? '';
+        if (argument === '--help' || argument === '-h') {
+            process.stdout.write(USAGE);
+            return null;
+        }
+        if (argument === '--version' || argument === '-V') {
+            process.stdout.write(`${TOOL_VERSION}\n`);
+            return null;
+        }
+        if (argument === '--json') {
+            json = true;
+            continue;
+        }
+        if (argument === '--no-color') {
+            color = false;
+            continue;
+        }
+        if (argument === '--color') {
+            color = true;
+            continue;
+        }
+        if (argument === '--fail-on') {
+            const value = argv[index + 1];
+            index += 1;
+            if (value === undefined)
+                throw new UsageError('--fail-on needs a severity');
+            if (value !== 'none' && !(value in SEVERITY_RANK)) {
+                throw new UsageError(`--fail-on must be one of critical, high, medium, low, none — got ${value}`);
+            }
+            failOn = value;
+            continue;
+        }
+        if (argument.startsWith('-'))
+            throw new UsageError(`unknown option ${argument}`);
+        if (target !== null)
+            throw new UsageError('only one target may be inspected at a time');
+        target = argument;
+    }
+    if (target === null)
+        throw new UsageError('a target directory or tarball is required');
+    return { target, json, failOn, color };
+}
+/**
+ * Run one invocation.
+ * @param argv - arguments after the node binary and script path.
+ * @returns the process exit code.
+ */
+export async function main(argv) {
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        process.stderr.write(`dsh-inspect: ${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
+        return EXIT.unanalysable;
+    }
+    if (options === null)
+        return EXIT.clean;
+    try {
+        const report = await inspect(options.target);
+        process.stdout.write(options.json ? renderJson(report) : renderHuman(report, options.color));
+        return exceedsThreshold(report, options.failOn) ? EXIT.findings : EXIT.clean;
+    }
+    catch (error) {
+        process.stderr.write(`dsh-inspect: ${error instanceof Error ? error.message : String(error)}\n`);
+        return EXIT.unanalysable;
+    }
+}
+/**
+ * Report a failure that reached no `try`, and say which exit code it is.
+ *
+ * Not every failure can be caught where it happens. A `RangeError` raised
+ * inside a stream's `'end'` handler is thrown at an EventEmitter, not at the
+ * `await`, so it walks past every `catch` in this program and kills the process
+ * with Node's default handler — which exits **1**, the code that means "the
+ * analysis completed and found something at or above --fail-on". A CI job then
+ * reads a crash as a verdict. The whole point of a separate code 2 is that this
+ * cannot happen, so the last resort has to be covered too.
+ * @param error - whatever was thrown.
+ * @returns the exit code to leave with.
+ */
+export function reportFatal(error) {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    process.stderr.write(`dsh-inspect: the analysis could not be completed: ${message}\n`);
+    return EXIT.unanalysable;
+}
+if (import.meta.main) {
+    process.on('uncaughtException', (error) => {
+        process.exit(reportFatal(error));
+    });
+    process.on('unhandledRejection', (error) => {
+        process.exit(reportFatal(error));
+    });
+    process.exitCode = await main(process.argv.slice(2));
+}