@xagents_in/unmask 0.1.2 → 0.1.4

package/dist/cli/lockfile.mjs

@@ -0,0 +1,330 @@
+import { constants, open } from "node:fs/promises";
+import { LocalInputError } from "../core/pipeline.mjs";
+
+export const LOCKFILE_LIMITS = Object.freeze({
+  maxBytes: 32 * 1024 * 1024,
+  maxEntries: 100000,
+});
+const EXACT =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const EDGE_TYPES = [
+  ["dependencies", "prod"],
+  ["optionalDependencies", "optional"],
+  ["peerDependencies", "peer"],
+  ["devDependencies", "dev"],
+];
+const invalid = (message) => new LocalInputError("lockfile-invalid", message);
+const isObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export const isExactVersion = (value) =>
+  typeof value === "string" &&
+  value.length <= 256 &&
+  EXACT.test(value) &&
+  !value
+    .split("+")[0]
+    .split("-")
+    .slice(1)
+    .join("-")
+    .split(".")
+    .some((part) => /^0\d+$/.test(part));
+export const isPackageName = (value) =>
+  typeof value === "string" && value.length <= 214 && NAME.test(value);
+
+export function nameFromKey(key) {
+  const index = key.lastIndexOf("node_modules/");
+  return index === -1 ? null : key.slice(index + "node_modules/".length);
+}
+
+export function parentKey(key) {
+  const index = key.lastIndexOf("/node_modules/");
+  return index === -1 ? "" : key.slice(0, index);
+}
+
+export const NPM_REGISTRY_HOST = "registry.npmjs.org";
+export function isNpmRegistryTarball(resolved, name, version) {
+  if (typeof resolved !== "string") return false;
+  try {
+    const url = new URL(resolved);
+    return (
+      url.protocol === "https:" &&
+      url.host === NPM_REGISTRY_HOST &&
+      !url.username &&
+      !url.password &&
+      !url.search &&
+      !url.hash &&
+      url.pathname === `/${name}/-/${name.split("/").pop()}-${version}.tgz`
+    );
+  } catch {
+    return false;
+  }
+}
+
+function classify(key, raw) {
+  if (key === "") return { kind: "root", reason: null };
+  if (raw.link === true) return { kind: "link", reason: "workspace-or-link" };
+  if (!key.includes("node_modules/"))
+    return { kind: "workspace", reason: "workspace-or-link" };
+  if (raw.inBundle === true)
+    return { kind: "bundled", reason: "bundled-dependency" };
+  const name = raw.name ?? nameFromKey(key);
+  if (!isPackageName(name)) return { kind: "invalid", reason: "invalid-name" };
+  if (typeof raw.version !== "string")
+    return { kind: "invalid", reason: "missing-version" };
+  if (/^(?:git\+|git:|github:|https?:|file:)/.test(raw.version))
+    return { kind: "url", reason: "non-registry-source" };
+  if (!isExactVersion(raw.version))
+    return { kind: "invalid", reason: "inexact-version" };
+  if (
+    raw.resolved !== undefined &&
+    !isNpmRegistryTarball(raw.resolved, name, raw.version)
+  )
+    return { kind: "url", reason: "non-registry-source" };
+  return { kind: "registry", reason: null };
+}
+
+function edges(raw) {
+  const result = [];
+  const peerMeta = isObject(raw.peerDependenciesMeta)
+    ? raw.peerDependenciesMeta
+    : {};
+  for (const [field, type] of EDGE_TYPES) {
+    const value = raw[field];
+    if (value === undefined) continue;
+    if (!isObject(value)) throw invalid(`Lockfile ${field} must be an object.`);
+    for (const [name, range] of Object.entries(value)) {
+      // Legacy or unusual names stay as edges; only their own entries are classified invalid.
+      if (
+        typeof range !== "string" ||
+        !name ||
+        name.length > 214 ||
+        /[\0-\x1f\x7f\\]/.test(name)
+      )
+        throw invalid(`Lockfile ${field} contains an invalid entry.`);
+      result.push({
+        name,
+        range,
+        type:
+          type === "peer" && peerMeta[name]?.optional === true
+            ? "peer-optional"
+            : type,
+      });
+    }
+  }
+  return result;
+}
+
+export function parseLockfile(text, limits = LOCKFILE_LIMITS) {
+  if (typeof text !== "string" || Buffer.byteLength(text) > limits.maxBytes)
+    throw invalid("Lockfile is missing or exceeds the size limit.");
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw invalid("Lockfile is not valid JSON.");
+  }
+  if (!isObject(data)) throw invalid("Lockfile must be a JSON object.");
+  if (![2, 3].includes(data.lockfileVersion))
+    throw new LocalInputError(
+      "lockfile-unsupported",
+      "Only npm lockfileVersion 2 or 3 (with a packages map) is supported.",
+    );
+  // npm writes an empty packages map for a project with no dependencies.
+  if (isObject(data.packages) && Object.keys(data.packages).length === 0)
+    data.packages = { "": {} };
+  if (!isObject(data.packages) || !isObject(data.packages[""]))
+    throw invalid("Lockfile packages map with a root entry is required.");
+  const keys = Object.keys(data.packages);
+  if (keys.length > limits.maxEntries)
+    throw invalid("Lockfile exceeds the entry limit.");
+  const entries = new Map();
+  for (const key of keys) {
+    const value = data.packages[key];
+    const badKey =
+      key.length > 4096 ||
+      (key !== "" &&
+        key
+          .split("/")
+          .some(
+            (part) => ["", ".", ".."].includes(part) || part.includes("\\"),
+          ));
+    // Malformed entries are kept as invalid so the rest of the graph still parses.
+    const raw = isObject(value) && !badKey ? value : {};
+    const { kind, reason } = badKey
+      ? { kind: "invalid", reason: "invalid-location" }
+      : !isObject(value)
+        ? { kind: "invalid", reason: "invalid-entry" }
+        : classify(key, raw);
+    let entryEdges = [];
+    let edgesValid = true;
+    try {
+      entryEdges = kind === "link" ? [] : edges(raw);
+    } catch {
+      edgesValid = false;
+    }
+    entries.set(key, {
+      key,
+      name:
+        key === ""
+          ? (raw.name ?? data.name ?? null)
+          : (raw.name ?? nameFromKey(key) ?? key),
+      version: typeof raw.version === "string" ? raw.version : null,
+      kind,
+      reason,
+      dev: raw.dev === true,
+      optional: raw.optional === true || raw.devOptional === true,
+      bundled: raw.inBundle === true,
+      resolved: typeof raw.resolved === "string" ? raw.resolved : null,
+      integrity: typeof raw.integrity === "string" ? raw.integrity : null,
+      bound:
+        kind === "registry" &&
+        isNpmRegistryTarball(
+          raw.resolved,
+          raw.name ?? nameFromKey(key),
+          raw.version,
+        ) &&
+        /^sha512-[A-Za-z0-9+/]{86}==$/.test(raw.integrity ?? ""),
+      edges: entryEdges,
+      edgesValid,
+    });
+  }
+  // npm omits name on workspace entries; the linking node_modules key carries it.
+  for (const entry of entries.values()) {
+    const target = entry.kind === "link" && entries.get(entry.resolved ?? "");
+    if (target?.kind === "workspace" && target.name === target.key)
+      target.name = nameFromKey(entry.key);
+  }
+  return { lockfileVersion: data.lockfileVersion, entries };
+}
+
+export async function readLockfile(filename, limits = LOCKFILE_LIMITS) {
+  const unreadable = () =>
+    new LocalInputError(
+      "lockfile-unreadable",
+      "The lockfile must be a readable regular file within the size limit; pass --lockfile PATH to package-lock.json.",
+    );
+  let handle;
+  try {
+    // Nonblocking open plus fstat rejects FIFOs/devices before any read.
+    handle = await open(filename, constants.O_RDONLY | constants.O_NONBLOCK);
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > limits.maxBytes) throw unreadable();
+    const buffer = Buffer.alloc(info.size + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(
+        buffer,
+        length,
+        buffer.length - length,
+        length,
+      );
+      if (bytesRead === 0) break;
+      length += bytesRead;
+    }
+    if (length !== info.size) throw unreadable();
+    return parseLockfile(buffer.subarray(0, length).toString("utf8"), limits);
+  } catch (error) {
+    if (error instanceof LocalInputError) throw error;
+    throw unreadable();
+  } finally {
+    await handle?.close();
+  }
+}
+
+export function resolveEdge(lock, fromKey, name) {
+  let base = fromKey;
+  for (let step = 0; step < 4096; step++) {
+    const candidate = (base ? base + "/" : "") + "node_modules/" + name;
+    const entry = lock.entries.get(candidate);
+    if (entry) {
+      if (entry.kind !== "link") return entry;
+      return lock.entries.get(entry.resolved ?? "") ?? null;
+    }
+    if (base === "") return null;
+    base = parentKey(base);
+  }
+  return null;
+}
+
+function scanEdges(lock, omitDev) {
+  const missing = [];
+  const omitted = { optional: 0, peerOptional: 0, devEdges: 0 };
+  for (const entry of lock.entries.values()) {
+    if (entry.kind === "link" || (omitDev && entry.dev)) continue;
+    const project = ["root", "workspace"].includes(entry.kind);
+    for (const edge of entry.edges) {
+      if (edge.type === "dev" && !project) continue;
+      const found = resolveEdge(lock, entry.key, edge.name);
+      if (edge.type === "dev" && omitDev) omitted.devEdges++;
+      else if (found) continue;
+      else if (edge.type === "optional") omitted.optional++;
+      else if (edge.type === "peer-optional") omitted.peerOptional++;
+      else missing.push({ from: entry.key, name: edge.name, type: edge.type });
+    }
+  }
+  return { missing, omitted };
+}
+
+export function unresolvedEdges(lock, { omitDev = false } = {}) {
+  return scanEdges(lock, omitDev).missing;
+}
+
+export function exactTargets(lock, { omitDev = false } = {}) {
+  const unique = new Map();
+  const skipped = {};
+  let considered = 0;
+  const { missing: unresolved, omitted } = scanEdges(lock, omitDev);
+  omitted.devEntries = 0;
+  if (unresolved.length) skipped["unresolved-dependency"] = unresolved.length;
+  const badEdges = [...lock.entries.values()].filter(
+    (entry) => !entry.edgesValid && !(omitDev && entry.dev),
+  ).length;
+  if (badEdges) skipped["invalid-dependencies"] = badEdges;
+  for (const entry of lock.entries.values()) {
+    if (omitDev && entry.dev) {
+      if (!["root", "workspace", "link"].includes(entry.kind))
+        omitted.devEntries++;
+      continue;
+    }
+    // A link whose target entry is absent means unlocked local code.
+    if (entry.kind === "link" && !lock.entries.has(entry.resolved ?? "")) {
+      skipped["dangling-link"] = (skipped["dangling-link"] ?? 0) + 1;
+      continue;
+    }
+    if (["root", "workspace", "link"].includes(entry.kind)) continue;
+    considered++;
+    if (entry.kind !== "registry") {
+      skipped[entry.reason] = (skipped[entry.reason] ?? 0) + 1;
+      continue;
+    }
+    const spec = `${entry.name}@${entry.version}`;
+    const target = unique.get(spec) ?? {
+      spec,
+      name: entry.name,
+      version: entry.version,
+      locations: [],
+      bound: true,
+      integrity: [],
+      aliases: [],
+    };
+    target.locations.push(entry.key);
+    const alias = nameFromKey(entry.key);
+    if (alias !== entry.name && !target.aliases.includes(alias))
+      target.aliases.push(alias);
+    target.bound &&= entry.bound;
+    if (entry.integrity && !target.integrity.includes(entry.integrity))
+      target.integrity.push(entry.integrity);
+    if (target.integrity.length > 1) target.bound = false;
+    unique.set(spec, target);
+  }
+  return {
+    considered,
+    targets: [...unique.values()].sort((a, b) =>
+      a.spec < b.spec ? -1 : a.spec > b.spec ? 1 : 0,
+    ),
+    skipped,
+    omitted,
+    unresolved: unresolved.slice(0, 100),
+  };
+}

