@myooken/license-output 0.1.0 → 0.2.0

package/README.md

@@ -12,58 +12,66 @@ It generates two files: `THIRD-PARTY-LICENSE.md` (main content) and `THIRD-PARTY
 - **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**.
+CLI command: `third-party-license`
 
 ### Usage
 
 #### Run without installing (recommended)
 
 ```bash
-npx --package=@myooken/license-output -- third-party-notices [args...]
+npx --package=@myooken/license-output -- third-party-license
 ```
 
 #### Run via npm exec
 
 ```bash
-npm exec --package=@myooken/license-output -- third-party-notices [args...]
+npm exec --package=@myooken/license-output -- third-party-license
 ```
 
 #### Install globally
 
 ```bash
 npm i -g @myooken/license-output
-third-party-notices [args...]
+third-party-license
 ```
 
+### 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`        |
+| `--recreate`           | Regenerate files from current `node_modules` only (drops removed packages)  | `true` (default)                |
+| `--update`             | Merge with existing outputs, keep removed packages, and mark their presence | `false`                        |
+| `--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**.
+> Packages in both files are sorted by name@version; `--update` keeps entries for packages no longer in `node_modules` and annotates their usage status.
+
 ### Examples
 
 ```bash
 # Default (both files)
-third-party-notices
+third-party-license
+
+# Update existing files without dropping removed packages
+third-party-license --update
 
 # Custom node_modules path
-third-party-notices --node-modules ./path/to/node_modules
+third-party-license --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
+third-party-license --review
+third-party-license --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
+third-party-license --license
+third-party-license --license ./out/THIRD-PARTY-LICENSE.md
 
-# Exit with code 1 when something is missing
-third-party-notices --fail-on-missing
+# Exit with code 1 when something is missing (with --fail-on-missing)
+third-party-license --fail-on-missing
 ```
 
 ### Programmatic API
@@ -76,20 +84,25 @@ const result = await collectThirdPartyLicenses({
   outFile: "./THIRD-PARTY-LICENSE.md",
   reviewFile: "./THIRD-PARTY-LICENSE-REVIEW.md",
   failOnMissing: false,
+  // mode: "update", // keep packages missing from node_modules when updating files
 });
 
 console.log(result.mainContent);
 console.log(result.reviewContent);
 ```
 
+Outputs are sorted by package key. Use `mode: "update"` to merge with existing files and keep packages that are no longer in `node_modules`, with their usage shown in both outputs.
+
 ### Output overview
 
 - **THIRD-PARTY-LICENSE.md**
   - List of packages
   - Source / License info
   - Full LICENSE/NOTICE/COPYING texts
+  - Usage line shows whether the package is present in the current `node_modules`
 - **THIRD-PARTY-LICENSE-REVIEW.md**
   - Review-oriented checklist
+  - Usage-aware status (present / not found) for each package
   - **Missing summary** section
 
 ### How it differs from typical npm license tools (general view)
@@ -105,5 +118,8 @@ console.log(result.reviewContent);
 
 ### Notes
 
+- Scans all packages under `node_modules` (including nested dependencies); license files are searched only in each package root directory.
+- Exit code 0: success.
+- Exit code 1: missing license files when `--fail-on-missing` is set, or `node_modules` not found.
 - Throws an error if `node_modules` does not exist.
 - Missing `license` or `repository` fields are flagged in the review file.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myooken/license-output",
