@myooken/license-output 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 myooken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# Third-Party License Output for node_modules
+
+### What is this?
+
+A tool to scan `node_modules` and **output third-party licenses in Markdown**.  
+It generates two files: `THIRD-PARTY-LICENSE.md` (main content) and `THIRD-PARTY-LICENSE-REVIEW.md` (review checklist).
+
+### Highlights
+
+- **ESM / Node.js 18+**, zero dependencies
+- **Outputs full license texts** from LICENSE/NOTICE/COPYING files
+- **Review file** flags missing Source / license / license files
+- `--fail-on-missing` supports CI enforcement
+
+### Options
+
+| Option                 | Description                                            | Default                         |
+| ---------------------- | ------------------------------------------------------ | ------------------------------- |
+| `--node-modules <dir>` | Path to `node_modules`                                 | `node_modules`                  |
+| `--review [file]`      | Write review file only; optional filename              | `THIRD-PARTY-LICENSE-REVIEW.md` |
+| `--license [file]`     | Write main file only; optional filename                | `THIRD-PARTY-LICENSE.md`        |
+| `--fail-on-missing`    | Exit with code 1 if LICENSE/NOTICE/COPYING are missing | `false`                         |
+| `-h`, `--help`         | Show help                                              | -                               |
+
+> If neither `--review` nor `--license` is specified, **both files are generated**.
+
+### Usage
+
+#### Run without installing (recommended)
+
+```bash
+npx --package=@myooken/license-output -- third-party-notices [args...]
+```
+
+#### Run via npm exec
+
+```bash
+npm exec --package=@myooken/license-output -- third-party-notices [args...]
+```
+
+#### Install globally
+
+```bash
+npm i -g @myooken/license-output
+third-party-notices [args...]
+```
+
+### Examples
+
+```bash
+# Default (both files)
+third-party-notices
+
+# Custom node_modules path
+third-party-notices --node-modules ./path/to/node_modules
+
+# Review-only output (optional filename)
+third-party-notices --review
+third-party-notices --review ./out/THIRD-PARTY-LICENSE-REVIEW.md
+
+# Main-only output (optional filename)
+third-party-notices --license
+third-party-notices --license ./out/THIRD-PARTY-LICENSE.md
+
+# Exit with code 1 when something is missing
+third-party-notices --fail-on-missing
+```
+
+### Programmatic API
+
+```js
+import { collectThirdPartyLicenses } from "@myooken/license-output";
+
+const result = await collectThirdPartyLicenses({
+  nodeModules: "./node_modules",
+  outFile: "./THIRD-PARTY-LICENSE.md",
+  reviewFile: "./THIRD-PARTY-LICENSE-REVIEW.md",
+  failOnMissing: false,
+});
+
+console.log(result.mainContent);
+console.log(result.reviewContent);
+```
+
+### Output overview
+
+- **THIRD-PARTY-LICENSE.md**
+  - List of packages
+  - Source / License info
+  - Full LICENSE/NOTICE/COPYING texts
+- **THIRD-PARTY-LICENSE-REVIEW.md**
+  - Review-oriented checklist
+  - **Missing summary** section
+
+### How it differs from typical npm license tools (general view)
+
+> Examples: `license-checker`, `license-report`, `license-finder`
+
+- **Focused on bundling full license texts into a single Markdown file**
+  - Many existing tools emphasize JSON/CSV reports; this tool emphasizes **ready-to-share license documents**.
+- **Separate review file** to track missing metadata
+  - Easier to integrate into audit workflows.
+- **ESM / Node.js 18+ with no dependencies**
+  - Simple runtime requirements.
+
+### Notes
+
+- Throws an error if `node_modules` does not exist.
+- Missing `license` or `repository` fields are flagged in the review file.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@myooken/license-output",
+  "version": "0.1.0",
+  "description": "Generate THIRD-PARTY-NOTICES markdown by scanning licenses in node_modules.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/myooken/collect-node-modules-licenses.git"
+  },
+  "homepage": "https://github.com/myooken/collect-node-modules-licenses#readme",
+  "bugs": {
+    "url": "https://github.com/myooken/collect-node-modules-licenses/issues"
+  },
+  "keywords": [
+    "license",
+    "third-party",
+    "notices",
+    "node_modules",
+    "oss",
+    "compliance",
+    "cli"
+  ],
+  "exports": {
+    ".": "./src/core.js"
+  },
+  "bin": {
+    "third-party-notices": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// CLIエントリーポイント（引数パースとファイル出力を担当）
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectThirdPartyLicenses, DEFAULT_OPTIONS } from "./core.js";
+
+// 引数パース: --review / --license は最後に指定されたものを優先し、直後の値があれば出力ファイル名として扱う
+function parseArgs(argv) {
+  const args = { ...DEFAULT_OPTIONS };
+  let outputMode = "both"; // "both" | "review" | "license"
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--node-modules" || a === "--nodeModules") {
+      const dir = optionalValue(argv, i + 1);
+      if (dir) {
+        args.nodeModules = dir;
+        i += 1;
+      }
+    } else if (a === "--review") {
+      outputMode = "review";
+      const file = optionalValue(argv, i + 1);
+      if (file) {
+        args.reviewFile = file;
+        i += 1;
+      }
+    } else if (a === "--license") {
+      outputMode = "license";
+      const file = optionalValue(argv, i + 1);
+      if (file) {
+        args.outFile = file;
+        i += 1;
+      }
+    } else if (a === "--fail-on-missing") {
+      args.failOnMissing = true;
+    } else if (a === "-h" || a === "--help") {
+      showHelp();
+      process.exit(0);
+    }
+  }
+  applyOutputMode(outputMode, args);
+  return args;
+}
+
+// オプションの直後にファイル名があれば取得（次のトークンが別オプションなら無視）
+function optionalValue(argv, idx) {
+  const v = argv[idx];
+  if (!v) return null;
+  return v.startsWith("-") ? null : v;
+}
+
+// 生成対象をまとめて決定（両方／レビューのみ／ライセンスのみ）
+function applyOutputMode(mode, args) {
+  if (mode === "review") {
+    args.writeMain = false;
+    args.writeReview = true;
+  } else if (mode === "license") {
+    args.writeMain = true;
+    args.writeReview = false;
+  } else {
+    args.writeMain = true;
+    args.writeReview = true;
+  }
+}
+
+function showHelp() {
+  console.log(`Usage:
+  third-party-notices [--node-modules <dir>] [--review [file]] [--license [file]] [--fail-on-missing]
+`);
+}
+
+async function ensureParentDir(filePath) {
+  const dir = path.dirname(filePath);
+  await fsp.mkdir(dir, { recursive: true });
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+
+  try {
+    const result = await collectThirdPartyLicenses(args);
+
+    const dirsToEnsure = [];
+    if (result.options.writeMain)
+      dirsToEnsure.push(ensureParentDir(result.options.outFile));
+    if (result.options.writeReview) {
+      dirsToEnsure.push(ensureParentDir(result.options.reviewFile));
+    }
+    await Promise.all(dirsToEnsure);
+
+    const writeTasks = [];
+    if (result.options.writeMain) {
+      writeTasks.push(
+        fsp.writeFile(result.options.outFile, result.mainContent, "utf8")
+      );
+    }
+    if (result.options.writeReview) {
+      writeTasks.push(
+        fsp.writeFile(result.options.reviewFile, result.reviewContent, "utf8")
+      );
+    }
+    await Promise.all(writeTasks);
+
+    if (result.options.writeMain)
+      console.log(`Generated: ${result.options.outFile}`);
+    if (result.options.writeReview)
+      console.log(`Review:    ${result.options.reviewFile}`);
+    console.log(`Packages:  ${result.stats.packages}`);
+    console.log(
+      `Missing LICENSE/NOTICE/COPYING: ${result.stats.missingFiles.length}`
+    );
+
+    if (result.stats.missingFiles.length > 0 && result.options.failOnMissing) {
+      process.exitCode = 1;
+    }
+  } catch (e) {
+    console.error(e?.stack || String(e));
+    process.exit(2);
+  }
+}
+
+function isCliExecution() {
+  // npmの .bin シム経由でも動作するように、実ファイル一致と .bin 配下を許可
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  const self = fileURLToPath(import.meta.url);
+  const resolvedArg = path.resolve(argv1);
+  if (resolvedArg === self) return true;
+
+  const base = path.basename(resolvedArg).toLowerCase();
+  if (base === "third-party-notices" || base === "third-party-notices.cmd") {
+    return true;
+  }
+  if (resolvedArg.includes(`${path.sep}.bin${path.sep}`)) return true;
+  return false;
+}
+
+if (isCliExecution()) {
+  // eslint-disable-next-line unicorn/prefer-top-level-await
+  runCli();
+}

