dsh-plugin-inspector 0.1.0

package/lib/model.js

@@ -0,0 +1,55 @@
+/**
+ * The report vocabulary: what a finding is, how findings rank, and what the
+ * complete inspection document looks like.
+ *
+ * The document separates `facts` from `findings` deliberately. Facts carry no
+ * severity and answer "what does this plugin do"; findings carry severity and
+ * answer "what warrants a decision". A well-behaved plugin has a full facts
+ * section and an empty findings section — emitting `dsh.bundle` as a finding
+ * would fire on every legitimate plugin and train users to ignore the tool.
+ * @module dsh-plugin-inspector/model
+ */
+/** Severity ordering, ascending. Used for `--fail-on` comparison and ranking. */
+export const SEVERITY_RANK = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+};
+/** Every severity, most severe first — the order the human report prints in. */
+export const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+/**
+ * Order findings for display: most severe first, then by tier (A before B
+ * before C, since A carries verdicts), then by check id, then by evidence
+ * location. Total and deterministic, so two runs diff cleanly.
+ * @param a - left finding.
+ * @param b - right finding.
+ * @returns negative when `a` sorts first.
+ */
+export function compareFindings(a, b) {
+    const bySeverity = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (bySeverity !== 0)
+        return bySeverity;
+    const byTier = a.tier.localeCompare(b.tier);
+    if (byTier !== 0)
+        return byTier;
+    const byCheck = a.checkId.localeCompare(b.checkId, 'en', { numeric: true });
+    if (byCheck !== 0)
+        return byCheck;
+    const byFile = a.evidence.file.localeCompare(b.evidence.file);
+    if (byFile !== 0)
+        return byFile;
+    return (a.evidence.path ?? '').localeCompare(b.evidence.path ?? '');
+}
+/**
+ * Count findings per severity, including zeroes, so the JSON summary has a
+ * fixed key set that consumers can rely on.
+ * @param findings - the findings to tally.
+ * @returns one count per severity.
+ */
+export function summarize(findings) {
+    const summary = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const finding of findings)
+        summary[finding.severity] += 1;
+    return summary;
+}

package/lib/publish.js

