pkgviz 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+![issues](https://img.shields.io/github/issues/artiphishle/pkgviz?style=flat-square)
+![PRs](https://img.shields.io/github/issues-pr/artiphishle/pkgviz?style=flat-square)
+
+# Package Visualizer
+
+Tool to visualize packages and their dependencies between each other. This project is inspired by [socomo](https://github.com/gdela/socomo).
+
+Good software architecture starts with matching functional requirements to code structure.
+Visualizing and showing the dependencies of packages in your project is the first step to regain control of your project.
+
+## Prerequisites
+
+Make sure to have PNPM & Node installed, check `package.json` for allowed versions
+
+## Quickstart
+
+```bash
+# 1. Install dependencies
+bun install
+yarn install
+pnpm install
+npm install
+
+# 2. Create your .env file
+cp .env.tpl .env
+
+# 3. Supply the project path to analyze in the .env file
+
+# 4. Run the app
+bun run dev
+yarn run dev
+pnpm run dev
+npm run dev
+```
+
+## Documentation
+
+Find the official documentation at Github Pages here:
+
+[artiphishle.github.io/forensics-docs](https://artiphishle.github.io/forensics-docs/)
+
+## Test
+
+```bash
+# Run tests
+bun run test
+yarn run test
+pnpm run test
+npm run test
+
+# Print Coverage to stdout
+bun run test:cov
+yarn run test:cov
+pnpm run test:cov
+npm run test:cov
+
+# Generate HTML Coverage to 'test/coverage/index.html'
+bun test:cov:html
+yarn test:cov:html
+pnpm test:cov:html
+npm test:cov:html
+```
+
+## Contributing
+
+The list of open source tools to visualize code structure is rather short. Structure101 is now part of Sonar. Don't let paid tools dominate software craft. Join us and contribute to open-source!

package/bin/pkgviz.ts

@@ -0,0 +1,239 @@
+#!/usr/bin/env bun
+
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as net from 'node:net';
+
+type Opts = {
+  out: string;
+  open: boolean;
+  serve: boolean;
+  prod: boolean;
+  port?: number;
+  route: string;
+  waitMs: number;
+  pretty: boolean;
+  verbose: boolean;
+};
+
+function parseArgs(argv: string[]): Opts {
+  const o: Opts = {
+    out: 'audit.json',
+    open: false,
+    serve: false,
+    prod: false,
+    port: undefined,
+    route: '/api/audit/json',
+    waitMs: 90_000,
+    pretty: true,
+    verbose: false,
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-o' || a === '--out') o.out = argv[++i]!;
+    else if (a === '--open') o.open = true;
+    else if (a === '--serve') o.serve = true;
+    else if (a === '--prod') o.prod = true;
+    else if (a === '-p' || a === '--port') o.port = Number(argv[++i]);
+    else if (a === '--route') o.route = argv[++i]!;
+    else if (a === '--wait') o.waitMs = Number(argv[++i]);
+    else if (a === '--no-pretty') o.pretty = false;
+    else if (a === '-v' || a === '--verbose') o.verbose = true;
+    else if (a === '-h' || a === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+  }
+  return o;
+}
+
+function printHelp() {
+  console.log(`
+Usage:
+  bunx @your-scope/myapp [options]
+
+Options:
+  -o, --out <file>   Output file (default: audit.json in caller's cwd)
+  --open             Open the viewer UI after export
+  --serve            Keep server running after export (implies --open unless exporting only)
+  --prod             Use "next start" if a build exists inside the package
+  -p, --port <n>     Port to use (default: find free)
+  --route <path>     API route path (default: /api/audit/json)
+  --wait <ms>        Max wait for server & route (default: 90000)
+  --no-pretty        Write minified JSON
+  -v, --verbose      Verbose logs
+  -h, --help         Show help
+
+Behavior:
+  - Starts the packaged Next.js app from inside this npm package.
+  - Passes ANALYZE_ROOT = process.cwd() (the caller's project root).
+  - Calls GET {route} to retrieve JSON, writes it to --out, then exits (unless --open/--serve).
+`);
+}
+
+function logv(v: boolean, ...args: unknown[]) {
+  if (v) console.log('[myapp]', ...args);
+}
+
+async function findFreePort(preferred?: number): Promise<number> {
+  const tryPort = (port: number) =>
+    new Promise<boolean>(resolvePort => {
+      const srv = net.createServer().once('error', () => resolvePort(false));
+      srv.listen(port, () => srv.close(() => resolvePort(true)));
+    });
+
+  if (preferred && (await tryPort(preferred))) return preferred;
+  for (const port of [3000, 3001, 3030, 4000, 5173, 8787, 0]) {
+    if (await tryPort(port)) {
+      if (port === 0) {
+        const srv = net.createServer();
+        await new Promise<void>(r => srv.listen(0, r));
+        const addr = srv.address();
+        const free = typeof addr === 'object' && addr ? addr.port : 3000;
+        await new Promise<void>(r => srv.close(() => r()));
+        return free;
+      }
+      return port;
+    }
+  }
+  throw new Error('No free port found');
+}
+
+function resolvePackageRoot(): string {
+  // bin is at <pkgRoot>/bin/myapp.ts; step up to package root
+  const here = fileURLToPath(new URL(import.meta.url));
+  return resolve(dirname(here), '..');
+}
+
+function resolveNextBin(pkgRoot: string): string {
+  const local = resolve(
+    pkgRoot,
+    'node_modules',
+    '.bin',
+    process.platform === 'win32' ? 'next.cmd' : 'next'
+  );
+  if (existsSync(local)) return local;
+  return 'next'; // fallback to PATH
+}
+
+async function waitForJson(url: string, timeoutMs: number, verbose: boolean): Promise<unknown> {
+  const start = Date.now();
+  let last: unknown;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url);
+      const ct = res.headers.get('content-type') || '';
+      if (res.ok && ct.includes('application/json')) return await res.json();
+      last = `status=${res.status} ct=${ct}`;
+    } catch (e) {
+      last = e;
+    }
+    await new Promise(r => setTimeout(r, 400));
+    logv(verbose, 'Waiting for JSON…', Date.now() - start + 'ms');
+  }
+  throw new Error(`Timed out waiting for ${url}. Last: ${String(last)}`);
+}
+
+function openBrowser(url: string) {
+  const cmd =
+    process.platform === 'darwin'
+      ? ['open', url]
+      : process.platform === 'win32'
+        ? ['cmd', '/c', 'start', '', url]
+        : ['xdg-open', url];
+  Bun.spawn({ cmd, stdout: 'ignore', stderr: 'ignore' });
+}
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  const callerRoot = process.cwd(); // The project being analyzed
+  const pkgRoot = resolvePackageRoot(); // The packaged Next app root
+  const port = await findFreePort(opts.port);
+  const nextBin = resolveNextBin(pkgRoot);
+  const hasBuild = existsSync(resolve(pkgRoot, '.next'));
+  const mode = opts.prod || hasBuild ? 'start' : 'dev';
+
+  const env = {
+    ...process.env,
+    NEXT_PUBLIC_PROJECT_PATH: callerRoot,
+    PORT: String(port),
+    NEXT_TELEMETRY_DISABLED: '1',
+    NODE_ENV: mode === 'start' ? 'production' : 'development',
+  };
+
+  logv(opts.verbose, `Starting Next (${mode}) at ${pkgRoot} on :${port}`);
+  const child = Bun.spawn({
+    cmd: [nextBin, mode, '-p', String(port)],
+    cwd: pkgRoot,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (opts.verbose) {
+    (async () => {
+      const reader = child.stdout.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          process.stdout.write(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    })();
+    (async () => {
+      const reader = child.stderr.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          process.stderr.write(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    })();
+  }
+
+  const base = `http://localhost:${port}`;
+  const apiUrl = `${base}${opts.route}`;
+
+  // fetch JSON export
+  const data = await waitForJson(apiUrl, opts.waitMs, opts.verbose);
+
+  // write to caller's directory
+  const outPath = resolve(callerRoot, opts.out);
+  await mkdir(dirname(outPath), { recursive: true });
+  const body = opts.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+  await writeFile(outPath, body, 'utf8');
+  console.log(`✓ audit.json written → ${outPath}`);
+
+  const shouldOpen = opts.open || opts.serve;
+  if (shouldOpen) {
+    // Optional: pass cwd also as a query param if your UI reads it
+    const ui = `${base}/?cwd=${encodeURIComponent(callerRoot)}`;
+    openBrowser(ui);
+  }
+
+  if (opts.serve) {
+    console.log(`Serving UI at ${base} (NEXT_PUBLIC_PROJECT_PATH=${callerRoot})`);
+    // don't exit; keep Next running
+    return;
+  }
+
+  // else, terminate Next
+  try {
+    child.kill('SIGTERM');
+    await new Promise(r => setTimeout(r, 800));
+    if (child.exitCode === null) child.kill('SIGKILL');
+  } catch {}
+}
+
+main().catch(err => {
+  console.error('✖ myapp failed:', err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pkgviz",
+  "bin": {
+    "pkgviz": "bin/pkgviz.ts"
+  },
+  "files": [
+    "/bin", ".next"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.14.0",
+    "bun": ">=1.2.18",
+    "npm": ">=10.9.2"
+  },
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "docs:deploy": "bun --filter forensics-docs run deploy",
+    "start": "next start",
+    "lint": "next lint",
+    "format:check": "prettier --check .",
+    "format:write": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,yml,yaml,mjs,cjs,html,css,scss,mdx}\"",
+    "test": "npx @artiphishle/testosterone",
+    "test:cov": "c8 --reporter=text --reporter=text-summary tsx --test",
+    "test:cov:html": "c8 --report-dir=./test/coverage --reporter=html tsx --test"
+  },
+  "dependencies": {
+    "@artiphishle/testosterone": "^0.1.3",
+    "cytoscape": "^3.31.2",
+    "cytoscape-klay": "^3.1.4",
+    "fp-ts": "^2.16.9",
+    "lucide-react": "^0.487.0",
+    "meta": "^2.2.25",
+    "next": "15.4.7",
+    "next-themes": "^0.4.6",
+    "radix-ui": "^1.2.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "xml-js": "^1.6.11"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3",
+    "@tailwindcss/postcss": "^4.1.3",
+    "@types/bun": "^1.2.21",
+    "@types/cytoscape": "^3.21.9",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "autoprefixer": "^10.4.21",
+    "c8": "^10.1.3",
+    "eslint": "^9",
+    "eslint-config-next": "15.3.0",
+    "postcss": "^8.5.3",
+    "prettier": "^3.5.3",
+    "tailwindcss": "^4.1.3",
+    "tailwindcss-cli": "^0.1.2",
+    "tsx": "^4.19.3",
+    "typescript": "^5"
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
+}