package/src/constants.js

@@ -0,0 +1,11 @@
+// デフォルト値と定数群
+export const DEFAULT_OPTIONS = {
+  nodeModules: "node_modules",
+  outFile: "THIRD-PARTY-LICENSE.md",
+  reviewFile: "THIRD-PARTY-LICENSE-REVIEW.md",
+  failOnMissing: false,
+};
+
+// ライセンスらしいファイル名を検出する正規表現
+export const LICENSE_LIKE_RE =
+  /^(LICEN[CS]E|COPYING|NOTICE)(\..*)?$|^(LICEN[CS]E|COPYING|NOTICE)-/i;

package/src/core.js

@@ -0,0 +1,66 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_OPTIONS } from "./constants.js";
+import { gatherPackages } from "./scan.js";
+import { renderMain, renderReview } from "./render.js";
+import { uniqSorted } from "./fs-utils.js";
+
+// 警告の出力先（デフォルトは console）
+const defaultWarn = (msg) => {
+  console.warn(`warning: ${msg}`);
+};
+
+// 公開API: ライセンス情報を収集し、マークダウン文字列を返す
+export async function collectThirdPartyLicenses(options = {}) {
+  const opts = normalizeOptions(options);
+  await assertNodeModulesExists(opts.nodeModules); // node_modules が無ければ即エラー
+
+  const result = await gatherPackages(opts);
+
+  const mainContent = renderMain(result.packages, opts);
+  const reviewContent = renderReview(
+    result.packages,
+    opts,
+    result.missingFiles,
+    result.missingSource,
+    result.missingLicenseField
+  );
+
+  return {
+    mainContent,
+    reviewContent,
+    options: opts,
+    stats: {
+      packages: result.seenCount,
+      missingFiles: uniqSorted(result.missingFiles),
+      missingSource: uniqSorted(result.missingSource),
+      missingLicenseField: uniqSorted(result.missingLicenseField),
+    },
+  };
+}
+
+export { DEFAULT_OPTIONS } from "./constants.js";
+
+function normalizeOptions(options) {
+  return {
+    nodeModules: path.resolve(
+      options.nodeModules ?? DEFAULT_OPTIONS.nodeModules
+    ),
+    outFile: path.resolve(options.outFile ?? DEFAULT_OPTIONS.outFile),
+    reviewFile: path.resolve(options.reviewFile ?? DEFAULT_OPTIONS.reviewFile),
+    failOnMissing: Boolean(
+      options.failOnMissing ?? DEFAULT_OPTIONS.failOnMissing
+    ),
+    writeMain: options.writeMain ?? true,
+    writeReview: options.writeReview ?? true,
+    warn: options.onWarn ?? defaultWarn,
+  };
+}
+
+async function assertNodeModulesExists(dir) {
+  // node_modules の有無を事前チェックし、無ければ例外を投げてCIなどで失敗させる
+  const stat = await fsp.stat(dir).catch(() => null);
+  if (!stat || !stat.isDirectory()) {
+    throw new Error(`not found node_modules: ${dir}`);
+  }
+}

