dsh-plugin-inspector 0.1.0 → 0.2.1

package/lib/registry.js

@@ -0,0 +1,261 @@
+/**
+ * Fetching a published package from an npm registry, and proving the bytes are
+ * the ones the registry vouched for.
+ *
+ * This is the one module in the tool that opens a socket, and it exists behind
+ * one explicit flag. A network fetch is not execution — nothing here installs,
+ * unpacks to disk, or runs a lifecycle script — but it is a side effect the
+ * tool's other two modes do not have, so it is never reached implicitly: a
+ * directory or tarball scan cannot get here, because neither imports this
+ * module.
+ *
+ * The order of operations is the security property. The packument is read
+ * first, which is ~3 KB and already answers `hasInstallScript`, the install
+ * lifecycle scripts, and whether the package declares `dsh.bundle` — a
+ * pre-check that needs no tarball at all. Only then is the tarball fetched, and
+ * its `dist.integrity` hash is verified **before** any byte of it reaches the
+ * tar parser. A hash mismatch is a refusal, not a warning: the whole point of
+ * the mode is that the analysed bytes are the published bytes.
+ * @module dsh-plugin-inspector/registry
+ */
+import { createHash } from 'node:crypto';
+import { INSTALL_LIFECYCLE_SCRIPTS } from "./knowledge.js";
+import { MAX_TOTAL_BYTES } from "./source.js";
+/** The public npm registry, used when no other is named. */
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/** Largest packument the tool will read. A version document is a few kilobytes. */
+export const MAX_METADATA_BYTES = 4 * 1024 * 1024;
+/**
+ * Largest compressed tarball the tool will download. The decompressed stream is
+ * capped separately, and lower, by the tar reader.
+ */
+export const MAX_TARBALL_BYTES = MAX_TOTAL_BYTES;
+/** Hash algorithms accepted in a Subresource Integrity string, weakest last. */
+const SRI_ALGORITHMS = new Set(['sha512', 'sha384', 'sha256']);
+/**
+ * npm package names, as the registry accepts them. Validated because the name
+ * is interpolated into a URL: `../` in a package name is a request for a
+ * different endpoint, and a `http://…` "name" is a request to a different host.
+ */
+const PACKAGE_NAME = /^(?:@[a-z0-9~][a-z0-9-._~]*\/)?[a-z0-9~][a-z0-9-._~]*$/;
+/** Versions and dist-tags, as they may appear after the `@` in a spec. */
+const VERSION_OR_TAG = /^[A-Za-z0-9][A-Za-z0-9-._+]*$/;
+/** Thrown when a package cannot be resolved, fetched, or verified. */
+export class RegistryError extends Error {
+}
+/**
+ * Split a `<name>` or `<name>@<version>` argument.
+ *
+ * The `@` that starts a scope is not a separator, so `@scope/name` has no
+ * version and `@scope/name@1.2.3` has one.
+ * @param spec - the argument as typed.
+ * @returns the package name and the requested version, if any.
+ * @throws RegistryError when the name or version is not one the registry accepts.
+ */
+export function parseSpec(spec) {
+    const separator = spec.lastIndexOf('@');
+    const split = separator > 0;
+    const name = split ? spec.slice(0, separator) : spec;
+    const version = split ? spec.slice(separator + 1) : null;
+    if (!PACKAGE_NAME.test(name))
+        throw new RegistryError(`not an npm package name: ${spec}`);
+    if (version !== null && !VERSION_OR_TAG.test(version)) {
+        throw new RegistryError(`not a version or dist-tag: ${version}`);
+    }
+    return { name, version };
+}
+/**
+ * Read one response body under a ceiling, without materialising more than the
+ * ceiling allows. A registry that streams forever is a hang, and a hang in a
+ * gate is a denial of service.
+ * @param response - the fetch response.
+ * @param limit - the ceiling in bytes.
+ * @param what - what is being read, for the error message.
+ * @returns the body.
+ * @throws RegistryError when the body passes the ceiling.
+ */
+async function readCapped(response, limit, what) {
+    const body = response.body;
+    if (body === null)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of body) {
+        total += chunk.byteLength;
+        if (total > limit)
+            throw new RegistryError(`${what} is larger than ${limit} bytes`);
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * GET a URL, failing loud on anything but a 2xx.
+ * @param url - the absolute URL.
+ * @param accept - the Accept header.
+ * @param options - registry options carrying the fetch implementation.
+ * @returns the response.
+ * @throws RegistryError on a transport failure or a non-2xx status.
+ */
+async function get(url, accept, options) {
+    const call = options.fetch ?? globalThis.fetch;
+    let response;
+    try {
+        response = await call(url, { headers: { accept, 'user-agent': 'dsh-plugin-inspector' } });
+    }
+    catch (error) {
+        throw new RegistryError(`cannot reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok)
+        throw new RegistryError(`${url} returned HTTP ${response.status}`);
+    return response;
+}
+/**
+ * Read the packument for one version, which is the pre-check.
+ * @param spec - the package name and requested version.
+ * @param options - where to fetch from.
+ * @returns everything the metadata says, including the tarball URL and its hash.
+ * @throws RegistryError when the package or version does not resolve, or when
+ * the document does not carry a tarball URL on the registry's own origin.
+ */
+export async function resolvePackage(spec, options = {}) {
+    const registry = (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, '');
+    const url = `${registry}/${spec.name}/${encodeURIComponent(spec.version ?? 'latest')}`;
+    const response = await get(url, 'application/json', options);
+    const body = await readCapped(response, MAX_METADATA_BYTES, 'package metadata');
+    let document;
+    try {
+        document = JSON.parse(body.toString('utf8'));
+    }
+    catch (error) {
+        throw new RegistryError(`${url} did not return JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const record = asRecord(document);
+    const dist = asRecord(record.dist);
+    const tarball = typeof dist.tarball === 'string' ? dist.tarball : null;
+    if (tarball === null)
+        throw new RegistryError(`${url} carries no dist.tarball`);
+    assertSameOrigin(tarball, registry);
+    const scripts = asRecord(record.scripts);
+    const dsh = asRecord(record.dsh);
+    const bundle = asRecord(dsh.bundle);
+    return {
+        name: typeof record.name === 'string' ? record.name : spec.name,
+        version: typeof record.version === 'string' ? record.version : (spec.version ?? 'latest'),
+        tarball,
+        integrity: typeof dist.integrity === 'string' ? dist.integrity : null,
+        shasum: typeof dist.shasum === 'string' ? dist.shasum : null,
+        hasInstallScript: record.hasInstallScript === true,
+        lifecycleScripts: INSTALL_LIFECYCLE_SCRIPTS.filter(name => typeof scripts[name] === 'string'),
+        bundlePatch: typeof bundle.patch === 'string' ? bundle.patch : null,
+        metadataBytes: body.byteLength,
+    };
+}
+/**
+ * Narrow an unknown JSON value to a record, so a hostile document's `dist: 7`
+ * reads as "no fields" rather than throwing somewhere further down.
+ * @param value - the parsed JSON value.
+ * @returns the value as a record, or an empty one.
+ */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Refuse a tarball URL that points somewhere other than the registry that
+ * described it.
+ *
+ * The integrity hash comes from the same document as the URL, so a hostile
+ * registry can always make the two agree — this does not defend against that.
+ * What it does refuse is a single doctored packument on an honest registry
+ * pointing the download at a host of the attacker's choosing, which would make
+ * the tool fetch an arbitrary URL on the user's behalf.
+ * @param tarball - the declared tarball URL.
+ * @param registry - the registry base URL.
+ * @throws RegistryError when the origins differ or the URL is not http(s).
+ */
+function assertSameOrigin(tarball, registry) {
+    let url;
+    let base;
+    try {
+        url = new URL(tarball);
+        base = new URL(registry);
+    }
+    catch {
+        throw new RegistryError(`dist.tarball is not a URL: ${tarball}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new RegistryError(`dist.tarball is not an http(s) URL: ${tarball}`);
+    }
+    if (url.origin !== base.origin) {
+        throw new RegistryError(`dist.tarball ${tarball} is not on the registry's origin ${base.origin}`);
+    }
+}
+/**
+ * Check downloaded bytes against what the registry published.
+ *
+ * `dist.integrity` is preferred and is a real check. `dist.shasum` is SHA-1 and
+ * is accepted only when there is no `integrity` field at all, which happens on
+ * packages published before npm 5; it is recorded in the report as the weaker
+ * check it is. No digest at all is a refusal, because "verified" would then be
+ * a claim the tool cannot make.
+ * @param bytes - the downloaded tarball.
+ * @param resolved - what the packument said about it.
+ * @returns the algorithm and digest that matched.
+ * @throws RegistryError on a mismatch, an unusable digest, or no digest at all.
+ */
+export function verifyIntegrity(bytes, resolved) {
+    if (resolved.integrity !== null) {
+        // An `integrity` field may carry several space-separated digests. One
+        // matching digest in a recognised algorithm is the check; an unrecognised
+        // algorithm is not silently ignored, it just is not a match.
+        for (const entry of resolved.integrity.trim().split(/\s+/)) {
+            const dash = entry.indexOf('-');
+            const algorithm = dash < 0 ? '' : entry.slice(0, dash);
+            if (!SRI_ALGORITHMS.has(algorithm))
+                continue;
+            const expected = entry.slice(dash + 1);
+            const actual = digest(algorithm, bytes, 'base64');
+            if (actual !== expected) {
+                throw new RegistryError(`integrity check failed for ${resolved.name}@${resolved.version}: `
+                    + `registry published ${algorithm}-${expected}, downloaded bytes are ${algorithm}-${actual}`);
+            }
+            return { bytes, algorithm, digest: entry };
+        }
+        throw new RegistryError(`no usable digest in dist.integrity for ${resolved.name}@${resolved.version}: ${resolved.integrity}`);
+    }
+    if (resolved.shasum !== null) {
+        const actual = digest('sha1', bytes, 'hex');
+        if (actual !== resolved.shasum) {
+            throw new RegistryError(`shasum check failed for ${resolved.name}@${resolved.version}: `
+                + `registry published sha1-${resolved.shasum}, downloaded bytes are sha1-${actual}`);
+        }
+        return { bytes, algorithm: 'sha1', digest: `sha1-${actual}` };
+    }
+    throw new RegistryError(`${resolved.name}@${resolved.version} carries neither dist.integrity nor dist.shasum, so the download cannot be verified`);
+}
+/**
+ * Hash a buffer.
+ * @param algorithm - the hash algorithm.
+ * @param bytes - the input.
+ * @param encoding - how to render the digest.
+ * @returns the digest.
+ */
+function digest(algorithm, bytes, encoding) {
+    return createHash(algorithm).update(bytes).digest(encoding);
+}
+/**
+ * Download a resolved package's tarball and verify it before returning it.
+ *
+ * Nothing parses the bytes on the way in — they are counted against a ceiling
+ * and hashed, and a failed hash throws before any caller can see them.
+ * @param resolved - the packument reading for the version to fetch.
+ * @param options - where to fetch from.
+ * @returns the verified tarball, in memory.
+ * @throws RegistryError on a transport failure, an oversized body, or a hash mismatch.
+ */
+export async function fetchVerifiedTarball(resolved, options = {}) {
+    const response = await get(resolved.tarball, 'application/octet-stream', options);
+    const bytes = await readCapped(response, MAX_TARBALL_BYTES, `tarball ${resolved.tarball}`);
+    return verifyIntegrity(bytes, resolved);
+}

package/lib/report.js

@@ -43,14 +43,16 @@ export function renderJson(report) {
  * @returns the rendered lines.
  */
 function renderFinding(finding, paint) {
-    const where = finding.evidence.path === undefined
-        ? finding.evidence.file
-        : `${finding.evidence.file}:${finding.evidence.path}`;
+    const count = finding.occurrences > 1 ? ` ${paint('dim', `(×${finding.occurrences})`)}` : '';
     const lines = [
-        `${paint(finding.severity, LABEL[finding.severity])}  ${paint('bold', finding.title)}`,
+        `${paint(finding.severity, LABEL[finding.severity])}  ${paint('bold', finding.title)}${count}`,
         `          ${paint('dim', `${finding.checkId} ${finding.name} · tier ${finding.tier} · confidence ${finding.confidence}`)}`,
-        `          ${paint('dim', where)}`,
     ];
+    for (const example of finding.examples)
+        lines.push(`          ${paint('dim', locate(example))}`);
+    if (finding.occurrences > finding.examples.length) {
+        lines.push(`          ${paint('dim', `… and ${finding.occurrences - finding.examples.length} more site(s)`)}`);
+    }
     if (finding.evidence.snippet !== undefined)
         lines.push(`          ${paint('dim', `> ${finding.evidence.snippet}`)}`);
     for (const line of wrap(finding.detail, 88))
@@ -60,6 +62,14 @@ function renderFinding(finding, paint) {
     lines.push('');
     return lines;
 }
+/**
+ * Render one example site as `file:locator`.
+ * @param evidence - the site.
+ * @returns the location.
+ */
+function locate(evidence) {
+    return evidence.path === undefined ? evidence.file : `${evidence.file}:${evidence.path}`;
+}
 /**
  * Wrap prose to a column without breaking words.
  * @param text - the prose.
@@ -121,9 +131,19 @@ function describeFileSet(facts) {
  */
 function renderFacts(report, paint) {
     const { facts } = report;
+    const provenance = report.target.registry;
     const rows = [
         ['package', `${facts.packageName}@${facts.packageVersion}${facts.license === null ? '' : ` (${facts.license})`}`],
         ['read from', `${report.target.kind} ${report.target.path}`],
+        ...provenance === undefined
+            ? []
+            : [
+                ['fetched from', `${provenance.tarball} (${provenance.tarballBytes} bytes, never written to disk)`],
+                ['verified', `${provenance.digest} matched dist.integrity before anything parsed it`],
+                ['install script', provenance.hasInstallScript
+                        ? 'yes — the registry marks this package as running one at install time'
+                        : 'no — the registry does not mark this package as running one'],
+            ],
         ['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'],

package/lib/source.js

@@ -20,7 +20,7 @@
  */
 import { createReadStream, openSync, readdirSync, readFileSync, readSync, closeSync, statSync } from 'node:fs';
 import { join, posix, relative, resolve, sep } from 'node:path';
-import { PassThrough, Transform } from 'node:stream';
+import { PassThrough, Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createGunzip } from 'node:zlib';
 import { Parser } from 'tar';
@@ -249,10 +249,11 @@ function isGzip(file) {
  * `await`, so every one of them is captured here and rethrown on the awaited
  * path — an emitter-thrown `RangeError` that escapes becomes an uncaught
  * exception and a raw stack trace on a user's terminal.
- * @param file - absolute path to the `.tgz`.
+ * @param bytes - the arriving tar stream, gzipped or not.
+ * @param gzipped - whether to inflate before parsing.
  * @param collector - the shared accumulator.
  */
-async function readTarball(file, collector) {
+async function readTarStream(bytes, gzipped, collector) {
     const pending = [];
     let failure = null;
     const parser = new Parser({
@@ -306,8 +307,8 @@ async function readTarball(file, collector) {
             }));
         },
     });
-    const inflate = isGzip(file) ? createGunzip() : new PassThrough();
-    await pipeline(createReadStream(file), inflate, byteCeiling(MAX_STREAM_BYTES), parser);
+    const inflate = gzipped ? createGunzip() : new PassThrough();
+    await pipeline(bytes, inflate, byteCeiling(MAX_STREAM_BYTES), parser);
     await Promise.all(pending);
     if (failure !== null)
         throw failure;
@@ -384,17 +385,58 @@ export async function loadSource(target, limits = DEFAULT_LIMITS) {
     }
     else {
         published = TARBALL_PUBLISH_SET;
-        try {
-            await readTarball(path, collector);
-        }
-        catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            throw new SourceError(`cannot read tarball ${path}: ${detail}`);
-        }
-        if (collector.entries === 0) {
-            throw new SourceError(`${path} holds no tar entries — this is not a readable npm tarball`);
-        }
+        await decodeTar(createReadStream(path), isGzip(path), collector, path);
+    }
+    return finish(kind, path, collector, published);
+}
+/**
+ * Decode an npm tarball held in memory, for bytes that never touched the disk.
+ *
+ * The only caller is the `--from-npm` path, which fetches a tarball and
+ * verifies its `dist.integrity` hash before handing the buffer here. Reading it
+ * goes through the same `Parser` as the on-disk path, so the "no extraction,
+ * ever" property covers both.
+ * @param bytes - the complete tarball, gzipped or not.
+ * @param label - what to report as the target path, e.g. `npm:pkg@1.2.3`.
+ * @param limits - resource ceilings; defaults to {@link DEFAULT_LIMITS}.
+ * @returns the decoded package.
+ * @throws SourceError when the buffer is not a readable npm tarball.
+ */
+export async function loadTarballBuffer(bytes, label, limits = DEFAULT_LIMITS) {
+    const collector = { files: new Map(), skipped: [], limits, bytes: 0, entries: 0, unpublished: 0 };
+    const gzipped = bytes[0] === 0x1f && bytes[1] === 0x8b;
+    await decodeTar(Readable.from(bytes), gzipped, collector, label);
+    return finish('registry', label, collector, TARBALL_PUBLISH_SET);
+}
+/**
+ * Run the tar pipeline and turn every failure into a `SourceError` naming the
+ * target, so a caller can tell "this is not a tarball" from a crash.
+ * @param bytes - the arriving tar stream.
+ * @param gzipped - whether to inflate before parsing.
+ * @param collector - the shared accumulator.
+ * @param label - the target as it should appear in an error message.
+ */
+async function decodeTar(bytes, gzipped, collector, label) {
+    try {
+        await readTarStream(bytes, gzipped, collector);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new SourceError(`cannot read tarball ${label}: ${detail}`);
     }
+    if (collector.entries === 0) {
+        throw new SourceError(`${label} holds no tar entries — this is not a readable npm tarball`);
+    }
+}
+/**
+ * Assemble the decoded package, refusing a target that holds no manifest.
+ * @param kind - where the bytes came from.
+ * @param path - the target as it should appear in the report.
+ * @param collector - the shared accumulator.
+ * @param published - the publish-set membership test that was used.
+ * @returns the decoded package.
+ */
+function finish(kind, path, collector, published) {
     if (!collector.files.has('package.json')) {
         throw new SourceError(`no readable package.json in ${path} — this is not an npm package`);
     }

package/lib/types/cli.d.ts

@@ -15,13 +15,25 @@ export declare const EXIT: {
     readonly findings: 1;
     readonly unanalysable: 2;
 };
-/** One parsed command line. */
-interface Options {
-    readonly target: string;
+/** Options that do not depend on which target form was given. */
+interface CommonOptions {
+    /** Registry base URL, used only in `--from-npm` mode. */
+    readonly registry: string;
     readonly json: boolean;
     readonly failOn: Severity | 'none';
     readonly color: boolean;
 }
+/**
+ * One parsed command line. Exactly one of the two target forms is present:
+ * a local path, or a registry spec that opts this invocation into fetching.
+ */
+type Options = CommonOptions & ({
+    readonly target: string;
+    readonly fromNpm: null;
+} | {
+    readonly target: null;
+    readonly fromNpm: string;
+});
 /** Raised for a malformed command line; the message is printed and the tool exits 2. */
 export declare class UsageError extends Error {
 }

package/lib/types/files.d.ts

@@ -13,7 +13,7 @@ export declare function isSourceFile(path: string): boolean;
 /**
  * Whether a path is markdown that can reach the model verbatim.
  *
- * The reach is conditional and PLAN.md §6.1 says so: a `SKILL.md` inside an npm
+ * The reach is conditional: a `SKILL.md` inside an npm
  * package is only discovered when the plugin registers it through
  * `ctx.skills`, when a patch row redirects a skill root into the package, or
  * when something copies it into the user's workspace. This predicate answers

package/lib/types/index.d.ts

@@ -11,13 +11,15 @@
  * The ceiling is triage, not containment. See `README.md` §Limitations.
  * @module dsh-plugin-inspector
  */
-export { exceedsThreshold, inspect, TOOL_NAME, TOOL_VERSION } from './inspect.ts';
+export { analyze, exceedsThreshold, inspect, TOOL_NAME, TOOL_VERSION } from './inspect.ts';
+export { inspectFromNpm, precheck } from './npm.ts';
+export { DEFAULT_REGISTRY, fetchVerifiedTarball, parseSpec, RegistryError, resolvePackage, verifyIntegrity, type PackageSpec, type RegistryOptions, type ResolvedPackage, type VerifiedTarball, } from './registry.ts';
 export { renderHuman, renderJson } from './report.ts';
 export { classifyExpression, isJsExpr, parsePatchDocument, patchSchema, PatchParseError, type ExpressionClass, type ExpressionSite, type ExpressionSlot, type InsertedRow, type JsExprNode, type OverridePatch, type PatchDocument, } from './cordis-yaml.ts';
 export { declaredPackages, ManifestError, parseManifest, type PackageManifest } from './manifest.ts';
-export { DEFAULT_LIMITS, loadSource, SourceError, type PluginSource, type ReadLimits } from './source.ts';
+export { DEFAULT_LIMITS, loadSource, loadTarballBuffer, SourceError, type PluginSource, type ReadLimits, type SourceKind, } from './source.ts';
 export { globMatch, publishSet, type PublishBasis, type PublishInputs, type PublishSet } from './publish.ts';
 export { INJECTION_RULES, scanInjection, type InjectionMatch, type InjectionRule } from './injection.ts';
-export { compareFindings, SEVERITIES, SEVERITY_RANK, summarize, type AnalysisIntegrity, type Confidence, type Evidence, type Facts, type Finding, type Report, type Severity, type Tier, } from './model.ts';
+export { aggregateFindings, compareFindings, MAX_EXAMPLES, SEVERITIES, SEVERITY_RANK, summarize, type AnalysisIntegrity, type Confidence, type Evidence, type Facts, type Finding, type RegistryProvenance, type Report, type Severity, type Tier, } from './model.ts';
 export { CORE_ROWS, CORE_ROW_IDS, HARNESS_BUNDLE_PACKAGES, HARNESS_REFERENCE, SEAM_KEYS, SECURITY_ROW_IDS, WATERFALL_EVENTS, type BundleName, type CoreRow, } from './knowledge.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/inspect.d.ts

@@ -9,18 +9,31 @@
  * `cordis-yaml.ts`, and its result is discarded without being called.
  * @module dsh-plugin-inspector/inspect
  */
-import { type Report, type Severity } from './model.ts';
+import { type RegistryProvenance, type Report, type Severity } from './model.ts';
+import { type PluginSource } from './source.ts';
 /** This tool's own version, reported in the JSON document. */
 export declare const TOOL_VERSION = "0.1.0";
 /** This tool's package name, reported in the JSON document. */
 export declare const TOOL_NAME = "dsh-plugin-inspector";
 /**
- * Inspect a plugin package.
+ * Inspect a plugin package on disk.
+ *
+ * Nothing on this path opens a socket: neither this module nor anything it
+ * imports can reach the registry, which is what makes "a directory or tarball
+ * scan never fetches" structural rather than a promise.
  * @param target - a plugin directory, or a `.tgz` / `.tar.gz` npm tarball.
  * @returns the complete report.
  * @throws SourceError or ManifestError when the target cannot be analysed at all.
  */
 export declare function inspect(target: string): Promise<Report>;
+/**
+ * Run every check over an already-decoded package.
+ * @param source - the decoded package.
+ * @param registry - provenance, when the bytes were fetched from a registry.
+ * @returns the complete report.
+ * @throws ManifestError when the manifest cannot be read.
+ */
+export declare function analyze(source: PluginSource, registry?: RegistryProvenance): Report;
 /**
  * Whether a report should fail a CI gate.
  * @param report - the report.

package/lib/types/model.d.ts

@@ -32,7 +32,22 @@ export interface Evidence {
     /** A short verbatim excerpt, truncated and single-lined for display. */
     readonly snippet?: string;
 }
-/** One thing the inspector believes warrants a decision. */
+/**
+ * How many example sites one finding carries. Three is enough to show a
+ * pattern — one file, a second confirming it is not isolated, a third for
+ * spread — and few enough that the report stays readable when a package
+ * imports `node:fs` from ninety files.
+ */
+export declare const MAX_EXAMPLES = 3;
+/**
+ * One thing the inspector believes warrants a decision, in one package.
+ *
+ * A finding is per package, not per syntax site. A package that imports
+ * `node:fs` from eleven files has one B13 finding with `occurrences: 11`, not
+ * eleven findings — the eleventh import warrants no decision the first did not
+ * already warrant, and a report that lists it eleven times buries the one
+ * finding that does.
+ */
 export interface Finding {
     /** Catalogue id from PLAN.md §6, e.g. `A2`. Stable across releases. */
     readonly checkId: string;
@@ -41,11 +56,24 @@ export interface Finding {
     readonly tier: Tier;
     readonly severity: Severity;
     readonly confidence: Confidence;
+    /**
+     * What this finding is about, independent of where it was seen: the module
+     * specifier, the row id, the seam name, the matched rule. Two findings that
+     * share a `checkId` and a `subject` are the same finding observed twice, and
+     * are collapsed into one. Stable across releases, so a gate can allow a
+     * specific `B13`/`node:fs` without allowing every `B13`.
+     */
+    readonly subject: string;
     /** One line naming what was found. */
     readonly title: string;
     /** Why it matters, in terms of what the harness does with the declaration. */
     readonly detail: string;
+    /** The first site the check matched. Always equal to `examples[0]`. */
     readonly evidence: Evidence;
+    /** Up to {@link MAX_EXAMPLES} sites, in the order they were found. */
+    readonly examples: readonly Evidence[];
+    /** How many sites the check matched in this package. At least 1. */
+    readonly occurrences: number;
     /**
      * The one-line evasion for this specific check, or `null` when there is none.
      * Non-null for every Tier B and Tier C check. Carried inside the finding
@@ -119,9 +147,38 @@ export interface AnalysisIntegrity {
     readonly degradedBy: readonly string[];
     readonly filesSkipped: readonly SkippedFile[];
 }
-/** The complete inspection result, and the shape of `--json` output. */
+/**
+ * Where a `--from-npm` target came from and how the bytes were checked.
+ *
+ * Present only in registry mode. Its presence in a report is the record that
+ * this invocation opened a socket, which a directory or tarball scan never
+ * does.
+ */
+export interface RegistryProvenance {
+    /** The spec as the user typed it. */
+    readonly spec: string;
+    /** The registry base URL the packument was read from. */
+    readonly registry: string;
+    readonly resolvedVersion: string;
+    readonly tarball: string;
+    /** The digest that matched, in the registry's own encoding. */
+    readonly digest: string;
+    /** The algorithm that digest was taken with. `sha1` means no `dist.integrity` was published. */
+    readonly algorithm: string;
+    /** The registry's own flag, read before the tarball was fetched. */
+    readonly hasInstallScript: boolean;
+    readonly metadataBytes: number;
+    readonly tarballBytes: number;
+}
+/**
+ * The complete inspection result, and the shape of `--json` output.
+ *
+ * Version 2 is the first release where a finding is per package rather than per
+ * syntax site: every finding gained `subject`, `examples` and `occurrences`,
+ * and `target.kind` gained `registry`.
+ */
 export interface Report {
-    readonly schemaVersion: 1;
+    readonly schemaVersion: 2;
     readonly tool: {
         readonly name: string;
         readonly version: string;
@@ -133,8 +190,10 @@ export interface Report {
         readonly harnessReference: string;
     };
     readonly target: {
-        readonly kind: 'directory' | 'tarball';
+        readonly kind: 'directory' | 'tarball' | 'registry';
         readonly path: string;
+        /** Present only when the bytes were fetched from a registry. */
+        readonly registry?: RegistryProvenance;
     };
     readonly facts: Facts;
     readonly analysis: AnalysisIntegrity;
@@ -142,14 +201,33 @@ export interface Report {
     readonly findings: readonly Finding[];
 }
 /**
- * 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.
+ * Order findings for display: verdicts first, then most severe, then by tier,
+ * then by check id, then by evidence location. Total and deterministic, so two
+ * runs diff cleanly.
+ *
+ * Tier A outranks every Tier B finding whatever their severities, because a
+ * verdict and a capability report answer different questions and the verdict is
+ * the one the reader came for. Within each group severity decides.
  * @param a - left finding.
  * @param b - right finding.
  * @returns negative when `a` sorts first.
  */
 export declare function compareFindings(a: Finding, b: Finding): number;
+/**
+ * Collapse per-site findings into one finding per check per subject.
+ *
+ * This is where the report stops being a list of syntax sites and becomes a
+ * list of decisions. The count and the examples are kept, so nothing a reader
+ * would act on is lost: the number says how widespread it is, the examples say
+ * where to look first, and both live in the finding rather than in a footnote.
+ *
+ * Order is preserved: the first occurrence of each group decides where the
+ * group sits, and `compareFindings` sorts afterwards.
+ * @param findings - findings as the checks emitted them, one per site.
+ * @param maxExamples - how many sites to keep; defaults to {@link MAX_EXAMPLES}.
+ * @returns one finding per `checkId` and `subject`.
+ */
+export declare function aggregateFindings(findings: readonly Finding[], maxExamples?: number): Finding[];
 /**
  * Count findings per severity, including zeroes, so the JSON summary has a
  * fixed key set that consumers can rely on.