dsh-plugin-inspector 0.1.0

package/lib/types/publish.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Which files of a working tree npm would actually publish.
+ *
+ * A directory target is a repository checkout, and a repository holds far more
+ * than the package: tests, fixtures, CI config, build scratch. None of that is
+ * installed, none of it is mounted, and none of it can act on a user. Reporting
+ * on it produces findings nobody can act on and buries the ones they can, so
+ * the directory reader is scoped to the set npm would put in the tarball.
+ *
+ * The rules are npm's, transcribed from `npm-packlist`: the `files` allowlist
+ * when the manifest declares one, otherwise `.npmignore` — or `.gitignore` when
+ * there is no `.npmignore` — over everything else. A handful of files are
+ * always published whatever the manifest says, and a handful are never
+ * published whatever it says.
+ * @module dsh-plugin-inspector/publish
+ */
+/** How the publish set was decided, reported so the user knows what was read. */
+export type PublishBasis = 'files-allowlist' | 'ignore-rules' | 'tarball';
+/** A path is published, or it is not. */
+export interface PublishSet {
+    readonly basis: PublishBasis;
+    /**
+     * Whether npm would put this path in the tarball.
+     * @param path - package-relative POSIX path.
+     * @returns true when the file is published.
+     */
+    includes: (path: string) => boolean;
+}
+/**
+ * Whether a glob matches a path.
+ * @param pattern - the glob, package-relative and POSIX.
+ * @param path - the path, package-relative and POSIX.
+ * @returns true when the glob matches.
+ */
+export declare function globMatch(pattern: string, path: string): boolean;
+/** Everything the publish set needs from the working tree. */
+export interface PublishInputs {
+    /** The manifest's `files` array, or `null` when it declares none. */
+    readonly files: readonly string[] | null;
+    /** `.npmignore` content, or `null` when the package has none. */
+    readonly npmignore: string | null;
+    /** `.gitignore` content, or `null` when the package has none. */
+    readonly gitignore: string | null;
+    /** The manifest's `main`, which npm publishes even outside the allowlist. */
+    readonly main: string | null;
+}
+/**
+ * Build the publish set for a working tree.
+ * @param inputs - the manifest fields and ignore files the decision needs.
+ * @returns the membership test and the basis it used.
+ */
+export declare function publishSet(inputs: PublishInputs): PublishSet;
+/** Every file is published: a tarball is already the publish set. */
+export declare const TARBALL_PUBLISH_SET: PublishSet;
+//# sourceMappingURL=publish.d.ts.map

package/lib/types/report.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Rendering a report for a person and for a machine.
+ *
+ * The human renderer has one rule it is not allowed to break: when
+ * `analysis.negativesReliable` is false it must not print a clean bill. Saying
+ * "no findings" about a package the tool could not read would be worse than
+ * printing nothing at all, so the degraded banner replaces that line rather
+ * than accompanying it.
+ * @module dsh-plugin-inspector/report
+ */
+import { type Report } from './model.ts';
+/**
+ * Serialise the report as stable JSON. Key order is fixed by the object
+ * literals in `inspect.ts` and findings are pre-sorted, so two runs over the
+ * same input produce byte-identical output.
+ * @param report - the report.
+ * @returns pretty-printed JSON with a trailing newline.
+ */
+export declare function renderJson(report: Report): string;
+/**
+ * Render the human report.
+ * @param report - the report.
+ * @param color - whether to emit ANSI colour.
+ * @returns the rendered text, ending in a newline.
+ */
+export declare function renderHuman(report: Report, color: boolean): string;
+//# sourceMappingURL=report.d.ts.map

