@loomhelix/deptrail 0.1.0

package/dist/query/package-insight.js

@@ -0,0 +1,112 @@
+import semver from 'semver';
+import { IMPORTER_PREFIX, PLACEHOLDER_PREFIX } from "../model.js";
+import { advisoriesOfMatch, nodeAdvisories, nodeMeta, worstSeverity } from "./enrichment-lookup.js";
+import { requireNode } from "./lookup.js";
+import { edgeFixes, nodeFix, normalizedRequestedRange } from "./node-fix.js";
+import { outdatedLevel, wantedVersion } from "./versions.js";
+export const REQUESTED_CAP = 50;
+function insightAdvisory(advisory) {
+    const item = {
+        id: advisory.id,
+        aliases: advisory.aliases,
+        summary: advisory.summary,
+        severity: advisory.severity,
+        malicious: advisory.malicious,
+        url: advisory.url,
+        fixedIn: advisory.fixedIn,
+    };
+    if (advisory.cvss !== undefined)
+        item.cvss = advisory.cvss;
+    return item;
+}
+function registrySection(registry, node) {
+    if (registry.state === 'failed')
+        return { state: 'failed', message: registry.reason };
+    if (registry.state === 'not-found')
+        return { state: 'not-found', fetchedAt: registry.fetchedAt };
+    if (registry.state !== 'ok' && registry.state !== 'stale')
+        return { state: registry.state };
+    const { meta } = registry;
+    const section = { state: registry.state, fetchedAt: registry.fetchedAt };
+    const latest = meta.distTags.latest;
+    if (latest !== undefined)
+        section.latest = latest;
+    const level = outdatedLevel(node.version, latest);
+    if (level !== undefined)
+        section.outdatedLevel = level;
+    const deprecated = meta.deprecated[node.version];
+    if (deprecated !== undefined)
+        section.deprecated = deprecated;
+    if (semver.valid(node.version) !== null && !meta.versions.includes(node.version))
+        section.versionMissing = true;
+    return section;
+}
+function vulnerabilitiesSection(match, advisories) {
+    if (match.state === 'ok' || match.state === 'stale') {
+        return { state: match.state, fetchedAt: match.fetchedAt, items: advisories.map(insightAdvisory) };
+    }
+    if (match.state === 'skipped')
+        return { state: 'skipped', reason: match.reason, items: [] };
+    if (match.state === 'failed')
+        return { state: 'failed', message: match.reason, items: [] };
+    return { state: match.state, items: [] };
+}
+function requestedSection(view, root, node, kinds, vulnerable) {
+    const meta = nodeMeta(view, root, node);
+    const all = edgeFixes(view, root, node, kinds);
+    const requested = all.slice(0, REQUESTED_CAP).map(({ parent, range, fix }) => {
+        const row = { parent, range: range.range, rangeSource: range.source };
+        const normalizedRange = normalizedRequestedRange(root, node, meta, range);
+        if (normalizedRange !== undefined)
+            row.normalizedRange = normalizedRange;
+        const wanted = meta ? wantedVersion(meta.versions, normalizedRange) : undefined;
+        if (wanted !== undefined)
+            row.wanted = wanted;
+        if (vulnerable) {
+            row.fix = fix.kind;
+            if (fix.version !== undefined)
+                row.fixVersion = fix.version;
+        }
+        return row;
+    });
+    return { requested, requestedTruncated: all.length - requested.length };
+}
+function versionSeverities(view, node, monolithVersions) {
+    const result = {};
+    for (const version of monolithVersions) {
+        if (version === node.version)
+            continue;
+        const advisories = advisoriesOfMatch(view, node.name, view.matchOfVersion(node.name, version));
+        const worst = worstSeverity(advisories.map((advisory) => advisory.severity));
+        if (worst !== undefined)
+            result[version] = worst;
+    }
+    return result;
+}
+export function packageInsight(view, root, nodeId, kinds, monolithVersions) {
+    const found = requireNode(root, nodeId);
+    if (found.id.startsWith(IMPORTER_PREFIX) || found.id.startsWith(PLACEHOLDER_PREFIX)) {
+        return {
+            revision: view.revision,
+            registry: { state: 'not-applicable' },
+            requested: [],
+            requestedTruncated: 0,
+            vulnerabilities: { state: 'not-applicable', items: [] },
+            versionSeverities: {},
+        };
+    }
+    const node = found;
+    const advisories = nodeAdvisories(view, root, node);
+    const vulnerable = advisories.length > 0;
+    const insight = {
+        revision: view.revision,
+        registry: registrySection(view.registryOf(root, node), node),
+        ...requestedSection(view, root, node, kinds, vulnerable),
+        vulnerabilities: vulnerabilitiesSection(view.matchOf(root, node), advisories),
+        versionSeverities: versionSeverities(view, node, monolithVersions),
+    };
+    const fix = nodeFix(view, root, node, kinds);
+    if (fix !== undefined)
+        insight.fix = fix;
+    return insight;
+}