package/dist/cli/main.mjs

@@ -8,7 +8,35 @@ import { renderReport } from "../viewer/render.mjs";
 import { parsePackageSpec, AcquisitionError } from "../core/acquire.mjs";
 import { addConfiguredModel } from "../core/online.mjs";
 import { modelClientFromEnv } from "../model/config.mjs";
-import { checkHosted } from "./hosted.mjs";
+import { getHostedDetails } from "./hosted.mjs";
+import { infoCommand } from "./info.mjs";
+import { filesCommand } from "./files.mjs";
+import { fileCommand } from "./file.mjs";
+import {
+  createProgress,
+  renderAdvisoryOnly,
+  renderCheckSummary,
+  renderError,
+  terminalStyle,
+} from "./terminal.mjs";
+import { discoveryCommand, isDiscoveryRequest } from "./discovery.mjs";
+import { runConfig } from "./config.mjs";
+import { runExceptions } from "./exceptions.mjs";
+import { runInit } from "./init.mjs";
+import { runScan } from "./scan.mjs";
+import { runBatch } from "./batch.mjs";
+import { runInstallGuard } from "./install-guard.mjs";
+import { runShellIntegration } from "./shell-integration.mjs";
+import { runAudit } from "./audit.mjs";
+import { runWhy } from "./why.mjs";
+import { preflightMain } from "./preflight.mjs";
+import { watchMain } from "./watch.mjs";
+import { runCompare } from "./compare.mjs";
+import { runHistory } from "./history.mjs";
+import { doctorCommand } from "./doctor.mjs";
+import { cacheCommand } from "./cache.mjs";
+import { sarifCommand } from "./sarif.mjs";
+import { annotationsCommand } from "./annotations.mjs";
 
 const names = {
   "--tarball": "tarballPath",
@@ -33,7 +61,7 @@ function parse(argv) {
   if (argv[0] !== "check")
     throw new LocalInputError(
       "usage",
-      "Use check name@version or an explicit local tarball with --offline",
+      "Use check name@version, audit, why name, or an explicit local tarball with --offline",
     );
   const options = {};
   let start = 1;
@@ -76,8 +104,6 @@ function parse(argv) {
       );
     options[names[key]] = value;
   }
-  if (!options.out)
-    throw new LocalInputError("usage", "Check requires --out DIR");
   if (options.registrySpec) {
     if (
       options.offline ||
@@ -103,7 +129,7 @@ function parse(argv) {
   if (!options.registrySpec && !options.cacheDir)
     throw new LocalInputError(
       "usage",
-      "Offline check requires --cache-dir DIR and --out DIR",
+      "Offline check requires --cache-dir DIR",
     );
   if (options.claim !== undefined) options.claim = exactClaim(options.claim);
   return options;
@@ -161,19 +187,56 @@ async function configuredModel(allowModel, runtime) {
 }
 
 export async function main(argv = process.argv.slice(2), runtime = {}) {
+  const stdout = runtime.stdout ?? process.stdout;
+  const stderr = runtime.stderr ?? process.stderr;
+  const env = runtime.env ?? process.env;
+  const errorStyle = terminalStyle(stderr, env);
+  let progress;
   try {
+    if (isDiscoveryRequest(argv)) return discoveryCommand(argv, runtime);
+    if (argv[0] === "install" || argv[0] === "ci")
+      return await runInstallGuard(argv[0], argv.slice(1), runtime);
+    if (argv[0] === "enable" || argv[0] === "disable")
+      return await runShellIntegration(argv[0], argv.slice(1), runtime);
+    if (argv[0] === "scan") return await runScan(argv.slice(1), runtime);
+    if (argv[0] === "batch") return await runBatch(argv.slice(1), runtime);
+    if (argv[0] === "config") return await runConfig(argv.slice(1), runtime);
+    if (argv[0] === "exceptions")
+      return await runExceptions(argv.slice(1), runtime);
+    if (argv[0] === "init") return await runInit(argv.slice(1), runtime);
+    if (argv[0] === "file") return await fileCommand(argv.slice(1), runtime);
+    if (argv[0] === "files") return await filesCommand(argv.slice(1), runtime);
+    if (argv[0] === "info") return await infoCommand(argv.slice(1), runtime);
+    if (argv[0] === "audit") return await runAudit(argv.slice(1), runtime);
+    if (argv[0] === "preflight")
+      return await preflightMain(argv.slice(1), runtime);
+    if (argv[0] === "watch") return await watchMain(argv.slice(1), runtime);
+    if (argv[0] === "why") return await runWhy(argv.slice(1));
+    if (argv[0] === "compare") return await runCompare(argv.slice(1), runtime);
+    if (argv[0] === "history") return await runHistory(argv.slice(1), runtime);
+    if (argv[0] === "doctor")
+      return await doctorCommand(argv.slice(1), runtime);
+    if (argv[0] === "cache") return await cacheCommand(argv.slice(1), runtime);
+    if (argv[0] === "sarif") return await sarifCommand(argv.slice(1));
+    if (argv[0] === "annotations")
+      return await annotationsCommand(argv.slice(1));
     const { out, offline, allowModel, registrySpec, ...options } = parse(argv);
-    let report;
+    progress = createProgress(stderr, { env, subject: registrySpec });
+    let report, details;
     if (registrySpec)
-      report = await checkHosted(registrySpec, {
-        serverUrl: (runtime.env ?? process.env).UNMASK_SERVER_URL,
+      ({ report, details } = await getHostedDetails(registrySpec, {
+        serverUrl: env.UNMASK_SERVER_URL,
         fetchImpl: runtime.fetchImpl,
         signal: runtime.signal,
         limits: runtime.hostedLimits,
-      });
+        optionalDetails: true,
+        onStatus: progress.update,
+      }));
     else {
       const model = await configuredModel(allowModel, runtime);
+      progress.update("local");
       report = await analyzeLocal({ ...options, limits: runtime.limits });
+      if (allowModel) progress.update("model");
       if (allowModel) report = await addConfiguredModel(report, model);
       if (!allowModel)
         report = {
@@ -181,16 +244,40 @@ export async function main(argv = process.argv.slice(2), runtime = {}) {
           model: { status: "not-sent", reason: "consent-required" },
         };
     }
-    await writeReports(out, report);
-    process.stdout.write(`Report written to ${path.resolve(out)}\n`);
+    const outDir = out === undefined ? undefined : path.resolve(out);
+    if (outDir) progress.update("writing");
+    if (outDir) await writeReports(outDir, report);
+    progress.stop();
+    stdout.write(
+      renderCheckSummary(report, {
+        details,
+        outDir,
+        style: terminalStyle(stdout, env),
+      }),
+    );
     return report.policy.exitCode;
   } catch (error) {
+    progress?.stop();
+    if (error instanceof LocalInputError && error.advisoryResult)
+      stdout.write(
+        renderAdvisoryOnly(
+          error.advisoryResult,
+          `${error.advisoryResult.package.name}@${error.advisoryResult.package.version}`,
+          {
+            style: terminalStyle(stdout, env),
+          },
+        ),
+      );
     if (error instanceof LocalInputError) {
-      process.stderr.write(`${error.code}: ${error.message}\n`);
+      stderr.write(renderError(error.code, error.message, errorStyle));
       return 2;
     }
-    process.stderr.write(
-      "Internal analysis error; no completed result is claimed.\n",
+    stderr.write(
+      renderError(
+        "internal",
+        "Internal analysis error; no completed result is claimed.",
+        errorStyle,
+      ),
     );
     return 1;
   }