@@ -0,0 +1,208 @@
+/**
+ * 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
+ */
+/** Files npm publishes at the package root regardless of `files` or ignore rules. */
+const ALWAYS_PUBLISHED = /^(?:package\.json|npm-shrinkwrap\.json|(?:readme|licen[cs]e|changelog|notice)(?:\.[^/]*)?)$/i;
+/**
+ * Patterns npm refuses to publish whatever the manifest says. Transcribed from
+ * `npm-packlist`'s default rule list; the lockfiles and dotfiles are the ones
+ * that actually show up in a plugin checkout.
+ */
+const NEVER_PUBLISHED = [
+    '**/.git/**', '**/.git', '**/.svn/**', '**/.hg/**', '**/CVS/**',
+    '**/node_modules/**', '**/node_modules',
+    '**/.npmrc', '**/.DS_Store', '**/._*', '**/*.orig', '**/.*.swp',
+    'npm-debug.log', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+    '.lock-wscript', 'build/config.gypi', '.npmignore', '.gitignore',
+];
+/**
+ * Match one glob segment list against one path segment list. Segment-wise with
+ * a memo rather than a compiled regular expression: `files` comes from an
+ * untrusted manifest, and a memoised walk cannot be made to backtrack.
+ * @param pattern - the pattern's segments.
+ * @param path - the path's segments.
+ * @returns true when the pattern matches the whole path.
+ */
+function matchSegments(pattern, path) {
+    const seen = new Set();
+    const step = (p, s) => {
+        const key = p * (path.length + 1) + s;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        if (p === pattern.length)
+            return s === path.length;
+        if (pattern[p] === '**') {
+            for (let index = s; index <= path.length; index += 1) {
+                if (step(p + 1, index))
+                    return true;
+            }
+            return false;
+        }
+        if (s === path.length)
+            return false;
+        if (!matchSegment(pattern[p] ?? '', path[s] ?? ''))
+            return false;
+        return step(p + 1, s + 1);
+    };
+    return step(0, 0);
+}
+/**
+ * Match one glob segment, where `*` stops at a separator and `?` takes one
+ * character.
+ * @param pattern - the pattern segment.
+ * @param name - the path segment.
+ * @returns true when they match.
+ */
+function matchSegment(pattern, name) {
+    const source = [...pattern].map((character) => {
+        if (character === '*')
+            return '[^/]*';
+        if (character === '?')
+            return '[^/]';
+        return character.replace(/[.*+?^${}()|[\]\\]/, '\\$&');
+    }).join('');
+    return new RegExp(`^${source}$`).test(name);
+}
+/**
+ * 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 function globMatch(pattern, path) {
+    return matchSegments(pattern.split('/'), path.split('/'));
+}
+/**
+ * Strip the leading `./` or `/` npm accepts on a `files` entry, both of which
+ * mean "from the package root".
+ * @param pattern - the raw manifest entry.
+ * @returns the root-relative pattern.
+ */
+function normalizePattern(pattern) {
+    return pattern.replace(/^\.?\//, '').replace(/\/+$/, '');
+}
+/**
+ * Whether one `files` entry covers a path. npm treats a bare directory name as
+ * that whole subtree, so `"lib"` publishes everything under `lib/`.
+ * @param pattern - a normalised `files` entry.
+ * @param path - package-relative POSIX path.
+ * @returns true when the entry publishes the path.
+ */
+function allowlistCovers(pattern, path) {
+    if (pattern === '')
+        return false;
+    if (globMatch(pattern, path))
+        return true;
+    if (path.startsWith(`${pattern}/`))
+        return true;
+    return globMatch(`${pattern}/**`, path);
+}
+/**
+ * Parse ignore-file text into rules, using git's syntax: `#` comments, `!`
+ * negation, a trailing `/` for directories only, and anchoring to the root as
+ * soon as the pattern contains an interior separator.
+ * @param text - the file's content, or `null` when there is no such file.
+ * @returns the rules in declaration order.
+ */
+function parseIgnore(text) {
+    const rules = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\r$/, '').trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const negated = line.startsWith('!');
+        const body = negated ? line.slice(1) : line;
+        const directoryOnly = body.endsWith('/');
+        const trimmed = body.replace(/\/+$/, '');
+        const anchored = trimmed.startsWith('/') || trimmed.includes('/');
+        rules.push({ negated, directoryOnly, anchored, pattern: trimmed.replace(/^\//, '') });
+    }
+    return rules;
+}
+/**
+ * Whether an ignore rule matches a path or any directory above it, which is how
+ * git decides that `coverage/` hides `coverage/tmp/x.json`.
+ * @param rule - the rule.
+ * @param path - package-relative POSIX path.
+ * @returns true when the rule applies.
+ */
+function ignoreMatches(rule, path) {
+    const segments = path.split('/');
+    for (let end = 1; end <= segments.length; end += 1) {
+        const prefix = segments.slice(0, end).join('/');
+        // A directory-only rule cannot match the file itself, only a parent of it.
+        if (rule.directoryOnly && end === segments.length)
+            continue;
+        if (rule.anchored) {
+            if (globMatch(rule.pattern, prefix))
+                return true;
+            continue;
+        }
+        if (globMatch(rule.pattern, segments[end - 1] ?? ''))
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 function publishSet(inputs) {
+    const never = NEVER_PUBLISHED;
+    const main = inputs.main === null ? null : normalizePattern(inputs.main);
+    if (inputs.files !== null) {
+        const allow = inputs.files.filter(entry => !entry.startsWith('!')).map(normalizePattern);
+        const deny = inputs.files.filter(entry => entry.startsWith('!')).map(entry => normalizePattern(entry.slice(1)));
+        return {
+            basis: 'files-allowlist',
+            includes: (path) => {
+                if (never.some(pattern => globMatch(pattern, path)))
+                    return false;
+                if (ALWAYS_PUBLISHED.test(path))
+                    return true;
+                if (main !== null && path === main)
+                    return true;
+                if (deny.some(pattern => allowlistCovers(pattern, path)))
+                    return false;
+                return allow.some(pattern => allowlistCovers(pattern, path));
+            },
+        };
+    }
+    const text = inputs.npmignore ?? inputs.gitignore;
+    const rules = text === null ? [] : parseIgnore(text);
+    return {
+        basis: 'ignore-rules',
+        includes: (path) => {
+            if (never.some(pattern => globMatch(pattern, path)))
+                return false;
+            if (ALWAYS_PUBLISHED.test(path))
+                return true;
+            if (main !== null && path === main)
+                return true;
+            let ignored = false;
+            for (const rule of rules) {
+                if (!ignoreMatches(rule, path))
+                    continue;
+                ignored = !rule.negated;
+            }
+            return !ignored;
+        },
+    };
+}
+/** Every file is published: a tarball is already the publish set. */
+export const TARBALL_PUBLISH_SET = { basis: 'tarball', includes: () => true };

package/lib/report.js

@@ -0,0 +1,182 @@
+/**
+ * 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 { SEVERITIES } from "./model.js";
+/** ANSI colour per severity, and the reset. */
+const COLOR = {
+    critical: '\u001b[1;31m',
+    high: '\u001b[31m',
+    medium: '\u001b[33m',
+    low: '\u001b[36m',
+    dim: '\u001b[2m',
+    bold: '\u001b[1m',
+    reset: '\u001b[0m',
+};
+/** How the human report labels each severity. */
+const LABEL = {
+    critical: 'CRITICAL',
+    high: 'HIGH    ',
+    medium: 'MEDIUM  ',
+    low: 'LOW     ',
+};
+/**
+ * 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 function renderJson(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+/**
+ * Render one finding as an indented block.
+ * @param finding - the finding.
+ * @param paint - the colouring function.
+ * @returns the rendered lines.
+ */
+function renderFinding(finding, paint) {
+    const where = finding.evidence.path === undefined
+        ? finding.evidence.file
+        : `${finding.evidence.file}:${finding.evidence.path}`;
+    const lines = [
+        `${paint(finding.severity, LABEL[finding.severity])}  ${paint('bold', finding.title)}`,
+        `          ${paint('dim', `${finding.checkId} ${finding.name} · tier ${finding.tier} · confidence ${finding.confidence}`)}`,
+        `          ${paint('dim', where)}`,
+    ];
+    if (finding.evidence.snippet !== undefined)
+        lines.push(`          ${paint('dim', `> ${finding.evidence.snippet}`)}`);
+    for (const line of wrap(finding.detail, 88))
+        lines.push(`          ${line}`);
+    if (finding.bypass !== null)
+        lines.push(`          ${paint('dim', `bypass: ${finding.bypass}`)}`);
+    lines.push('');
+    return lines;
+}
+/**
+ * Wrap prose to a column without breaking words.
+ * @param text - the prose.
+ * @param width - the maximum line length.
+ * @returns the wrapped lines.
+ */
+function wrap(text, width) {
+    const lines = [];
+    let current = '';
+    for (const word of text.split(/\s+/)) {
+        if (current === '') {
+            current = word;
+        }
+        else if (current.length + 1 + word.length <= width) {
+            current = `${current} ${word}`;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current !== '')
+        lines.push(current);
+    return lines;
+}
+/**
+ * Summarise the mounted layer's `!!js` inventory, dropping the classes that
+ * scored nothing so the line stays readable.
+ * @param tally - one count per classification.
+ * @returns the summary line.
+ */
+function describeExpressions(tally) {
+    const present = Object.entries(tally).filter(([, count]) => count > 0);
+    if (present.length === 0)
+        return 'none';
+    return present.map(([name, count]) => `${count} ${name}`).join(', ');
+}
+/**
+ * Say which files were analysed and, in directory mode, how many were left out
+ * because npm would not publish them.
+ * @param facts - the report's facts.
+ * @returns the description.
+ */
+function describeFileSet(facts) {
+    if (facts.publishBasis === 'tarball')
+        return 'the tarball as published';
+    const basis = facts.publishBasis === 'files-allowlist'
+        ? 'the package.json `files` allowlist'
+        : 'npm defaults over .npmignore/.gitignore';
+    return `working tree narrowed to what npm would publish, by ${basis}`
+        + ` (${facts.unpublishedFiles} unpublished file(s) not read)`;
+}
+/**
+ * Render the "what does this plugin do" section, which is printed whether or
+ * not there are findings.
+ * @param report - the report.
+ * @param paint - the colouring function.
+ * @returns the rendered lines.
+ */
+function renderFacts(report, paint) {
+    const { facts } = report;
+    const rows = [
+        ['package', `${facts.packageName}@${facts.packageVersion}${facts.license === null ? '' : ` (${facts.license})`}`],
+        ['read from', `${report.target.kind} ${report.target.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'],
+        ['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'
+                : facts.insertedRows.map(row => `${row.id}${row.name === undefined ? '' : ` → ${row.name}`}`).join('\n                ')],
+        ['rows modified', facts.targetedRows.length === 0 ? 'none' : facts.targetedRows.join(', ')],
+        ['!!js in layer', describeExpressions(facts.jsExpressions)],
+        ['other layers', facts.unmountedPatchFiles.length === 0
+                ? 'none'
+                : `${facts.unmountedPatchFiles.join(', ')} (shipped, mounted by no manifest key)`],
+        ['installs', facts.binNames.length === 0 ? 'no commands' : facts.binNames.join(', ')],
+        ['dependencies', facts.dependencies.length === 0 ? 'none' : facts.dependencies.join(', ')],
+        ['model-visible', facts.modelVisibleFiles.length === 0 ? 'none' : facts.modelVisibleFiles.join(', ')],
+        ['analysed', `${facts.filesRead} files, ${facts.sourceFilesParsed} parsed as source, ${facts.bytesRead} bytes`],
+        ['file set', describeFileSet(facts)],
+        ['checked against', `DeepSeek Harness ${report.tool.harnessReference}`],
+    ];
+    const lines = [paint('bold', 'What this plugin declares'), ''];
+    for (const [key, value] of rows)
+        lines.push(`  ${paint('dim', key.padEnd(16))}${value}`);
+    lines.push('');
+    return lines;
+}
+/**
+ * Render the human report.
+ * @param report - the report.
+ * @param color - whether to emit ANSI colour.
+ * @returns the rendered text, ending in a newline.
+ */
+export function renderHuman(report, color) {
+    const paint = (code, text) => color ? `${COLOR[code] ?? ''}${text}${COLOR.reset}` : text;
+    const lines = ['', ...renderFacts(report, paint)];
+    if (report.findings.length > 0) {
+        const counts = SEVERITIES
+            .filter(severity => report.summary[severity] > 0)
+            .map(severity => paint(severity, `${report.summary[severity]} ${severity}`))
+            .join(', ');
+        lines.push(paint('bold', `Findings (${counts})`), '');
+        for (const finding of report.findings)
+            lines.push(...renderFinding(finding, paint));
+    }
+    if (!report.analysis.negativesReliable) {
+        lines.push(paint('medium', 'Analysis is degraded.'), ...wrap(`Tier C fired (${report.analysis.degradedBy.join(', ')}), so parts of this package could not be read the `
+            + 'way capability detection needs to read them. The findings above are real — the tool saw what it saw — '
+            + 'but the ABSENCE of a capability finding means nothing here. This report does not say the package is clean.', 88).map(line => `  ${line}`), '');
+    }
+    else if (report.findings.length === 0) {
+        lines.push(paint('bold', 'No findings.'), ...wrap('Nothing was found at any severity in the parts that could be read. That is not a statement that the '
+            + 'package is safe: this tool reads one version of one package. It does not read transitive dependencies, '
+            + 'it cannot see code fetched at runtime, and a later version that gains a dsh.bundle declaration is '
+            + 'mounted automatically by the next `dsh plugin update` with no notice.', 88).map(line => `  ${line}`), '');
+    }
+    return `${lines.join('\n')}\n`;
+}