package/dist/query/search.js

@@ -0,0 +1,61 @@
+import semver from 'semver';
+const DEFAULT_MAX_HITS = 50;
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function compareVersions(left, right) {
+    const leftValid = semver.valid(left) !== null;
+    const rightValid = semver.valid(right) !== null;
+    if (leftValid && rightValid)
+        return semver.rcompare(left, right);
+    if (leftValid)
+        return -1;
+    if (rightValid)
+        return 1;
+    return compareText(left, right);
+}
+function parseQuery(query) {
+    const separator = query.lastIndexOf('@');
+    if (separator <= 0)
+        return { term: query };
+    return { term: query.slice(0, separator), range: query.slice(separator + 1) };
+}
+function groupByVersion(entries) {
+    const byVersion = new Map();
+    for (const entry of entries) {
+        const roots = byVersion.get(entry.version) ?? [];
+        roots.push({ rootId: entry.rootId, nodeId: entry.nodeId });
+        byVersion.set(entry.version, roots);
+    }
+    return [...byVersion]
+        .sort(([left], [right]) => compareVersions(left, right))
+        .map(([version, roots]) => ({
+        version,
+        roots: roots.sort((left, right) => compareText(left.rootId, right.rootId) || compareText(left.nodeId, right.nodeId)),
+    }));
+}
+function satisfiesRange(version, range) {
+    return semver.valid(version) !== null && semver.satisfies(version, range, { includePrerelease: true });
+}
+export function search(index, query, max = DEFAULT_MAX_HITS) {
+    const trimmed = query.trim();
+    if (trimmed === '')
+        return [];
+    const { term, range } = parseQuery(trimmed);
+    const needle = term.toLowerCase();
+    if (range !== undefined && semver.validRange(range) === null)
+        return [];
+    const hits = [];
+    for (const [name, entries] of index) {
+        const lowerName = name.toLowerCase();
+        if (range === undefined ? !lowerName.includes(needle) : lowerName !== needle)
+            continue;
+        const matching = range === undefined ? entries : entries.filter((entry) => satisfiesRange(entry.version, range));
+        if (matching.length === 0)
+            continue;
+        hits.push({ name, versions: groupByVersion(matching) });
+    }
+    const exactFirst = (hit) => (hit.name.toLowerCase() === needle ? 0 : 1);
+    hits.sort((left, right) => exactFirst(left) - exactFirst(right) || left.name.length - right.name.length || compareText(left.name, right.name));
+    return hits.slice(0, max);
+}

package/dist/query/subgraph.js

