@deplens/cli 0.1.5 → 0.1.6

package/README.md

@@ -14,6 +14,8 @@ npx deplens --help
 
 ```bash
 deplens <package-or-import-path> [filter]
+deplens inspect <package-or-import-path> [filter]
+deplens diff <package> [options]
 ```
 
 ## Examples
@@ -37,15 +39,44 @@ deplens ai --types \
   --jsdoc-tags param,returns \
   --jsdoc-truncate sentence \
   --jsdoc-max-len 220
+
+# Diff package versions
+
+deplens diff express --from 4.18.0 --to 4.19.0 --verbose
 ```
 
-## Flags
+## Flags (inspect)
 
 - `--types` — include type signatures from `.d.ts`
 - `--filter <text>` — substring filter for exports
+- `--search <query>` — semantic search (token match + JSDoc)
 - `--kind <k1,k2>` — `function`, `class`, `object`, `constant`
 - `--depth <0-5>` — object inspection depth
 - `--resolve-from <dir>` — base directory for module resolution
+- `--docs` — include README preview
+- `--examples` — include code examples
+- `--list-sections` — list README sections
+- `--docs-sections <s1,s2>` — extract README sections
+- `--remote` — download package to cache
+- `--remote-version <v>` — remote version override
+- `--max-exports <n>` — limit exports shown
+- `--max-props <n>` — limit object props shown
+- `--max-examples <n>` — limit examples shown
+- `--analyze-source` — analyze source complexity
+- `--source-max-files <n>` — max source files to analyze
+- `--source-include-body` — include function body snippets
+
+## Flags (diff)
+
+- `--from <version>` — base version (default: installed)
+- `--to <version>` — target version (default: latest)
+- `--filter <text>` — filter exports by name
+- `--format text|json` — output format
+- `--include-source` — compare source complexity
+- `--no-changelog` — skip changelog parsing
+- `--verbose` — show detailed changes
+- `--no-color` — disable ANSI colors
+- `--project-dir <dir>` — base directory for installed version
 
 JSDoc:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deplens/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Inspect exports and types of installed npm packages",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
     "bin"
   ],
   "dependencies": {
-    "@deplens/core": "0.1.5"
+    "@deplens/core": "0.1.6"
   },
   "publishConfig": {
     "access": "public"

package/src/cli.mjs

@@ -1,87 +1,152 @@
 #!/usr/bin/env node
-import { runInspect } from "@deplens/core"
+import { runInspect, runDiff } from "@deplens/core";
 
-function parseCliArgs(argv) {
-  const target = argv[0]
-  let filter = argv[1] && !argv[1].startsWith("--") ? argv[1].toLowerCase() : null
-  const showTypes = argv.includes("--types")
+function parseInspectArgs(argv) {
+  const target = argv[0];
+  let filter =
+    argv[1] && !argv[1].startsWith("--") ? argv[1].toLowerCase() : null;
+  const showTypes = argv.includes("--types");
+  const includeDocs =
+    argv.includes("--docs") || argv.includes("--include-docs");
+  const includeExamples =
+    argv.includes("--examples") || argv.includes("--include-examples");
+  const remote = argv.includes("--remote");
 
-  let jsdoc = null
-  const jsdocIndex = argv.indexOf("--jsdoc")
+  // New options
+  const listSections = argv.includes("--list-sections");
+
+  let format = "text";
+  const formatIndex = argv.indexOf("--format");
+  if (formatIndex !== -1 && argv[formatIndex + 1]) {
+    format = argv[formatIndex + 1].toLowerCase();
+  }
+
+  let search = null;
+  const searchIndex = argv.indexOf("--search");
+  if (searchIndex !== -1 && argv[searchIndex + 1]) {
+    search = argv[searchIndex + 1];
+  }
+
+  let docsSections = null;
+  const docsSectionsIndex = argv.indexOf("--docs-sections");
+  if (docsSectionsIndex !== -1 && argv[docsSectionsIndex + 1]) {
+    docsSections = argv[docsSectionsIndex + 1].split(",").map((s) => s.trim());
+  }
+
+  let maxExports = null;
+  const maxExportsIndex = argv.indexOf("--max-exports");
+  if (maxExportsIndex !== -1 && argv[maxExportsIndex + 1]) {
+    const parsed = parseInt(argv[maxExportsIndex + 1], 10);
+    if (!isNaN(parsed) && parsed > 0) maxExports = parsed;
+  }
+
+  let maxProps = null;
+  const maxPropsIndex = argv.indexOf("--max-props");
+  if (maxPropsIndex !== -1 && argv[maxPropsIndex + 1]) {
+    const parsed = parseInt(argv[maxPropsIndex + 1], 10);
+    if (!isNaN(parsed) && parsed > 0) maxProps = parsed;
+  }
+
+  let maxExamples = null;
+  const maxExamplesIndex = argv.indexOf("--max-examples");
+  if (maxExamplesIndex !== -1 && argv[maxExamplesIndex + 1]) {
+    const parsed = parseInt(argv[maxExamplesIndex + 1], 10);
+    if (!isNaN(parsed) && parsed > 0) maxExamples = parsed;
+  }
+
+  const analyzeSource = argv.includes("--analyze-source");
+  let sourceMaxFiles = null;
+  const sourceMaxFilesIndex = argv.indexOf("--source-max-files");
+  if (sourceMaxFilesIndex !== -1 && argv[sourceMaxFilesIndex + 1]) {
+    const parsed = parseInt(argv[sourceMaxFilesIndex + 1], 10);
+    if (!isNaN(parsed) && parsed > 0) sourceMaxFiles = parsed;
+  }
+  const sourceIncludeBody = argv.includes("--source-include-body");
+
+  let jsdoc = null;
+  const jsdocIndex = argv.indexOf("--jsdoc");
   if (jsdocIndex !== -1 && argv[jsdocIndex + 1]) {
-    jsdoc = argv[jsdocIndex + 1].toLowerCase()
+    jsdoc = argv[jsdocIndex + 1].toLowerCase();
   }
 
-  let jsdocOutput = null
-  const jsdocOutputIndex = argv.indexOf("--jsdoc-output")
+  let jsdocOutput = null;
+  const jsdocOutputIndex = argv.indexOf("--jsdoc-output");
   if (jsdocOutputIndex !== -1 && argv[jsdocOutputIndex + 1]) {
-    jsdocOutput = argv[jsdocOutputIndex + 1].toLowerCase()
+    jsdocOutput = argv[jsdocOutputIndex + 1].toLowerCase();
   }
 
-  let jsdocSymbols = null
-  const jsdocSymbolIndex = argv.indexOf("--jsdoc-symbol")
+  let jsdocSymbols = null;
+  const jsdocSymbolIndex = argv.indexOf("--jsdoc-symbol");
   if (jsdocSymbolIndex !== -1 && argv[jsdocSymbolIndex + 1]) {
-    jsdocSymbols = argv[jsdocSymbolIndex + 1]
+    jsdocSymbols = argv[jsdocSymbolIndex + 1];
   }
 
-  let jsdocSections = null
-  const jsdocSectionsIndex = argv.indexOf("--jsdoc-sections")
+  let jsdocSections = null;
+  const jsdocSectionsIndex = argv.indexOf("--jsdoc-sections");
   if (jsdocSectionsIndex !== -1 && argv[jsdocSectionsIndex + 1]) {
-    jsdocSections = argv[jsdocSectionsIndex + 1]
+    jsdocSections = argv[jsdocSectionsIndex + 1];
   }
 
-  let jsdocTagsInclude = null
-  const jsdocTagsIndex = argv.indexOf("--jsdoc-tags")
+  let jsdocTagsInclude = null;
+  const jsdocTagsIndex = argv.indexOf("--jsdoc-tags");
   if (jsdocTagsIndex !== -1 && argv[jsdocTagsIndex + 1]) {
-    jsdocTagsInclude = argv[jsdocTagsIndex + 1]
+    jsdocTagsInclude = argv[jsdocTagsIndex + 1];
   }
 
-  let jsdocTagsExclude = null
-  const jsdocTagsExcludeIndex = argv.indexOf("--jsdoc-tags-exclude")
+  let jsdocTagsExclude = null;
+  const jsdocTagsExcludeIndex = argv.indexOf("--jsdoc-tags-exclude");
   if (jsdocTagsExcludeIndex !== -1 && argv[jsdocTagsExcludeIndex + 1]) {
-    jsdocTagsExclude = argv[jsdocTagsExcludeIndex + 1]
+    jsdocTagsExclude = argv[jsdocTagsExcludeIndex + 1];
   }
 
-  let jsdocTruncate = null
-  const jsdocTruncateIndex = argv.indexOf("--jsdoc-truncate")
+  let jsdocTruncate = null;
+  const jsdocTruncateIndex = argv.indexOf("--jsdoc-truncate");
   if (jsdocTruncateIndex !== -1 && argv[jsdocTruncateIndex + 1]) {
-    jsdocTruncate = argv[jsdocTruncateIndex + 1].toLowerCase()
+    jsdocTruncate = argv[jsdocTruncateIndex + 1].toLowerCase();
   }
 
-  let jsdocMaxLen = null
-  const jsdocMaxLenIndex = argv.indexOf("--jsdoc-max-len")
+  let jsdocMaxLen = null;
+  const jsdocMaxLenIndex = argv.indexOf("--jsdoc-max-len");
   if (jsdocMaxLenIndex !== -1 && argv[jsdocMaxLenIndex + 1]) {
-    const parsed = parseInt(argv[jsdocMaxLenIndex + 1], 10)
-    if (!isNaN(parsed) && parsed >= 0) jsdocMaxLen = parsed
+    const parsed = parseInt(argv[jsdocMaxLenIndex + 1], 10);
+    if (!isNaN(parsed) && parsed >= 0) jsdocMaxLen = parsed;
   }
 
-  const filterIndex = argv.indexOf("--filter")
+  const filterIndex = argv.indexOf("--filter");
   if (filterIndex !== -1 && argv[filterIndex + 1]) {
-    filter = argv[filterIndex + 1].toLowerCase()
+    filter = argv[filterIndex + 1].toLowerCase();
   }
 
-  let resolveFrom = null
-  const resolveFromIndex = argv.indexOf("--resolve-from")
+  let resolveFrom = null;
+  const resolveFromIndex = argv.indexOf("--resolve-from");
   if (resolveFromIndex !== -1 && argv[resolveFromIndex + 1]) {
-    resolveFrom = argv[resolveFromIndex + 1]
+    resolveFrom = argv[resolveFromIndex + 1];
+  }
+
+  let remoteVersion = null;
+  const remoteVersionIndex = argv.indexOf("--remote-version");
+  if (remoteVersionIndex !== -1 && argv[remoteVersionIndex + 1]) {
+    remoteVersion = argv[remoteVersionIndex + 1];
   }
 
-  let kindFilter = null
-  const kindIndex = argv.indexOf("--kind")
+  let kindFilter = null;
+  const kindIndex = argv.indexOf("--kind");
   if (kindIndex !== -1 && argv[kindIndex + 1]) {
-    kindFilter = argv[kindIndex + 1].split(",").map((k) => k.trim().toLowerCase())
+    kindFilter = argv[kindIndex + 1]
+      .split(",")
+      .map((k) => k.trim().toLowerCase());
   }
 
-  let depth = 1
-  const depthIndex = argv.indexOf("--depth")
+  let depth = 1;
+  const depthIndex = argv.indexOf("--depth");
   if (depthIndex !== -1 && argv[depthIndex + 1]) {
-    depth = parseInt(argv[depthIndex + 1], 10)
+    depth = parseInt(argv[depthIndex + 1], 10);
     if (isNaN(depth) || depth < 0 || depth > 5) {
-      depth = 1
+      depth = 1;
     }
   }
 
-  let jsdocQuery = null
+  let jsdocQuery = null;
   if (
     jsdocSymbols ||
     jsdocSections ||
@@ -90,46 +155,233 @@ function parseCliArgs(argv) {
     jsdocTruncate ||
     jsdocMaxLen !== null
   ) {
-    const symbols = jsdocSymbols ? jsdocSymbols.split(",").map((s) => s.trim()).filter(Boolean) : undefined
-    const sections = jsdocSections ? jsdocSections.split(",").map((s) => s.trim()).filter(Boolean) : undefined
-    const tagsInclude = jsdocTagsInclude ? jsdocTagsInclude.split(",").map((s) => s.trim()).filter(Boolean) : undefined
-    const tagsExclude = jsdocTagsExclude ? jsdocTagsExclude.split(",").map((s) => s.trim()).filter(Boolean) : undefined
+    const symbols = jsdocSymbols
+      ? jsdocSymbols
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : undefined;
+    const sections = jsdocSections
+      ? jsdocSections
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : undefined;
+    const tagsInclude = jsdocTagsInclude
+      ? jsdocTagsInclude
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : undefined;
+    const tagsExclude = jsdocTagsExclude
+      ? jsdocTagsExclude
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : undefined;
     jsdocQuery = {
       symbols: symbols && symbols.length === 1 ? symbols[0] : symbols,
       sections,
-      tags: tagsInclude || tagsExclude ? { include: tagsInclude, exclude: tagsExclude } : undefined,
+      tags:
+        tagsInclude || tagsExclude
+          ? { include: tagsInclude, exclude: tagsExclude }
+          : undefined,
       mode: jsdoc === "compact" || jsdoc === "full" ? jsdoc : undefined,
       maxLen: jsdocMaxLen ?? undefined,
       truncate: jsdocTruncate ?? undefined,
-    }
+    };
   }
 
-  return { target, filter, showTypes, kindFilter, depth, resolveFrom, jsdoc, jsdocOutput, jsdocQuery }
+  return {
+    target,
+    filter,
+    showTypes,
+    includeDocs,
+    includeExamples,
+    remote,
+    remoteVersion,
+    kindFilter,
+    depth,
+    resolveFrom,
+    jsdoc,
+    jsdocOutput,
+    jsdocQuery,
+    // New options
+    format,
+    listSections,
+    docsSections,
+    search,
+    maxExports,
+    maxProps,
+    maxExamples,
+    analyzeSource,
+    sourceMaxFiles,
+    sourceIncludeBody,
+  };
+}
+
+function parseDiffArgs(argv) {
+  const packageName = argv[0];
+
+  let from = "installed";
+  const fromIndex = argv.indexOf("--from");
+  if (fromIndex !== -1 && argv[fromIndex + 1]) {
+    from = argv[fromIndex + 1];
+  }
+
+  let to = "latest";
+  const toIndex = argv.indexOf("--to");
+  if (toIndex !== -1 && argv[toIndex + 1]) {
+    to = argv[toIndex + 1];
+  }
+
+  let filter = null;
+  const filterIndex = argv.indexOf("--filter");
+  if (filterIndex !== -1 && argv[filterIndex + 1]) {
+    filter = argv[filterIndex + 1];
+  }
+
+  let format = "text";
+  const formatIndex = argv.indexOf("--format");
+  if (formatIndex !== -1 && argv[formatIndex + 1]) {
+    format = argv[formatIndex + 1].toLowerCase();
+  }
+
+  const includeSource = argv.includes("--include-source");
+  const includeChangelog = !argv.includes("--no-changelog");
+  const verbose = argv.includes("--verbose");
+  const noColor = argv.includes("--no-color");
+
+  let projectDir = null;
+  const projectDirIndex = argv.indexOf("--project-dir");
+  if (projectDirIndex !== -1 && argv[projectDirIndex + 1]) {
+    projectDir = argv[projectDirIndex + 1];
+  }
+
+  return {
+    packageName,
+    from,
+    to,
+    filter,
+    format,
+    includeSource,
+    includeChangelog,
+    verbose,
+    noColor,
+    projectDir,
+  };
 }
 
 function usage() {
   console.error(
-    "Uso: deplens <pacote> [filtro] [--filter VALUE] [--types] [--jsdoc off|compact|full] [--jsdoc-output off|section|inline|only] [--jsdoc-symbol NAME|glob|/re/] [--jsdoc-sections summary,params,returns,tags] [--jsdoc-tags t1,t2] [--jsdoc-tags-exclude t1,t2] [--jsdoc-truncate none|sentence|word] [--jsdoc-max-len N] [--kind function,class,...] [--depth N] [--resolve-from DIR]"
-  )
+    "Uso:\n" +
+      "  deplens <pacote> [filtro] [opções]\n" +
+      "  deplens inspect <pacote> [filtro] [opções]\n" +
+      "  deplens diff <pacote> [opções]\n\n" +
+      "Opções (inspect):\n" +
+      "  --filter VALUE         Filter exports by name\n" +
+      "  --search QUERY         Semantic search (token matching + JSDoc)\n" +
+      "  --types                Show type signatures from .d.ts\n" +
+      "  --docs                 Include README preview\n" +
+      "  --list-sections        List available README sections\n" +
+      "  --docs-sections S1,S2  Extract specific README sections\n" +
+      "  --examples             Include code examples\n" +
+      "  --format text|json     Output format (default: text)\n" +
+      "  --remote               Download package to cache\n" +
+      "  --remote-version V     Version for remote download\n" +
+      "  --max-exports N        Max exports to show (default: 100)\n" +
+      "  --max-props N          Max props per object (default: 10)\n" +
+      "  --max-examples N       Max examples to show (default: 10)\n" +
+      "  --analyze-source       Analyze source for complexity\n" +
+      "  --source-max-files N   Max source files to analyze\n" +
+      "  --source-include-body  Include function body snippets\n" +
+      "  --kind f,c,...         Filter by kind (function,class,object,constant)\n" +
+      "  --depth N              Object inspection depth (0-5)\n" +
+      "  --resolve-from DIR     Base directory for module resolution\n" +
+      "  --jsdoc off|compact|full  JSDoc mode\n" +
+      "  --jsdoc-output off|section|inline|only  JSDoc output mode\n" +
+      "\nOpções (diff):\n" +
+      "  --from VERSION         Base version (default: installed)\n" +
+      "  --to VERSION           Target version (default: latest)\n" +
+      "  --filter VALUE         Filter exports by name\n" +
+      "  --format text|json     Output format (default: text)\n" +
+      "  --include-source       Compare source complexity\n" +
+      "  --no-changelog         Skip changelog parsing\n" +
+      "  --verbose              Show detailed changes\n" +
+      "  --no-color             Disable ANSI colors\n" +
+      "  --project-dir DIR      Base directory for installed version\n",
+  );
 }
 
-const parsed = parseCliArgs(process.argv.slice(2))
-if (!parsed.target) {
-  usage()
-  process.exit(1)
-}
+const argv = process.argv.slice(2);
+const command =
+  argv[0] === "diff" || argv[0] === "inspect" ? argv[0] : "inspect";
+const commandArgs =
+  command === "inspect" && argv[0] !== "inspect" ? argv : argv.slice(1);
+
+const parsed =
+  command === "diff"
+    ? parseDiffArgs(commandArgs)
+    : parseInspectArgs(commandArgs);
+if (command === "diff") {
+  if (!parsed.packageName) {
+    usage();
+    process.exit(1);
+  }
+
+  const output = await runDiff({
+    package: parsed.packageName,
+    from: parsed.from,
+    to: parsed.to,
+    projectDir: parsed.projectDir || process.cwd(),
+    includeSource: parsed.includeSource,
+    includeChangelog: parsed.includeChangelog,
+    filter: parsed.filter,
+    format: parsed.format,
+    verbose: parsed.verbose,
+    colors: !parsed.noColor,
+  });
+
+  if (typeof output?.output === "string" && output.output.length > 0) {
+    process.stdout.write(output.output);
+  }
+} else {
+  if (!parsed.target) {
+    usage();
+    process.exit(1);
+  }
+
+  const output = await runInspect({
+    target: parsed.target,
+    filter: parsed.filter,
+    showTypes: parsed.showTypes,
+    includeDocs: parsed.includeDocs,
+    includeExamples: parsed.includeExamples,
+    remote: parsed.remote,
+    remoteVersion: parsed.remoteVersion,
+    jsdoc: parsed.jsdoc,
+    jsdocOutput: parsed.jsdocOutput,
+    jsdocQuery: parsed.jsdocQuery,
+    kind: parsed.kindFilter,
+    depth: parsed.depth,
+    resolveFrom: parsed.resolveFrom,
+    // New options
+    format: parsed.format,
+    listSections: parsed.listSections,
+    docsSections: parsed.docsSections,
+    search: parsed.search,
+    maxExports: parsed.maxExports,
+    maxProps: parsed.maxProps,
+    maxExamples: parsed.maxExamples,
+    analyzeSource: parsed.analyzeSource,
+    sourceMaxFiles: parsed.sourceMaxFiles,
+    sourceIncludeBody: parsed.sourceIncludeBody,
+    cwd: process.cwd(),
+    write: console.log,
+    writeError: console.error,
+  });
 
-runInspect({
-  target: parsed.target,
-  filter: parsed.filter,
-  showTypes: parsed.showTypes,
-  jsdoc: parsed.jsdoc,
-  jsdocOutput: parsed.jsdocOutput,
-  jsdocQuery: parsed.jsdocQuery,
-  kind: parsed.kindFilter,
-  depth: parsed.depth,
-  resolveFrom: parsed.resolveFrom,
-  cwd: process.cwd(),
-  write: console.log,
-  writeError: console.error,
-})
+  if (typeof output === "string" && output.length > 0) {
+    process.stdout.write(output);
+  }
+}