package/lib/types/source.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Reading the package under analysis without installing, building, or running
+ * any part of it.
+ *
+ * A directory is walked directly. A tarball is decoded **entirely in memory** —
+ * nothing is ever written to disk. That is a safety property, not an
+ * optimisation: it makes tar path traversal (`../../.ssh/authorized_keys`)
+ * structurally impossible rather than something a filter has to catch, and it
+ * lets a test assert that analysing a hostile tarball touched no file.
+ *
+ * Every cap is enforced *while* bytes arrive, not after. A tar entry is
+ * abandoned the moment its running total passes {@link MAX_FILE_BYTES}, so a
+ * 27 MB tarball holding a 6 GB member costs 27 MB of decompression and no
+ * memory at all. Enforcing a cap on an already-materialised buffer is not a
+ * cap.
+ *
+ * Symbolic links are recorded and never followed, for the same reason: a link
+ * pointing outside the package is not part of the package.
+ * @module dsh-plugin-inspector/source
+ */
+import type { SkippedFile } from './model.ts';
+import { type PublishBasis } from './publish.ts';
+/** Largest single file the analyzer will hold in memory. */
+export declare const MAX_FILE_BYTES: number;
+/** Largest total payload the analyzer will hold in memory. */
+export declare const MAX_TOTAL_BYTES: number;
+/** Largest number of files the analyzer will consider. */
+export declare const MAX_ENTRIES = 10000;
+/** The resource ceilings one read runs under. */
+export interface ReadLimits {
+    readonly maxFileBytes: number;
+    readonly maxTotalBytes: number;
+    readonly maxEntries: number;
+}
+/** The shipping ceilings. Tests substitute smaller ones to exercise each cap. */
+export declare const DEFAULT_LIMITS: ReadLimits;
+/** Thrown when the target cannot be read at all, which is exit code 2, not a finding. */
+export declare class SourceError extends Error {
+}
+/** The analysed package, decoded into memory. */
+export interface PluginSource {
+    readonly kind: 'directory' | 'tarball';
+    /** The target as the user gave it, resolved to an absolute path. */
+    readonly path: string;
+    /** Package-relative POSIX path to UTF-8 text, for every readable text file. */
+    readonly files: ReadonlyMap<string, string>;
+    /** Files deliberately not read, each with the reason. Feeds Tier C. */
+    readonly skipped: readonly SkippedFile[];
+    readonly bytesRead: number;
+    /** How the set of analysed files was decided. */
+    readonly publishBasis: PublishBasis;
+    /** Working-tree files npm would not publish, and which were therefore not read. */
+    readonly unpublishedFiles: number;
+}
+/**
+ * Decompressed tar bytes one tarball may produce before the read is abandoned.
+ *
+ * Eight times the in-memory ceiling. A plugin tarball is never this large, and
+ * one that is has already answered the only question worth asking about it.
+ */
+export declare const MAX_STREAM_BYTES: number;
+/**
+ * Read the package under analysis.
+ * @param target - a plugin directory, or a `.tgz` / `.tar.gz` npm tarball.
+ * @param limits - resource ceilings; defaults to {@link DEFAULT_LIMITS}.
+ * @returns the decoded package.
+ * @throws SourceError when the target does not exist, is not a readable
+ * tarball, or holds no `package.json`.
+ */
+export declare function loadSource(target: string, limits?: ReadLimits): Promise<PluginSource>;
+//# sourceMappingURL=source.d.ts.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "dsh-plugin-inspector",
+  "version": "0.1.0",
+  "description": "Know what a DeepSeek Harness plugin does before you install it — static pre-install analysis of a plugin directory or tarball",
+  "license": "MIT",
+  "author": "Ivan Tyshchenko",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CharlotteN7/dsh-plugin-inspector.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CharlotteN7/dsh-plugin-inspector/issues"
+  },
+  "homepage": "https://github.com/CharlotteN7/dsh-plugin-inspector#readme",
+  "engines": {
+    "node": "^22.19.0 || >=24"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "bin": {
+    "dsh-inspect": "lib/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "static-analysis",
+    "supply-chain"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.2.0",
+    "tar": "^7.5.7",
+    "typescript": "^5.9.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.20.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "tsx": "^4.22.4",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run --config vitest.config.ts",
+    "test:coverage": "vitest run --config vitest.config.ts --coverage",
+    "inspect": "node --experimental-strip-types src/cli.ts",
+    "test:e2e": "pnpm run build && vitest run --config vitest.e2e.config.ts"
+  }
+}