dsh-plugin-inspector 0.3.0 → 0.5.0

package/lib/cordis-yaml.js

@@ -28,6 +28,7 @@ const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
     kind: 'scalar',
     resolve: data => typeof data === 'string',
     construct: (data) => {
+        /* v8 ignore next -- js-yaml calls `construct` only for data its `resolve` accepted, which is a string. */
         if (typeof data !== 'string')
             throw new TypeError('!!js requires a scalar string');
         return { __jsExpr: data };
@@ -44,35 +45,77 @@ export const patchSchema = yaml.JSON_SCHEMA.extend(jsExprType);
 export const EXPRESSION_CLASSES = [
     'literal', 'inert-read', 'harness-call', 'call', 'mutation', 'module-access', 'unparseable',
 ];
-/** Nodes one patch layer may be walked through before the walk gives up. */
+/**
+ * The two ceilings that make reading a patch layer terminate.
+ *
+ * They apply to {@link expandAliases}, and through it to everything downstream:
+ * the walk runs over the tree the expansion produced, which holds at most
+ * `MAX_WALK_NODES` nodes nested at most `MAX_WALK_DEPTH` deep, so the walk needs
+ * no ceiling of its own.
+ */
 export const MAX_WALK_NODES = 200_000;
-/** Nesting one patch layer may reach before the walk gives up. */
+/** Nesting one patch layer may reach before the reader gives up. */
 export const MAX_WALK_DEPTH = 200;
 /**
- * Charge one node against the budget, and refuse a node already walked.
- * @param budget - the shared budget.
- * @param value - the node about to be walked.
- * @param depth - the current nesting depth.
- * @returns true when the walk may descend into this node.
+ * Materialise a parsed patch layer's alias graph as a tree, so that every
+ * occurrence of an anchored node is a distinct node at its own path.
+ *
+ * js-yaml resolves `*a` to the *same JavaScript object* as `&a`, not to a copy.
+ * A reader that walks the result as a graph and skips an object it has already
+ * seen therefore attributes an anchored node to whichever position it reached
+ * first and drops every other one — which is how a row anchored in an inert
+ * `inject:` slot and aliased into a real patch slot came to be read as inert
+ * and analysed no further. The loader has no such notion: `interpolate` in
+ * `vendor/loader/src/config/utils.ts` maps over arrays and objects as a tree
+ * and evaluates each occurrence it reaches, and `applyEntryPatches` reads each
+ * element of the patch list on its own. Expanding first makes this module agree
+ * with both.
+ *
+ * The expansion is bounded, which is what keeps an alias bomb from becoming a
+ * hang: a 475-byte file can describe 100 nodes with 31 billion paths through
+ * them, and materialising those paths is exactly the non-terminating walk the
+ * ceilings exist to stop. Past either ceiling the subtree becomes `null` and
+ * the limit is recorded, so a truncated read is reported rather than presented
+ * as a complete one.
+ * @param entries - the entry list js-yaml returned.
+ * @returns the expanded entries, whether an alias was used, and the ceiling hit.
  */
-function admit(budget, value, depth) {
-    if (budget.limit !== null)
-        return false;
-    if (depth > MAX_WALK_DEPTH) {
-        budget.limit = 'depth';
-        return false;
-    }
-    budget.nodes += 1;
-    if (budget.nodes > MAX_WALK_NODES) {
-        budget.limit = 'nodes';
-        return false;
-    }
-    if (typeof value !== 'object' || value === null)
-        return true;
-    if (budget.visited.has(value))
-        return false;
-    budget.visited.add(value);
-    return true;
+function expandAliases(entries) {
+    const state = { aliased: false, nodes: 1, limit: null };
+    const seen = new WeakSet([entries]);
+    const expand = (value, depth) => {
+        if (typeof value !== 'object' || value === null)
+            return value;
+        if (state.limit !== null)
+            return null;
+        if (depth > MAX_WALK_DEPTH) {
+            state.limit = 'depth';
+            return null;
+        }
+        state.nodes += 1;
+        if (state.nodes > MAX_WALK_NODES) {
+            state.limit = 'nodes';
+            return null;
+        }
+        if (seen.has(value))
+            state.aliased = true;
+        else
+            seen.add(value);
+        if (Array.isArray(value))
+            return value.map(item => expand(item, depth + 1));
+        const clone = {};
+        for (const [key, child] of Object.entries(value)) {
+            // Assignment would invoke the `__proto__` setter, and js-yaml keeps a
+            // `__proto__` key from the document as an own property precisely so that
+            // it stays data. Defining the property keeps it data here too.
+            Object.defineProperty(clone, key, {
+                value: expand(child, depth + 1), enumerable: true, writable: true, configurable: true,
+            });
+        }
+        return clone;
+    };
+    const expanded = entries.map(entry => expand(entry, 1));
+    return { entries: expanded, aliased: state.aliased, limit: state.limit };
 }
 /** Thrown when the patch file cannot be parsed as an entry list. */
 export class PatchParseError extends Error {
@@ -126,6 +169,7 @@ export function classifyExpression(expression) {
         new Function(`return (${expression})`);
     }
     catch (error) {
+        /* v8 ignore next -- the Function constructor rejects a body only with a SyntaxError. */
         return { class: 'unparseable', parseError: error instanceof Error ? error.message : String(error) };
     }
     const source = ts.createSourceFile('expr.ts', `(${expression})`, ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
@@ -218,8 +262,6 @@ function isInertCall(node) {
  * @param depth - the current nesting depth.
  */
 function collect(value, path, slot, sink, depth) {
-    if (!admit(sink.budget, value, depth))
-        return;
     if (isJsExpr(value)) {
         const classified = classifyExpression(value.__jsExpr);
         sink.expressions.push({
@@ -294,8 +336,6 @@ function isTreeCarrier(entry) {
 function walkRow(value, path, intoGroupId, sink, depth) {
     if (!isRecord(value))
         return;
-    if (!admit(sink.budget, value, depth))
-        return;
     const carrier = isTreeCarrier(value);
     sink.inserts.push({
         path,
@@ -334,8 +374,6 @@ function walkPatchList(list, prefix, sink, depth) {
         const path = `${prefix}[${index}]`;
         if (!isRecord(patch))
             continue;
-        if (!admit(sink.budget, patch, depth))
-            continue;
         const id = typeof patch.id === 'string' ? patch.id : null;
         if (Array.isArray(patch.insert)) {
             for (const [rowIndex, row] of patch.insert.entries()) {
@@ -365,29 +403,27 @@ function walkPatchList(list, prefix, sink, depth) {
  * @throws PatchParseError when the text is not a loadable entry list.
  */
 export function parsePatchDocument(file, text) {
-    let document;
+    let loaded;
     try {
-        document = yaml.load(text, { schema: patchSchema });
+        loaded = yaml.load(text, { schema: patchSchema });
     }
     catch (error) {
+        /* v8 ignore next -- js-yaml rejects a document only with a YAMLException. */
         const message = error instanceof Error ? error.message : String(error);
         throw new PatchParseError(message, /(?<!!)!js(?![a-zA-Z0-9_-])/.test(text));
     }
-    if (!Array.isArray(document)) {
+    if (!Array.isArray(loaded)) {
         throw new PatchParseError('a patch layer must be a top-level array of entries', false);
     }
-    const sink = {
-        overrides: [],
-        inserts: [],
-        expressions: [],
-        budget: { visited: new WeakSet(), nodes: 0, limit: null },
-    };
-    walkPatchList(document, '', sink, 0);
+    const expansion = expandAliases(loaded);
+    const sink = { overrides: [], inserts: [], expressions: [] };
+    walkPatchList(expansion.entries, '', sink, 0);
     return {
         file,
         overrides: sink.overrides,
         inserts: sink.inserts,
         expressions: sink.expressions,
-        limit: sink.budget.limit,
+        limit: expansion.limit,
+        aliased: expansion.aliased,
     };
 }

package/lib/files.js

@@ -20,6 +20,23 @@ export function isSourceFile(path) {
         return false;
     return SOURCE_EXTENSIONS.some(extension => path.endsWith(extension));
 }
+/** Extensions a `binding.gyp` target compiles. */
+const NATIVE_SOURCE_EXTENSIONS = [
+    '.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.hxx', '.m', '.mm', '.s', '.asm',
+];
+/**
+ * Whether a path is C-family source a native build would compile.
+ *
+ * Used to answer one question about a package that ships a `binding.gyp`: is
+ * there anything in it to build. A gyp with no compilable source is a build
+ * declaration whose only effect is that a build runs.
+ * @param path - package-relative POSIX path.
+ * @returns true when the file is C-family source or a header.
+ */
+export function isNativeSource(path) {
+    const lower = path.toLowerCase();
+    return NATIVE_SOURCE_EXTENSIONS.some(extension => lower.endsWith(extension));
+}
 /**
  * Whether a path is markdown that can reach the model verbatim.
  *
@@ -34,6 +51,7 @@ export function isSourceFile(path) {
  */
 export function isModelVisibleText(path) {
     const segments = path.split('/');
+    /* v8 ignore next -- `split` returns at least one element for any string. */
     const base = segments.at(-1) ?? '';
     if (base === 'SKILL.md' || base === 'AGENTS.md' || base === 'CLAUDE.md')
         return true;
@@ -49,6 +67,7 @@ export function isModelVisibleText(path) {
  * @returns true for a cordis YAML file.
  */
 export function isCordisConfigFile(path) {
+    /* v8 ignore next -- `split` returns at least one element for any string. */
     const base = path.split('/').at(-1) ?? '';
     return /cordis/.test(base) && (base.endsWith('.yml') || base.endsWith('.yaml'));
 }

package/lib/inspect.js

@@ -108,11 +108,13 @@ export function analyze(source, registry) {
     const patches = [];
     const patchFailures = [];
     if (mounted !== null) {
+        /* v8 ignore next -- `mounted` is non-null only when `source.files` holds that key. */
         const text = source.files.get(mounted) ?? '';
         try {
             patches.push(parsePatchDocument(mounted, text));
         }
         catch (error) {
+            /* v8 ignore next -- `parsePatchDocument` reports every refusal as a PatchParseError. */
             if (!(error instanceof PatchParseError))
                 throw error;
             patchFailures.push({ file: mounted, error });

package/lib/knowledge.js

@@ -295,12 +295,11 @@ export const INSTALL_LIFECYCLE_SCRIPTS = [
  * Command shapes that make an install lifecycle script the attack rather than
  * the build.
  *
- * The head-to-head measurement on 6,420 malicious and 7,288 benign npm packages
- * (ASE 2026) puts 72.21 % of malicious packages on a lifecycle hook and 21.2 %
- * with the whole attack inside `package.json` scripts — no shipped module at
- * all. That second number is what this table is for: it is the case where the
- * command line itself fetches, decodes, or evaluates, and there is nothing else
- * to read.
+ * The case this table is for is the one where the command line itself fetches,
+ * decodes, or evaluates: the whole attack sits in `package.json` and there is
+ * no shipped module to read. A lifecycle hook alone does not distinguish that
+ * from a build, which is why the hook is a category at `medium` and only the
+ * command raises it.
  *
  * Each pattern is chosen against the measured false-positive side rather than
  * against the idea of a build script. The five packages in the pinned corpus
@@ -330,6 +329,38 @@ export const LIFECYCLE_SIGNALS = [
         meaning: 'decodes an encoded payload, which is how a command hides what it runs',
     },
 ];
+/**
+ * Every lifecycle signal a command line matches.
+ *
+ * One entry point rather than the filter written out twice, because the table
+ * now grades two different things — a `package.json` lifecycle command (A1) and
+ * a `binding.gyp` build step (A24) — and a rule added to it has to reach both.
+ * @param command - the command line, or the text that holds one.
+ * @returns the matching signals, in table order.
+ */
+export function matchingLifecycleSignals(command) {
+    return LIFECYCLE_SIGNALS.filter(signal => signal.pattern.test(command));
+}
+/**
+ * The file `node-gyp` reads, at the package root and nowhere else.
+ *
+ * npm and pnpm treat its presence as a declaration: a package that ships one
+ * and declares no `install` or `preinstall` script gets `node-gyp rebuild` as
+ * its install command. That default appears in no field of `package.json`.
+ */
+export const NATIVE_BUILD_FILE = 'binding.gyp';
+/**
+ * GYP keys that carry a command line rather than a list of sources to compile.
+ *
+ * `actions` and `rules` run a program during the build; `postbuilds` runs one
+ * after it. A target that only lists `sources`, `include_dirs` and `libraries`
+ * compiles code the package shipped and runs nothing else.
+ *
+ * Matched against the whole file, so a block nested inside a `conditions` arm
+ * counts the same as a top-level one — which is the point, because a condition
+ * is where a build step goes to be read past.
+ */
+export const GYP_COMMAND_KEYS = /['"](?:actions?|rules?|postbuilds)['"]\s*:/;
 /** Entry fields the loader never interpolates: a `!!js` node here is inert data. */
 export const STATIC_ENTRY_FIELDS = [
     'id', 'name', 'group', 'inject', 'intercept', 'isolate',

package/lib/manifest.js

@@ -103,6 +103,7 @@ export function parseManifest(text) {
         parsed = JSON.parse(text);
     }
     catch (error) {
+        /* v8 ignore next -- JSON.parse rejects text only with a SyntaxError. */
         throw new ManifestError(`package.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (!isRecord(parsed))

package/lib/publish.js

@@ -54,6 +54,7 @@ function matchSegments(pattern, path) {
         }
         if (s === path.length)
             return false;
+        /* v8 ignore next -- both indices are checked against their lengths above. */
         if (!matchSegment(pattern[p] ?? '', path[s] ?? ''))
             return false;
         return step(p + 1, s + 1);
@@ -152,6 +153,7 @@ function ignoreMatches(rule, path) {
                 return true;
             continue;
         }
+        /* v8 ignore next -- `end` runs from 1 to `segments.length`, so the index is in range. */
         if (globMatch(rule.pattern, segments[end - 1] ?? ''))
             return true;
     }

package/lib/registry.js

@@ -127,6 +127,7 @@ export async function resolvePackage(spec, options = {}) {
         document = JSON.parse(body.toString('utf8'));
     }
     catch (error) {
+        /* v8 ignore next -- JSON.parse rejects text only with a SyntaxError. */
         throw new RegistryError(`${url} did not return JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
     const record = asRecord(document);

package/lib/report.js

@@ -91,6 +91,7 @@ function wrap(text, width) {
             current = word;
         }
     }
+    /* v8 ignore next -- every wrapped string is a finding's detail, and none is empty. */
     if (current !== '')
         lines.push(current);
     return lines;
@@ -144,9 +145,11 @@ function renderFacts(report, paint) {
                         ? 'yes — the registry marks this package as running one at install time'
                         : 'no — the registry does not mark this package as running one'],
             ],
+        /* v8 ignore start -- `mountsAsBundle` is true exactly when the manifest declared a path. */
         ['mounted layer', facts.mountsAsBundle
                 ? `yes — dsh.bundle.patch = ${facts.bundlePatchPath ?? '?'} (imported into the harness process at the agent's uid)`
                 : 'no — installs as a plain library, and dsh plugin add prints a warning saying so'],
+        /* v8 ignore stop */
         ['browser bundle', facts.shipsClientBundle ? 'yes — dsh.client with an ./client export, executed in the user\'s browser' : 'no'],
         ['rows inserted', facts.insertedRows.length === 0
                 ? 'none'
@@ -176,7 +179,9 @@ function renderFacts(report, paint) {
  * @returns the rendered text, ending in a newline.
  */
 export function renderHuman(report, color) {
+    /* v8 ignore start -- every call site passes a literal key of COLOR. */
     const paint = (code, text) => color ? `${COLOR[code] ?? ''}${text}${COLOR.reset}` : text;
+    /* v8 ignore stop */
     const lines = ['', ...renderFacts(report, paint)];
     if (report.findings.length > 0) {
         const counts = SEVERITIES

package/lib/source.js

@@ -31,11 +31,19 @@ export const MAX_FILE_BYTES = 4 * 1024 * 1024;
 export const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 /** Largest number of files the analyzer will consider. */
 export const MAX_ENTRIES = 10_000;
+/**
+ * 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 const MAX_STREAM_BYTES = 8 * MAX_TOTAL_BYTES;
 /** The shipping ceilings. Tests substitute smaller ones to exercise each cap. */
 export const DEFAULT_LIMITS = {
     maxFileBytes: MAX_FILE_BYTES,
     maxTotalBytes: MAX_TOTAL_BYTES,
     maxEntries: MAX_ENTRIES,
+    maxStreamBytes: MAX_STREAM_BYTES,
 };
 /** Directories never descended into: not shipped, and not the package's own code. */
 const SKIPPED_DIRECTORIES = new Set([
@@ -76,6 +84,7 @@ function countEntry(collector, path) {
  * @param buffer - the file content.
  */
 function store(collector, path, buffer) {
+    /* v8 ignore next 4 -- both callers check the size before reading; this is the same ceiling held at the last point that could still allocate. */
     if (buffer.byteLength > collector.limits.maxFileBytes) {
         collector.skipped.push({ path, reason: 'size-cap' });
         return;
@@ -170,6 +179,7 @@ function stripRoot(entryPath) {
     if (slash < 0)
         return undefined;
     const remainder = normalized.slice(slash + 1);
+    /* v8 ignore next -- an entry name ending in `/` is a directory entry, which the parser never hands to this. */
     if (remainder === '')
         return undefined;
     const segments = [];
@@ -186,13 +196,6 @@ function stripRoot(entryPath) {
     }
     return segments.length === 0 ? undefined : segments.join('/');
 }
-/**
- * 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 const MAX_STREAM_BYTES = 8 * MAX_TOTAL_BYTES;
 /**
  * A stage that fails the pipeline once the decompressed stream passes a
  * ceiling. Nothing downstream keeps the bytes, but *producing* eight gigabytes
@@ -308,7 +311,7 @@ async function readTarStream(bytes, gzipped, collector) {
         },
     });
     const inflate = gzipped ? createGunzip() : new PassThrough();
-    await pipeline(bytes, inflate, byteCeiling(MAX_STREAM_BYTES), parser);
+    await pipeline(bytes, inflate, byteCeiling(collector.limits.maxStreamBytes), parser);
     await Promise.all(pending);
     if (failure !== null)
         throw failure;

package/lib/types/checks/tier-b.d.ts

@@ -14,6 +14,26 @@
  */
 import type { Finding } from '../model.ts';
 import type { CheckInput } from './input.ts';
+/** One filesystem location that holds credentials, and how it is spelled. */
+export interface CredentialPath {
+    readonly id: string;
+    /** Pattern source, matched case-insensitively anywhere in a string literal. */
+    readonly pattern: string;
+}
+/**
+ * Filesystem locations that hold credentials.
+ *
+ * A table rather than one regular expression so each location can be pinned by
+ * name: `tests/unit/rule-tables.spec.ts` iterates this export, and a location
+ * added without a fixture fails there.
+ */
+export declare const CREDENTIAL_PATHS: readonly CredentialPath[];
+/**
+ * Whether a string names a location that holds credentials.
+ * @param text - the literal text of a string in shipped source.
+ * @returns true when it names one of {@link CREDENTIAL_PATHS}.
+ */
+export declare function matchesCredentialPath(text: string): boolean;
 /**
  * Run every Tier B check.
  * @param input - the decoded package.

package/lib/types/checks/tier-c.d.ts

@@ -14,18 +14,19 @@
  * from claiming nothing was found.
  * @module dsh-plugin-inspector/checks/tier-c
  */
-import type { Finding } from '../model.ts';
+import { type Finding } from '../model.ts';
 import type { CheckInput } from './input.ts';
 /**
  * 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*.
+ * Every other check here says the analyzer could not read something. C3 and C8
+ * say the opposite. C3: 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. Treating that as an unreadable package
+ * marks every ordinary published tarball `degraded`, because shipping built
+ * output and no source is what publishing a package *is*. C8: the escape is
+ * resolved by the parser before any check reads the name, so the analysis of an
+ * escaped identifier is exactly as good as the analysis of a plain one.
  */
 export declare const NON_DEGRADING_CHECKS: ReadonlySet<string>;
 /**

package/lib/types/cordis-yaml.d.ts

@@ -82,10 +82,23 @@ export interface PatchDocument {
      * means the layer was read in part, which Tier C reports.
      */
     readonly limit: WalkLimit;
+    /**
+     * True when the layer reached at least one node twice, which is what a YAML
+     * alias does and what nothing else does. Tier C reports it, because a reader
+     * of the file sees one row where the loader sees two.
+     */
+    readonly aliased: boolean;
 }
-/** Nodes one patch layer may be walked through before the walk gives up. */
+/**
+ * The two ceilings that make reading a patch layer terminate.
+ *
+ * They apply to {@link expandAliases}, and through it to everything downstream:
+ * the walk runs over the tree the expansion produced, which holds at most
+ * `MAX_WALK_NODES` nodes nested at most `MAX_WALK_DEPTH` deep, so the walk needs
+ * no ceiling of its own.
+ */
 export declare const MAX_WALK_NODES = 200000;
-/** Nesting one patch layer may reach before the walk gives up. */
+/** Nesting one patch layer may reach before the reader gives up. */
 export declare const MAX_WALK_DEPTH = 200;
 /** Thrown when the patch file cannot be parsed as an entry list. */
 export declare class PatchParseError extends Error {

package/lib/types/files.d.ts

@@ -10,6 +10,16 @@
  * @returns true when the file should be parsed.
  */
 export declare function isSourceFile(path: string): boolean;
+/**
+ * Whether a path is C-family source a native build would compile.
+ *
+ * Used to answer one question about a package that ships a `binding.gyp`: is
+ * there anything in it to build. A gyp with no compilable source is a build
+ * declaration whose only effect is that a build runs.
+ * @param path - package-relative POSIX path.
+ * @returns true when the file is C-family source or a header.
+ */
+export declare function isNativeSource(path: string): boolean;
 /**
  * Whether a path is markdown that can reach the model verbatim.
  *

package/lib/types/knowledge.d.ts

@@ -121,12 +121,11 @@ export interface LifecycleSignal {
  * Command shapes that make an install lifecycle script the attack rather than
  * the build.
  *
- * The head-to-head measurement on 6,420 malicious and 7,288 benign npm packages
- * (ASE 2026) puts 72.21 % of malicious packages on a lifecycle hook and 21.2 %
- * with the whole attack inside `package.json` scripts — no shipped module at
- * all. That second number is what this table is for: it is the case where the
- * command line itself fetches, decodes, or evaluates, and there is nothing else
- * to read.
+ * The case this table is for is the one where the command line itself fetches,
+ * decodes, or evaluates: the whole attack sits in `package.json` and there is
+ * no shipped module to read. A lifecycle hook alone does not distinguish that
+ * from a build, which is why the hook is a category at `medium` and only the
+ * command raises it.
  *
  * Each pattern is chosen against the measured false-positive side rather than
  * against the idea of a build script. The five packages in the pinned corpus
@@ -135,6 +134,36 @@ export interface LifecycleSignal {
  * that shape is deliberately not a signal here.
  */
 export declare const LIFECYCLE_SIGNALS: readonly LifecycleSignal[];
+/**
+ * Every lifecycle signal a command line matches.
+ *
+ * One entry point rather than the filter written out twice, because the table
+ * now grades two different things — a `package.json` lifecycle command (A1) and
+ * a `binding.gyp` build step (A24) — and a rule added to it has to reach both.
+ * @param command - the command line, or the text that holds one.
+ * @returns the matching signals, in table order.
+ */
+export declare function matchingLifecycleSignals(command: string): LifecycleSignal[];
+/**
+ * The file `node-gyp` reads, at the package root and nowhere else.
+ *
+ * npm and pnpm treat its presence as a declaration: a package that ships one
+ * and declares no `install` or `preinstall` script gets `node-gyp rebuild` as
+ * its install command. That default appears in no field of `package.json`.
+ */
+export declare const NATIVE_BUILD_FILE = "binding.gyp";
+/**
+ * GYP keys that carry a command line rather than a list of sources to compile.
+ *
+ * `actions` and `rules` run a program during the build; `postbuilds` runs one
+ * after it. A target that only lists `sources`, `include_dirs` and `libraries`
+ * compiles code the package shipped and runs nothing else.
+ *
+ * Matched against the whole file, so a block nested inside a `conditions` arm
+ * counts the same as a top-level one — which is the point, because a condition
+ * is where a build step goes to be read past.
+ */
+export declare const GYP_COMMAND_KEYS: RegExp;
 /** Entry fields the loader never interpolates: a `!!js` node here is inert data. */
 export declare const STATIC_ENTRY_FIELDS: readonly string[];
 /**

package/lib/types/source.d.ts

@@ -26,11 +26,20 @@ export declare const MAX_FILE_BYTES: number;
 export declare const MAX_TOTAL_BYTES: number;
 /** Largest number of files the analyzer will consider. */
 export declare const MAX_ENTRIES = 10000;
+/**
+ * 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;
 /** The resource ceilings one read runs under. */
 export interface ReadLimits {
     readonly maxFileBytes: number;
     readonly maxTotalBytes: number;
     readonly maxEntries: number;
+    /** Decompressed tar bytes one tarball may produce before the read is abandoned. */
+    readonly maxStreamBytes: number;
 }
 /** The shipping ceilings. Tests substitute smaller ones to exercise each cap. */
 export declare const DEFAULT_LIMITS: ReadLimits;
@@ -58,13 +67,6 @@ export interface PluginSource {
     /** 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-inspector",
-  "version": "0.3.0",
+  "version": "0.5.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",