package/src/fs-utils.js

@@ -0,0 +1,114 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { LICENSE_LIKE_RE } from "./constants.js";
+
+// 文字コードを判定しつつ文字列へデコードする
+export function decodeSmart(buf) {
+  if (buf.length >= 2) {
+    const b0 = buf[0];
+    const b1 = buf[1];
+    if (b0 === 0xff && b1 === 0xfe) {
+      return new TextDecoder("utf-16le").decode(buf.subarray(2));
+    }
+    if (b0 === 0xfe && b1 === 0xff) {
+      const be = buf.subarray(2);
+      const swapped = Buffer.allocUnsafe(be.length);
+      for (let i = 0; i + 1 < be.length; i += 2) {
+        swapped[i] = be[i + 1];
+        swapped[i + 1] = be[i];
+      }
+      return new TextDecoder("utf-16le").decode(swapped);
+    }
+  }
+  if (
+    buf.length >= 3 &&
+    buf[0] === 0xef &&
+    buf[1] === 0xbb &&
+    buf[2] === 0xbf
+  ) {
+    return new TextDecoder("utf-8").decode(buf.subarray(3));
+  }
+
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(buf);
+  } catch {
+    return new TextDecoder("latin1").decode(buf);
+  }
+}
+
+// LICENSE/NOTICE などのライセンス系ファイルを探す
+export async function getLicenseLikeFilesInFolderRoot(pkgDir) {
+  try {
+    const ents = await fsp.readdir(pkgDir, { withFileTypes: true });
+    return ents
+      .filter((e) => e.isFile() && LICENSE_LIKE_RE.test(e.name))
+      .map((e) => path.join(pkgDir, e.name))
+      .sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+  } catch {
+    return [];
+  }
+}
+
+// package.json を深さ優先で探す（node_modules/.bin は除外）
+export async function* walkForPackageJson(rootDir) {
+  const stack = [rootDir];
+
+  while (stack.length) {
+    const dir = stack.pop();
+    if (!dir) continue;
+
+    let ents;
+    try {
+      ents = await fsp.readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const e of ents) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === ".bin") continue;
+        stack.push(full);
+        continue;
+      }
+      if (e.isFile() && e.name === "package.json") {
+        if (full.includes(`${path.sep}.bin${path.sep}`)) continue;
+        yield full;
+      }
+    }
+  }
+}
+
+export async function readPackageJson(pjPath) {
+  try {
+    const txt = await fsp.readFile(pjPath, "utf8");
+    return JSON.parse(txt);
+  } catch {
+    return null;
+  }
+}
+
+// BOM や UTF-16 を考慮してテキストを読み込む
+export async function readTextFileSmart(filePath) {
+  const buf = await fsp.readFile(filePath);
+  return decodeSmart(buf);
+}
+
+export function mdSafeText(s) {
+  return String(s).replace(/```/g, "``\u200b`");
+}
+
+export function uniqSorted(arr) {
+  return [...new Set(arr)].sort();
+}
+
+// アンカー用の安全な ID を作る
+export function makeAnchorId(key) {
+  return (
+    "pkg-" +
+    String(key)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+  );
+}

package/src/render.js

@@ -0,0 +1,104 @@
+import os from "node:os";
+import path from "node:path";
+import { mdSafeText, uniqSorted } from "./fs-utils.js";
+
+// メインのTHIRD-PARTY-LICENSE.mdを描画する
+export function renderMain(packages, opts) {
+  const lines = [];
+  const push = (s = "") => lines.push(s);
+
+  push("# Third-Party Licenses");
+  push("");
+  push(`Generated from: ${opts.nodeModules}`);
+  push("");
+
+  for (const pkg of packages) {
+    push(`<a id="${pkg.anchor}"></a>`);
+    push(`## ${pkg.key}`);
+    push(`- Source: ${pkg.source ?? "(missing)"}`);
+    push(`- License: ${pkg.license ?? "(missing)"}`);
+
+    if (pkg.fileNames.length === 0) {
+      push("- (no LICENSE/NOTICE/COPYING files)");
+      push("");
+      push("_No LICENSE/NOTICE/COPYING file found in package directory._");
+      push("");
+      continue;
+    }
+
+    for (const n of pkg.fileNames) push(`- ${n}`);
+    push("");
+
+    for (const lic of pkg.licenseTexts) {
+      push(`### ${lic.name}`);
+      push("```text");
+      push(mdSafeText(lic.text).replace(/\s+$/, ""));
+      push("```");
+      push("");
+    }
+  }
+
+  return lines.join(os.EOL) + os.EOL;
+}
+
+// レビューファイルを描画する
+export function renderReview(
+  packages,
+  opts,
+  missingFiles,
+  missingSource,
+  missingLicenseField
+) {
+  const lines = [];
+  const push = (s = "") => lines.push(s);
+  const mainBase = path.basename(opts.outFile);
+
+  push("# THIRD-PARTY-LICENSE-REVIEW");
+  push("");
+  push(`Generated from: ${opts.nodeModules}`);
+  push(`Main file: ${mainBase}`);
+  push("");
+
+  for (const it of [...packages].sort((a, b) => a.key.localeCompare(b.key))) {
+    push(`## ${it.key}`);
+    push(`- Main: ${mainBase}#${it.anchor}`);
+    push(`- Source: ${it.source ?? "(missing)"}`);
+    push(`- License: ${it.license ?? "(missing)"}`);
+
+    push("- Files:");
+    if (it.fileNames.length === 0) {
+      push("  - (none)");
+    } else {
+      for (const f of it.fileNames) push(`  - ${f}`);
+    }
+
+    if (it.flags.length === 0) {
+      push("- Status: Check manually");
+    } else {
+      push(`- Status: ${it.flags.join(" / ")}`);
+    }
+
+    push("- Notes:");
+    push("");
+  }
+
+  push("---");
+  push("");
+  push("## Missing summary");
+  push("");
+
+  const writeList = (title, arr) => {
+    push(`### ${title}`);
+    push("");
+    const xs = uniqSorted(arr);
+    if (xs.length === 0) push("- (none)");
+    else for (const x of xs) push(`- ${x}`);
+    push("");
+  };
+
+  writeList("Missing Source", missingSource);
+  writeList("Missing package.json license field", missingLicenseField);
+  writeList("Missing LICENSE/NOTICE/COPYING files", missingFiles);
+
+  return lines.join(os.EOL) + os.EOL;
+}

package/src/scan.js

@@ -0,0 +1,133 @@
+import path from "node:path";
+import {
+  getLicenseLikeFilesInFolderRoot,
+  makeAnchorId,
+  readPackageJson,
+  readTextFileSmart,
+  uniqSorted,
+  walkForPackageJson,
+} from "./fs-utils.js";
+import { getRepositoryUrl } from "./url.js";
+
+// node_modules を走査してパッケージ情報を集約する
+export async function gatherPackages(opts) {
+  const missingFiles = [];
+  const missingSource = [];
+  const missingLicenseField = [];
+  const packages = [];
+  const seen = new Set();
+
+  for await (const pj of walkForPackageJson(opts.nodeModules)) {
+    const pkgDir = path.dirname(pj);
+    const pkg = await readPackageJson(pj);
+    if (!pkg) continue;
+
+    const name =
+      typeof pkg.name === "string" && pkg.name.trim().length > 0
+        ? pkg.name.trim()
+        : "";
+    const version =
+      typeof pkg.version === "string" && pkg.version.trim().length > 0
+        ? pkg.version.trim()
+        : "";
+    if (!name || !version) continue;
+
+    const key = `${name}@${version}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const anchor = makeAnchorId(key);
+    const source = getRepositoryUrl(pkg);
+    const license = formatLicense(pkg.license); // 文字列/オブジェクト/配列すべてを受け付ける
+
+    const flags = [];
+    if (!source) {
+      missingSource.push(key);
+      flags.push("Missing Source");
+      opts.warn(`Unknown source: ${key}`);
+    }
+    if (!license) {
+      missingLicenseField.push(key);
+      flags.push("Missing package.json license");
+      opts.warn(`Missing license in package.json: ${key}`);
+    }
+
+    const licFiles = await getLicenseLikeFilesInFolderRoot(pkgDir);
+    const fileNames = licFiles.map((f) => path.basename(f));
+
+    if (licFiles.length === 0) {
+      missingFiles.push(key);
+      flags.push("Missing LICENSE/NOTICE/COPYING files");
+      opts.warn(`Missing LICENSE/NOTICE/COPYING in ${pkgDir} (${key})`);
+    }
+
+    const licenseTexts =
+      licFiles.length > 0
+        ? await Promise.all(
+            licFiles.map(async (filePath) => ({
+              name: path.basename(filePath),
+              text: await readTextFileSmart(filePath),
+            }))
+          )
+        : [];
+
+    packages.push({
+      key,
+      anchor,
+      source,
+      license,
+      fileNames,
+      flags,
+      licenseTexts,
+    });
+  }
+
+  return {
+    packages,
+    missingFiles: uniqSorted(missingFiles),
+    missingSource: uniqSorted(missingSource),
+    missingLicenseField: uniqSorted(missingLicenseField),
+    seenCount: seen.size,
+  };
+}
+
+// license フィールドを人間可読にまとめる（文字列/オブジェクト/配列に対応）
+function formatLicense(raw) {
+  const parts = [];
+
+  const pushMaybe = (v) => {
+    if (typeof v === "string" && v.trim()) parts.push(v.trim());
+  };
+
+  const handleObj = (licObj) => {
+    if (!licObj || typeof licObj !== "object") return;
+    const type =
+      typeof licObj.type === "string" && licObj.type.trim()
+        ? licObj.type.trim()
+        : "";
+    const url =
+      typeof licObj.url === "string" && licObj.url.trim()
+        ? licObj.url.trim()
+        : "";
+    if (type && url) {
+      parts.push(`${type} (${url})`);
+    } else {
+      pushMaybe(type);
+      pushMaybe(url);
+    }
+  };
+
+  if (typeof raw === "string") {
+    pushMaybe(raw);
+  } else if (Array.isArray(raw)) {
+    for (const lic of raw) {
+      if (typeof lic === "string") pushMaybe(lic);
+      else handleObj(lic);
+    }
+  } else {
+    handleObj(raw);
+  }
+
+  if (parts.length === 0) return null;
+  return [...new Set(parts)].join(" | ");
+}

package/src/url.js

@@ -0,0 +1,8 @@
+// package.jsonのrepositoryからURLを取り出す
+export function getRepositoryUrl(pkg) {
+  const repo = pkg?.repository;
+  if (!repo) return null;
+  if (typeof repo === "string") return repo;
+  if (typeof repo === "object" && typeof repo.url === "string") return repo.url;
+  return null;
+}