@@ -0,0 +1,107 @@
+import { ParentLinkResolver } from "./dependents.js";
+import { passingEdges, requireNode, viewOf } from "./lookup.js";
+class SubgraphWalk {
+    root;
+    options;
+    links;
+    visited = new Map();
+    queue = [];
+    truncated = false;
+    constructor(root, options) {
+        this.root = root;
+        this.options = options;
+        this.links = new ParentLinkResolver(root, options.kinds);
+    }
+    run(focus) {
+        this.visit(focus, 0);
+        for (let cursor = 0; cursor < this.queue.length; cursor++) {
+            const { node, layer } = this.queue[cursor];
+            if (this.canExpandUp(layer)) {
+                for (const parentId of this.parentIds(node))
+                    this.visit(requireNode(this.root, parentId), layer - 1, true);
+            }
+            if (this.canExpandDown(layer)) {
+                for (const childId of this.childIds(node))
+                    this.visit(requireNode(this.root, childId), layer + 1, true);
+            }
+        }
+        return this.queue;
+    }
+    has(id) {
+        return this.visited.has(id);
+    }
+    parentIds(node) {
+        return [...new Set(this.links.of(node).map((link) => link.id))];
+    }
+    childIds(node) {
+        return [...new Set(passingEdges(node, this.options.kinds).map((edge) => edge.to))];
+    }
+    canExpandUp(layer) {
+        return layer <= 0 && layer > -this.options.up;
+    }
+    canExpandDown(layer) {
+        return layer >= 0 && layer < this.options.down;
+    }
+    visit(node, layer, enforceLimit = false) {
+        if (this.visited.has(node.id))
+            return;
+        if (enforceLimit && this.queue.length >= this.options.limit) {
+            this.truncated = true;
+            return;
+        }
+        const visit = { node, layer };
+        this.visited.set(node.id, visit);
+        this.queue.push(visit);
+    }
+}
+function collectEdges(walk, visits, kinds) {
+    const edges = [];
+    const seen = new Set();
+    for (const { node } of visits) {
+        for (const edge of passingEdges(node, kinds)) {
+            if (!walk.has(edge.to))
+                continue;
+            const key = `${node.id}\u0000${edge.to}\u0000${edge.kind}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            edges.push({ from: node.id, to: edge.to, kind: edge.kind });
+        }
+    }
+    return edges;
+}
+function countHidden(walk, ids) {
+    let hidden = 0;
+    for (const id of ids)
+        if (!walk.has(id))
+            hidden++;
+    return hidden;
+}
+function collectStubs(walk, visits) {
+    const stubs = [];
+    for (const { node, layer } of visits) {
+        if (layer <= 0) {
+            const hidden = countHidden(walk, walk.parentIds(node));
+            if (hidden > 0)
+                stubs.push({ at: node.id, side: 'up', hidden });
+        }
+        if (layer >= 0) {
+            const hidden = countHidden(walk, walk.childIds(node));
+            if (hidden > 0)
+                stubs.push({ at: node.id, side: 'down', hidden });
+        }
+    }
+    return stubs;
+}
+export function subgraph(root, id, options) {
+    const focus = requireNode(root, id);
+    const walk = new SubgraphWalk(root, options);
+    const visits = walk.run(focus);
+    return {
+        focus: id,
+        nodes: visits.map(({ node, layer }) => ({ node: viewOf(node), layer })),
+        edges: collectEdges(walk, visits, options.kinds),
+        stubs: collectStubs(walk, visits),
+        truncated: walk.truncated,
+    };
+}

package/dist/query/versions.js

@@ -0,0 +1,103 @@
+import semver from 'semver';
+import { isNonRegistrySpec } from "../adapters/package-manifest.js";
+const LOCAL_SPEC_PREFIXES = ['workspace:', 'link:', 'file:'];
+const NPM_ALIAS_PREFIX = 'npm:';
+const CATALOG_PREFIX = 'catalog:';
+const DEFAULT_CATALOG = 'default';
+const LATEST_TAG = 'latest';
+function resolveCatalogRange(range, context) {
+    const catalogName = range.slice(CATALOG_PREFIX.length) || DEFAULT_CATALOG;
+    const resolved = context.catalogs[catalogName]?.[context.name];
+    if (resolved === undefined || resolved.startsWith(CATALOG_PREFIX))
+        return undefined;
+    return normalizeRange(resolved, context);
+}
+function resolveAliasRange(range, context) {
+    const versionSeparator = range.lastIndexOf('@');
+    const aliased = versionSeparator > NPM_ALIAS_PREFIX.length ? range.slice(versionSeparator + 1) : LATEST_TAG;
+    if (aliased.startsWith(NPM_ALIAS_PREFIX))
+        return undefined;
+    return normalizeRange(aliased, context);
+}
+export function normalizeRange(range, context) {
+    if (LOCAL_SPEC_PREFIXES.some((prefix) => range.startsWith(prefix)) || isNonRegistrySpec(range))
+        return undefined;
+    if (range.startsWith(CATALOG_PREFIX))
+        return resolveCatalogRange(range, context);
+    if (range.startsWith(NPM_ALIAS_PREFIX))
+        return resolveAliasRange(range, context);
+    if (semver.validRange(range) !== null)
+        return range;
+    const tagged = context.distTags?.[range];
+    return tagged !== undefined && semver.valid(tagged) !== null ? tagged : undefined;
+}
+export function wantedVersion(versions, range) {
+    if (range === undefined || semver.validRange(range) === null)
+        return undefined;
+    return semver.maxSatisfying(versions.filter((version) => semver.valid(version) !== null), range) ?? undefined;
+}
+export function outdatedLevel(current, latest) {
+    if (latest === undefined || semver.valid(current) === null || semver.valid(latest) === null)
+        return undefined;
+    if (semver.prerelease(current) !== null || !semver.gt(latest, current))
+        return undefined;
+    const difference = semver.diff(current, latest);
+    if (difference === 'major' || difference === 'premajor')
+        return 'major';
+    if (difference === 'minor' || difference === 'preminor')
+        return 'minor';
+    return 'patch';
+}
+function eventVersion(event) {
+    if ('introduced' in event)
+        return event.introduced;
+    if ('fixed' in event)
+        return event.fixed;
+    return event.last_affected;
+}
+function isUsableEvent(event) {
+    const version = eventVersion(event);
+    if (typeof version !== 'string')
+        return false;
+    if ('introduced' in event && version === '0')
+        return true;
+    return semver.valid(version) !== null;
+}
+function compareEventVersions(left, right) {
+    if (left === right)
+        return 0;
+    if (left === '0')
+        return -1;
+    if (right === '0')
+        return 1;
+    return semver.compare(left, right);
+}
+function sortedEvents(events) {
+    return events
+        .filter(isUsableEvent)
+        .sort((left, right) => compareEventVersions(eventVersion(left), eventVersion(right)));
+}
+export function isAffected(version, advisory) {
+    if (advisory.affected.some((entry) => entry.versions.includes(version)))
+        return true;
+    if (semver.valid(version) === null)
+        return false;
+    return advisory.affected.some((entry) => entry.ranges.some((range) => {
+        let affected = false;
+        for (const event of sortedEvents(range.events)) {
+            if ('introduced' in event && (event.introduced === '0' || semver.gte(version, event.introduced)))
+                affected = true;
+            if ('fixed' in event && semver.gte(version, event.fixed))
+                affected = false;
+            if ('last_affected' in event && semver.gt(version, event.last_affected))
+                affected = false;
+        }
+        return affected;
+    }));
+}
+export function safeVersions(meta, advisories) {
+    return meta.versions
+        .filter((version) => semver.valid(version) !== null && semver.prerelease(version) === null)
+        .filter((version) => !advisories.some((advisory) => isAffected(version, advisory)))
+        .sort(semver.compare);
+}

package/dist/scan/build-root.js

@@ -0,0 +1,137 @@
+import { posix } from 'node:path';
+import { buildManifestOnly } from "../adapters/manifest-only.js";
+import { parseNpmLock } from "../adapters/npm-lock.js";
+import { readManifest } from "../adapters/package-manifest.js";
+import { parsePnpmLock } from "../adapters/pnpm-lock.js";
+import { walkNodeModules } from "../adapters/node-modules.js";
+import { resolveToday } from "../adapters/resolve-today.js";
+import { RootGraphBuilder } from "../graph/root-graph-builder.js";
+const LOCKFILE_PARSERS = {
+    'pnpm-lock.yaml': parsePnpmLock,
+    'package-lock.json': parseNpmLock,
+    'npm-shrinkwrap.json': parseNpmLock,
+};
+function newBuilder(root, source) {
+    return new RootGraphBuilder({ id: root.id, path: root.path, manager: root.manager, source });
+}
+export function messageOf(failure) {
+    return failure instanceof Error ? failure.message : String(failure);
+}
+export function failedRootGraph(root, error, warnings = []) {
+    return {
+        id: root.id,
+        path: root.path,
+        manager: root.manager,
+        source: root.lockfile ? 'lockfile' : 'manifest-only',
+        status: 'failed',
+        error,
+        importers: [],
+        packages: new Map(),
+        warnings,
+    };
+}
+function parseLockfileText(root, text, source, parser) {
+    const builder = newBuilder(root, source);
+    const { supported } = parser(text, builder);
+    const graph = builder.build();
+    if (supported)
+        return { graph, reason: '' };
+    return { graph: null, reason: graph.warnings.join('; ') || 'lockfile is not supported' };
+}
+export function parseRootLockfile(root, lockfileName, text) {
+    const parser = LOCKFILE_PARSERS[posix.basename(lockfileName)];
+    if (!parser)
+        return { error: `${lockfileName} has no supported lockfile format` };
+    try {
+        const attempt = parseLockfileText({ ...root, importerPaths: [] }, text, 'lockfile', parser);
+        return attempt.graph ? { graph: attempt.graph } : { error: attempt.reason };
+    }
+    catch (failure) {
+        return { error: messageOf(failure) };
+    }
+}
+async function attemptLockfile(root, reader) {
+    if (!root.lockfile)
+        return { graph: null, reason: 'no lockfile' };
+    const parser = LOCKFILE_PARSERS[posix.basename(root.lockfile)];
+    if (!parser)
+        return { graph: null, reason: `${root.lockfile} has no supported lockfile format` };
+    const text = await reader.readText(root.lockfile);
+    if (text === null)
+        return { graph: null, reason: `${root.lockfile} could not be read` };
+    return parseLockfileText(root, text, 'lockfile', parser);
+}
+async function attemptInstalled(root, reader) {
+    const builder = newBuilder(root, 'installed');
+    return (await walkNodeModules(reader, root, builder)) ? builder.build() : null;
+}
+async function attemptResolveToday(root, deps) {
+    if (!deps.allowResolve)
+        return { graph: null, reason: 'versions not resolved' };
+    const result = await resolveToday(deps.reader, root, deps.runner);
+    if ('error' in result)
+        return { graph: null, reason: `version resolution failed: ${result.error}` };
+    const parser = result.manager === 'pnpm' ? parsePnpmLock : parseNpmLock;
+    const attempt = parseLockfileText(root, result.lockfileText, 'resolved-today', parser);
+    if (attempt.graph)
+        return attempt;
+    return { graph: null, reason: `resolved ${result.manager} lockfile is not usable: ${attempt.reason}` };
+}
+async function attemptManifestOnly(root, reader) {
+    const builder = newBuilder(root, 'manifest-only');
+    await buildManifestOnly(reader, root, builder);
+    return builder.build();
+}
+function withFallbackWarning(graph, reasons) {
+    if (reasons.length === 0)
+        return graph;
+    const sourceLabel = {
+        lockfile: 'lockfile',
+        installed: 'installed node_modules',
+        'resolved-today': 'versions resolved today',
+        'manifest-only': 'package.json manifests only',
+    };
+    graph.warnings.push(`${reasons.join('; ')}; built from ${sourceLabel[graph.source]}`);
+    return graph;
+}
+async function useRepoRelativeImporters(root, graph, reader) {
+    await Promise.all(graph.importers.map(async (importer) => {
+        const rootRelativePath = importer.path;
+        importer.path = rootRelativePath === '.' ? root.path : posix.join(root.path, rootRelativePath);
+        if (importer.name !== rootRelativePath)
+            return;
+        const read = await readManifest(reader, importer.path);
+        if ('manifest' in read && read.manifest.name)
+            importer.name = read.manifest.name;
+    }));
+}
+async function cascade(root, deps, reasons) {
+    const fromLockfile = await attemptLockfile(root, deps.reader);
+    if (fromLockfile.graph)
+        return finish(root, fromLockfile.graph, reasons, deps);
+    reasons.push(fromLockfile.reason);
+    if (deps.allowInstalled !== false) {
+        const installed = await attemptInstalled(root, deps.reader);
+        if (installed)
+            return finish(root, installed, reasons, deps);
+        reasons.push('no installed node_modules');
+    }
+    const resolved = await attemptResolveToday(root, deps);
+    if (resolved.graph)
+        return finish(root, resolved.graph, reasons, deps);
+    reasons.push(resolved.reason);
+    return finish(root, await attemptManifestOnly(root, deps.reader), reasons, deps);
+}
+async function finish(root, graph, reasons, deps) {
+    await useRepoRelativeImporters(root, graph, deps.reader);
+    return withFallbackWarning(graph, reasons);
+}
+export async function buildRoot(root, deps) {
+    const reasons = [];
+    try {
+        return await cascade(root, deps, reasons);
+    }
+    catch (failure) {
+        return failedRootGraph(root, messageOf(failure), reasons.length > 0 ? [reasons.join('; ')] : []);
+    }
+}

package/dist/scan/cache-shape.js

@@ -0,0 +1,52 @@
+const STATUSES = new Set(['scanning', 'ready', 'failed']);
+const SOURCES = new Set(['lockfile', 'installed', 'resolved-today', 'manifest-only']);
+const MANAGERS = new Set(['pnpm', 'npm', 'unknown']);
+const DEP_KINDS = new Set(['prod', 'dev', 'optional', 'peer']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function isEdge(value) {
+    return (isRecord(value) &&
+        typeof value.to === 'string' &&
+        typeof value.range === 'string' &&
+        typeof value.kind === 'string' &&
+        DEP_KINDS.has(value.kind));
+}
+function hasEdgesAndDependents(node) {
+    return Array.isArray(node.deps) && node.deps.every(isEdge) && isStringArray(node.dependents);
+}
+function isImporter(value) {
+    return (isRecord(value) &&
+        typeof value.id === 'string' &&
+        typeof value.path === 'string' &&
+        typeof value.name === 'string' &&
+        hasEdgesAndDependents(value));
+}
+function isPackage(value) {
+    return (isRecord(value) &&
+        typeof value.id === 'string' &&
+        typeof value.name === 'string' &&
+        typeof value.version === 'string' &&
+        (value.peerSuffix === undefined || typeof value.peerSuffix === 'string') &&
+        (value.nonRegistry === undefined || value.nonRegistry === true) &&
+        hasEdgesAndDependents(value));
+}
+export function isRootGraphShape(json) {
+    return (isRecord(json) &&
+        typeof json.id === 'string' &&
+        typeof json.path === 'string' &&
+        typeof json.manager === 'string' &&
+        MANAGERS.has(json.manager) &&
+        typeof json.status === 'string' &&
+        STATUSES.has(json.status) &&
+        typeof json.source === 'string' &&
+        SOURCES.has(json.source) &&
+        isStringArray(json.warnings) &&
+        Array.isArray(json.importers) &&
+        json.importers.every(isImporter) &&
+        Array.isArray(json.packages) &&
+        json.packages.every(isPackage));
+}

package/dist/scan/scan-cache.js

@@ -0,0 +1,32 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { deserializeRootGraph, serializeRootGraph } from "../graph/serialize.js";
+import { isRootGraphShape } from "./cache-shape.js";
+const KEY_SEPARATOR = '\0';
+export const CACHE_FORMAT = 2;
+export function cacheKeyOf(repoPath, rootPath, lockfileText, format = CACHE_FORMAT) {
+    return createHash('sha256')
+        .update([String(format), repoPath, rootPath, lockfileText].join(KEY_SEPARATOR))
+        .digest('hex');
+}
+export function createScanCache(dir) {
+    const fileOf = (key) => path.join(dir, `${key}.json`);
+    return {
+        async get(key) {
+            try {
+                const json = JSON.parse(await readFile(fileOf(key), 'utf8'));
+                return isRootGraphShape(json) ? deserializeRootGraph(json) : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async set(key, graph) {
+            await mkdir(dir, { recursive: true });
+            const temporaryFile = `${fileOf(key)}.${randomUUID()}.tmp`;
+            await writeFile(temporaryFile, JSON.stringify(serializeRootGraph(graph)));
+            await rename(temporaryFile, fileOf(key));
+        },
+    };
+}