-  "version": "0.1.0",
-  "description": "Generate THIRD-PARTY-NOTICES markdown by scanning licenses in node_modules.",
+  "version": "0.2.0",
+  "description": "Generate third-party-license markdown by scanning licenses in node_modules.",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -25,7 +25,7 @@
     ".": "./src/core.js"
   },
   "bin": {
-    "third-party-notices": "./src/cli.js"
+    "third-party-license": "./src/cli.js"
   },
   "files": [
     "src",

package/src/cli.js

@@ -32,6 +32,10 @@ function parseArgs(argv) {
         args.outFile = file;
         i += 1;
       }
+    } else if (a === "--recreate") {
+      args.mode = "recreate";
+    } else if (a === "--update") {
+      args.mode = "update";
     } else if (a === "--fail-on-missing") {
       args.failOnMissing = true;
     } else if (a === "-h" || a === "--help") {
@@ -66,7 +70,7 @@ function applyOutputMode(mode, args) {
 
 function showHelp() {
   console.log(`Usage:
-  third-party-notices [--node-modules <dir>] [--review [file]] [--license [file]] [--fail-on-missing]
+  third-party-license [--node-modules <dir>] [--review [file]] [--license [file]] [--recreate|--update] [--fail-on-missing]
 `);
 }
 
@@ -129,7 +133,7 @@ function isCliExecution() {
   if (resolvedArg === self) return true;
 
   const base = path.basename(resolvedArg).toLowerCase();
-  if (base === "third-party-notices" || base === "third-party-notices.cmd") {
+  if (base === "third-party-license" || base === "third-party-license.cmd") {
     return true;
   }
   if (resolvedArg.includes(`${path.sep}.bin${path.sep}`)) return true;

package/src/constants.js

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

package/src/core.js

@@ -3,27 +3,39 @@ 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";
+import { makeAnchorId, uniqSorted } from "./fs-utils.js";
+import {
+  parseExistingMainFile,
+  parseExistingReviewFile,
+} from "./existing.js";
 
-// 警告の出力先（デフォルトは console）
+// Default warning handler (prints to console)
 const defaultWarn = (msg) => {
   console.warn(`warning: ${msg}`);
 };
 
-// 公開API: ライセンス情報を収集し、マークダウン文字列を返す
+// Public API: scan licenses and render markdown
 export async function collectThirdPartyLicenses(options = {}) {
   const opts = normalizeOptions(options);
-  await assertNodeModulesExists(opts.nodeModules); // node_modules が無ければ即エラー
+  await assertNodeModulesExists(opts.nodeModules); // fail fast when node_modules is missing
 
-  const result = await gatherPackages(opts);
+  const scanResult = await gatherPackages(opts);
+  const presentPackages = withPresentUsage(scanResult.packages);
 
-  const mainContent = renderMain(result.packages, opts);
+  const packages =
+    opts.mode === "update"
+      ? await mergeWithExistingOutputs(presentPackages, opts)
+      : presentPackages;
+
+  const sortedPackages = sortPackages(packages);
+
+  const mainContent = renderMain(sortedPackages, opts);
   const reviewContent = renderReview(
-    result.packages,
+    sortedPackages,
     opts,
-    result.missingFiles,
-    result.missingSource,
-    result.missingLicenseField
+    scanResult.missingFiles,
+    scanResult.missingSource,
+    scanResult.missingLicenseField
   );
 
   return {
@@ -31,10 +43,10 @@ export async function collectThirdPartyLicenses(options = {}) {
     reviewContent,
     options: opts,
     stats: {
-      packages: result.seenCount,
-      missingFiles: uniqSorted(result.missingFiles),
-      missingSource: uniqSorted(result.missingSource),
-      missingLicenseField: uniqSorted(result.missingLicenseField),
+      packages: scanResult.seenCount,
+      missingFiles: uniqSorted(scanResult.missingFiles),
+      missingSource: uniqSorted(scanResult.missingSource),
+      missingLicenseField: uniqSorted(scanResult.missingLicenseField),
     },
   };
 }
@@ -54,13 +66,87 @@ function normalizeOptions(options) {
     writeMain: options.writeMain ?? true,
     writeReview: options.writeReview ?? true,
     warn: options.onWarn ?? defaultWarn,
+    mode: normalizeMode(options.mode),
   };
 }
 
+function normalizeMode(mode) {
+  const m = typeof mode === "string" ? mode.toLowerCase() : "";
+  return m === "update" ? "update" : DEFAULT_OPTIONS.mode;
+}
+
 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}`);
   }
 }
+
+function withPresentUsage(packages) {
+  return packages.map((pkg) => ({
+    ...pkg,
+    usage: "present",
+    notes: "",
+  }));
+}
+
+async function mergeWithExistingOutputs(currentPackages, opts) {
+  const [existingMain, existingReview] = await Promise.all([
+    parseExistingMainFile(opts.outFile),
+    parseExistingReviewFile(opts.reviewFile),
+  ]);
+
+  // Start with previously known packages as "missing" (not found in this scan)
+  const merged = new Map();
+  for (const [key, prevReview] of existingReview.entries()) {
+    const prevMain = existingMain.get(key);
+    merged.set(key, toMissingPackage(key, prevMain, prevReview));
+  }
+  for (const [key, prevMain] of existingMain.entries()) {
+    if (!merged.has(key)) {
+      merged.set(key, toMissingPackage(key, prevMain, null));
+    }
+  }
+
+  // Override with current scan (present in node_modules), keeping previous notes when available
+  for (const pkg of currentPackages) {
+    const prevReview = existingReview.get(pkg.key);
+    merged.set(pkg.key, toPresentPackage(pkg, prevReview));
+  }
+
+  return [...merged.values()];
+}
+
+function toPresentPackage(pkg, prevReview) {
+  return {
+    ...pkg,
+    usage: "present",
+    notes: prevReview?.notes ?? "",
+  };
+}
+
+function toMissingPackage(key, prevMain, prevReview) {
+  return {
+    key,
+    anchor: makeAnchorId(key),
+    source: prevMain?.source ?? prevReview?.source ?? null,
+    license: prevMain?.license ?? prevReview?.license ?? null,
+    fileNames: deriveFileNames(prevMain, prevReview),
+    flags: [],
+    licenseTexts: prevMain?.licenseTexts ?? [],
+    usage: "missing",
+    notes: prevReview?.notes ?? "",
+  };
+}
+
+function deriveFileNames(prevMain, prevReview) {
+  const names =
+    (prevMain?.fileNames && prevMain.fileNames.length > 0
+      ? prevMain.fileNames
+      : prevReview?.fileNames) ?? [];
+  return uniqSorted(names);
+}
+
+function sortPackages(packages) {
+  return [...packages].sort((a, b) => a.key.localeCompare(b.key));
+}

package/src/existing.js

@@ -0,0 +1,162 @@
+import fsp from "node:fs/promises";
+import { makeAnchorId, uniqSorted } from "./fs-utils.js";
+
+export async function parseExistingMainFile(filePath) {
+  const content = await readFileSafe(filePath);
+  if (!content) return new Map();
+
+  const map = new Map();
+  for (const { key, body } of splitPackageBlocks(content)) {
+    map.set(key, parseMainBlock(key, body));
+  }
+  return map;
+}
+
+export async function parseExistingReviewFile(filePath) {
+  const content = await readFileSafe(filePath);
+  if (!content) return new Map();
+
+  const map = new Map();
+  for (const { key, body } of splitPackageBlocks(content)) {
+    map.set(key, parseReviewBlock(key, body));
+  }
+  return map;
+}
+
+async function readFileSafe(filePath) {
+  try {
+    return await fsp.readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function splitPackageBlocks(content) {
+  const blocks = [];
+  const headingRe = /^##\s+(.+)$/gm;
+  let match;
+  let current = null;
+
+  while ((match = headingRe.exec(content))) {
+    if (current) {
+      blocks.push({
+        key: current.key,
+        body: content.slice(current.start, match.index),
+      });
+    }
+    current = { key: match[1].trim(), start: match.index };
+  }
+
+  if (current) {
+    blocks.push({
+      key: current.key,
+      body: content.slice(current.start),
+    });
+  }
+
+  return blocks;
+}
+
+function parseMainBlock(key, body) {
+  const source = pickLine(body, /^- Source:\s*(.+)$/m);
+  const license = pickLine(body, /^- License:\s*(.+)$/m);
+  const usage = pickLine(body, /^- Usage:\s*(.+)$/m);
+
+  const licenseTexts = [];
+  const licRe = /###\s+(.+?)\s*\r?\n```text\r?\n([\s\S]*?)```/g;
+  let licMatch;
+  while ((licMatch = licRe.exec(body))) {
+    licenseTexts.push({
+      name: licMatch[1].trim(),
+      text: licMatch[2],
+    });
+  }
+
+  const fileNames = [];
+  for (const m of body.matchAll(/^- (.+)$/gm)) {
+    const val = m[1].trim();
+    if (
+      val.startsWith("Source:") ||
+      val.startsWith("License:") ||
+      val.startsWith("Usage:")
+    ) {
+      continue;
+    }
+    if (val.startsWith("(no LICENSE/NOTICE/COPYING files)")) continue;
+    fileNames.push(val);
+  }
+
+  const derivedNames =
+    fileNames.length > 0 ? fileNames : licenseTexts.map((x) => x.name);
+
+  return {
+    key,
+    anchor: makeAnchorId(key),
+    source: source || null,
+    license: license || null,
+    fileNames: uniqSorted(derivedNames),
+    flags: [],
+    licenseTexts,
+    usage: usage || "",
+    notes: "",
+  };
+}
+
+function parseReviewBlock(key, body) {
+  const source = pickLine(body, /^- Source:\s*(.+)$/m);
+  const license = pickLine(body, /^- License:\s*(.+)$/m);
+
+  const lines = body.split(/\r?\n/);
+  const fileNames = [];
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.startsWith("- Files:")) continue;
+
+    let j = i + 1;
+    while (j < lines.length && lines[j].startsWith("  -")) {
+      fileNames.push(lines[j].replace(/^  -\s*/, ""));
+      j += 1;
+    }
+    i = j - 1;
+  }
+
+  let notes = "";
+  const notesIdx = lines.findIndex((l) => l.startsWith("- Notes:"));
+  if (notesIdx !== -1) {
+    const noteLines = [];
+    for (let i = notesIdx + 1; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (line.startsWith("## ")) break;
+      if (line.startsWith("- ")) break;
+      if (line.startsWith("---")) break;
+      if (line.startsWith("  ")) {
+        noteLines.push(line.slice(2));
+        continue;
+      }
+      if (line.trim() === "") {
+        noteLines.push("");
+        continue;
+      }
+      break;
+    }
+    notes = noteLines.join("\n").replace(/\s+$/, "");
+  }
+
+  return {
+    key,
+    anchor: makeAnchorId(key),
+    source: source || null,
+    license: license || null,
+    fileNames: uniqSorted(fileNames),
+    flags: [],
+    licenseTexts: [],
+    usage: "",
+    notes,
+  };
+}
+
+function pickLine(body, re) {
+  const m = body.match(re);
+  return m ? m[1].trim() : "";
+}

package/src/render.js

@@ -17,8 +17,10 @@ export function renderMain(packages, opts) {
     push(`## ${pkg.key}`);
     push(`- Source: ${pkg.source ?? "(missing)"}`);
     push(`- License: ${pkg.license ?? "(missing)"}`);
+    push(`- Usage: ${describeUsage(pkg.usage)}`);
 
-    if (pkg.fileNames.length === 0) {
+    const fileNames = pkg.fileNames ?? [];
+    if (fileNames.length === 0) {
       push("- (no LICENSE/NOTICE/COPYING files)");
       push("");
       push("_No LICENSE/NOTICE/COPYING file found in package directory._");
@@ -26,10 +28,10 @@ export function renderMain(packages, opts) {
       continue;
     }
 
-    for (const n of pkg.fileNames) push(`- ${n}`);
+    for (const n of fileNames) push(`- ${n}`);
     push("");
 
-    for (const lic of pkg.licenseTexts) {
+    for (const lic of pkg.licenseTexts ?? []) {
       push(`### ${lic.name}`);
       push("```text");
       push(mdSafeText(lic.text).replace(/\s+$/, ""));
@@ -66,19 +68,26 @@ export function renderReview(
     push(`- License: ${it.license ?? "(missing)"}`);
 
     push("- Files:");
-    if (it.fileNames.length === 0) {
+    const fileNames = it.fileNames ?? [];
+    if (fileNames.length === 0) {
       push("  - (none)");
     } else {
-      for (const f of it.fileNames) push(`  - ${f}`);
+      for (const f of fileNames) push(`  - ${f}`);
     }
 
-    if (it.flags.length === 0) {
-      push("- Status: Check manually");
-    } else {
-      push(`- Status: ${it.flags.join(" / ")}`);
-    }
+    const statusParts = [describeUsage(it.usage), ...(it.flags ?? [])].filter(
+      Boolean
+    );
+    const status =
+      statusParts.length === 0 ? "Check manually" : statusParts.join(" / ");
+    push(`- Status: ${status}`);
 
     push("- Notes:");
+    if (it.notes && it.notes.length > 0) {
+      for (const line of it.notes.split(/\r?\n/)) {
+        push(`  ${line}`);
+      }
+    }
     push("");
   }
 
@@ -102,3 +111,10 @@ export function renderReview(
 
   return lines.join(os.EOL) + os.EOL;
 }
+
+function describeUsage(usage) {
+  if (usage === "missing") {
+    return "Not found in node_modules (kept from previous output)";
+  }
+  return "Present in node_modules";
+}