@gesslar/licensed 1.0.1 → 1.3.0

package/LICENSE.txt

@@ -0,0 +1,12 @@
+Copyright (C) 2026 by Brian M. Workman bmw@gesslar.dev
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,8 +1,9 @@
 # @gesslar/licensed
 
-A simple CLI tool that generates license documentation for Node.js projects. It
-reads your `package.json`, finds your license file, and outputs a formatted
-markdown section listing your project license and all dependency licenses.
+A simple CLI and API for generating license documentation for Node.js projects.
+It reads your `package.json`, finds your license file, and outputs formatted
+markdown or structured JSON listing your project license and all dependency
+licenses.
 
 ## Installation
 
@@ -16,7 +17,7 @@ Or as a dev dependency:
 npm install --save-dev @gesslar/licensed
 ```
 
-## Usage
+## CLI Usage
 
 Run from your project directory:
 
@@ -30,18 +31,73 @@ includes:
 - Your project's license with a link to the license file
 - A table of all dependencies with their licenses and repository links
 
+## API Usage
+
+You can also use `licensed` programmatically. Pass a
+[`FileObject`](https://github.com/gesslar/toolkit) pointing to a project's
+`package.json` and get back structured JSON.
+
+```js
+import {licensed} from "@gesslar/licensed"
+import {DirectoryObject} from "@gesslar/toolkit"
+
+const cwd = new DirectoryObject("/path/to/project")
+const jsonFile = cwd.getFile("package.json")
+const data = await licensed(jsonFile)
+```
+
+The returned object has the following shape:
+
+```js
+{
+  name: "my-package",        // package name, or null
+  license: "MIT",            // SPDX license identifier, or null
+  licenseFile: "LICENSE.txt", // detected license filename, or null
+  publicDomain: false,       // true for Unlicense, 0BSD, CC0-1.0, MIT-0
+  dependencies: [
+    { name: "lodash", license: "MIT", repo: "https://github.com/lodash/lodash" },
+    { name: "private-pkg", license: "Unknown", repo: null },
+  ]
+}
+```
+
+### Generating Markdown from the API
+
+Use `buildLicenseSection` to turn the data into the same markdown the CLI
+produces:
+
+```js
+import {licensed, buildLicenseSection} from "@gesslar/licensed"
+
+const data = await licensed(jsonFile)
+const markdown = buildLicenseSection({
+  name: data.name,
+  license: data.license,
+  licenseFile: data.licenseFile,
+  depResults: data.dependencies,
+})
+```
+
+### Other Exports
+
+- `cleanUrl(raw)` - Normalizes repository URLs (strips `git+`, `.git`,
+  converts SSH/git protocols to HTTPS)
+- `npmView(dep)` - Queries the npm registry for a package's license and
+  repository URL
+- `buildLicenseSection(options)` - Generates a markdown license section from
+  structured data
+
 ## Requirements
 
 - Node.js v24.13.0 or higher
 
 ## License
 
-licensed is released into the public domain under the
-[Unlicense](UNLICENSE.txt).
+`@gesslar/licensed` is released into the public domain under the [0BSD](LICENSE.txt).
 
 This package includes or depends on third-party components under their own
 licenses:
 
 | Dependency | License |
 | --- | --- |
-| [@gesslar/toolkit](https://github.com/gesslar/toolkit) | Unlicense |
+| [@gesslar/toolkit](https://github.com/gesslar/toolkit) | 0BSD |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gesslar/licensed",
-  "version": "1.0.1",
-  "description": "Simple CLI to produce license copy for README.md",
+  "version": "1.3.0",
+  "description": "CLI and library for generating license sections in README.md",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gesslar/licensed.git"
@@ -11,14 +11,15 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "license": "Unlicense",
+  "license": "0BSD",
   "type": "module",
   "homepage": "https://github.com/gesslar/licensed#readme",
   "scripts": {
     "clean": "rm -rfv ./dist",
     "build": "mkdir -pv ./dist && npm pack --pack-destination ./dist/",
-    "types": "node -e \"require('fs').rmSync('types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",
-    "exec": "node ./src/cli.js",
+    "types": "node -e \"require('fs').rmSync('types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json && sed -i '1{/^#!.*/d}' types/index.d.ts",
+    "exec": "node ./src/index.js",
+    "test": "node --test tests/**/*.test.js",
     "lint": "eslint src/",
     "submit": "npm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
     "update": "npx npm-check-updates -u && npm install",
@@ -28,18 +29,27 @@
     "major": "npm version major"
   },
   "dependencies": {
-    "@gesslar/toolkit": "^3.42.0"
+    "@gesslar/toolkit": "^5.0.1"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^2.0.0",
-    "eslint": "^10.0.2"
+    "@gesslar/uglier": "^2.4.0",
+    "eslint": "^10.2.0",
+    "typescript": "^6.0.2"
   },
   "engines": {
     "node": ">=v24.13.0"
   },
   "files": [
-    "UNLICENSE.txt",
-    "src/**/*.js"
+    "LICENSE.txt",
+    "src/**/*.js",
+    "types/**/*.d.ts",
+    "types/**/*.d.ts.map"
   ],
-  "bin": "./src/cli.js"
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "bin": "./src/index.js"
 }

package/src/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import * as TK from "@gesslar/toolkit"
+import {buildLicenseSection, npmView, PUBLIC_DOMAIN} from "./lib.js"
+import {fileURLToPath} from "node:url"
+
+/**
+ * Generates structured license data for a project.
+ *
+ * @param {import("@gesslar/toolkit").FileObject} jsonFile - A FileObject
+ *   pointing to the project's package.json.
+ * @returns {Promise<{name: string|null, license: string|null,
+ *   licenseFile: string|null, publicDomain: boolean,
+ *   dependencies: Array<{name: string, license: string,
+ *   repo: string|null}>}>} Structured license data.
+ */
+export async function licensed(jsonFile) {
+  const pkg = await jsonFile.loadData()
+  const cwd = jsonFile.parent
+
+  const licenseFileObj =
+    (await cwd.glob("{LICEN[CS]E,UNLICEN[CS]E}{,.txt,.md}"))?.files[0]
+
+  const deps = Object.keys(pkg.dependencies ?? {}).sort()
+  const depResults = deps.length
+    ? await Promise.all(deps.map(dep => npmView(dep)))
+    : []
+
+  return {
+    name: pkg.name ?? null,
+    license: pkg.license ?? null,
+    licenseFile: licenseFileObj?.name ?? null,
+    publicDomain: PUBLIC_DOMAIN.includes(pkg.license),
+    dependencies: depResults,
+  }
+}
+
+export {buildLicenseSection, cleanUrl, npmView} from "./lib.js"
+
+// CLI mode
+if(process.argv[1] === fileURLToPath(import.meta.url)) {
+  const cwd = new TK.DirectoryObject()
+  const jsonFile = cwd.getFile("package.json")
+  const data = await licensed(jsonFile)
+
+  const output = buildLicenseSection({
+    name: data.name,
+    license: data.license,
+    licenseFile: data.licenseFile,
+    depResults: data.dependencies,
+  })
+
+  TK.Glog(output)
+}

package/src/lib.js

@@ -0,0 +1,91 @@
+import {execFile} from "node:child_process"
+import {promisify} from "node:util"
+
+const exec = promisify(execFile)
+
+export const PUBLIC_DOMAIN = ["Unlicense", "0BSD", "CC0-1.0", "MIT-0"]
+
+/**
+ * Cleans a repository URL to a normalized HTTPS form.
+ *
+ * @param {string|null|undefined} raw - The raw repository URL.
+ * @returns {string|null} The cleaned URL or null.
+ */
+export function cleanUrl(raw) {
+  if(!raw)
+    return null
+
+  return raw
+    .replace(/^git\+/, "")
+    .replace(/\.git$/, "")
+    .replace(/^ssh:\/\/git@github\.com/, "https://github.com")
+    .replace(/^git:\/\//, "https://")
+}
+
+/**
+ * Queries npm registry for a dependency's license and repository URL.
+ *
+ * @param {string} dep - The dependency name.
+ * @returns {Promise<{name: string, license: string, repo: string|null}>}
+ *   The dependency info.
+ */
+export async function npmView(dep) {
+  try {
+    const {stdout} = await exec(
+      "npm", ["view", dep, "repository.url", "license", "--json"]
+    )
+    const data = JSON.parse(stdout)
+
+    return {
+      name: dep,
+      license: data.license ?? "Unknown",
+      repo: cleanUrl(data["repository.url"]),
+    }
+  } catch {
+    return {name: dep, license: "Unknown", repo: null}
+  }
+}
+
+/**
+ * Builds the markdown license section lines.
+ *
+ * @param {object} options - The options.
+ * @param {string|undefined} options.name - Package name.
+ * @param {string|undefined} options.license - Package license identifier.
+ * @param {string|undefined} options.licenseFile - License file name.
+ * @param {Array<{name: string, license: string, repo: string|null}>}
+ *   options.depResults - Dependency info results.
+ * @returns {string} The formatted markdown string.
+ */
+export function buildLicenseSection({name, license, licenseFile, depResults}) {
+  const projName = name ?? "this project"
+  const projLicense = license ?? "Unknown"
+
+  const phrase = PUBLIC_DOMAIN.includes(projLicense)
+    ? `\`${projName}\` is released into the public domain under the`
+    : `\`${projName}\` is released under the`
+
+  const lines = [
+    "## License",
+    "",
+    `${phrase} [${projLicense}](${licenseFile ?? "LICENSE"}).`,
+  ]
+
+  if(depResults?.length) {
+    lines.push(
+      "",
+      "This package includes or depends on third-party components under their own",
+      "licenses:",
+      "",
+      "| Dependency | License |",
+      "| --- | --- |",
+    )
+
+    for(const {name: dep, license: depLicense, repo} of depResults) {
+      const link = repo ? `[${dep}](${repo})` : dep
+      lines.push(`| ${link} | ${depLicense} |`)
+    }
+  }
+
+  return lines.join("\n")
+}

package/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generates structured license data for a project.
+ *
+ * @param {import("@gesslar/toolkit").FileObject} jsonFile - A FileObject
+ *   pointing to the project's package.json.
+ * @returns {Promise<{name: string|null, license: string|null,
+ *   licenseFile: string|null, publicDomain: boolean,
+ *   dependencies: Array<{name: string, license: string,
+ *   repo: string|null}>}>} Structured license data.
+ */
+export function licensed(jsonFile: import("@gesslar/toolkit").FileObject): Promise<{
+    name: string | null;
+    license: string | null;
+    licenseFile: string | null;
+    publicDomain: boolean;
+    dependencies: Array<{
+        name: string;
+        license: string;
+        repo: string | null;
+    }>;
+}>;
+export { buildLicenseSection, cleanUrl, npmView } from "./lib.js";
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":";AAMA;;;;;;;;;GASG;AACH,mCAPW,OAAO,kBAAkB,EAAE,UAAU,GAEnC,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAC,IAAI,CAAC;IACzD,WAAW,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC;IAChD,YAAY,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QACnD,IAAI,EAAE,MAAM,GAAC,IAAI,CAAA;KAAC,CAAC,CAAA;CAAC,CAAC,CAqBzB"}

package/types/lib.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cleans a repository URL to a normalized HTTPS form.
+ *
+ * @param {string|null|undefined} raw - The raw repository URL.
+ * @returns {string|null} The cleaned URL or null.
+ */
+export function cleanUrl(raw: string | null | undefined): string | null;
+/**
+ * Queries npm registry for a dependency's license and repository URL.
+ *
+ * @param {string} dep - The dependency name.
+ * @returns {Promise<{name: string, license: string, repo: string|null}>}
+ *   The dependency info.
+ */
+export function npmView(dep: string): Promise<{
+    name: string;
+    license: string;
+    repo: string | null;
+}>;
+/**
+ * Builds the markdown license section lines.
+ *
+ * @param {object} options - The options.
+ * @param {string|undefined} options.name - Package name.
+ * @param {string|undefined} options.license - Package license identifier.
+ * @param {string|undefined} options.licenseFile - License file name.
+ * @param {Array<{name: string, license: string, repo: string|null}>}
+ *   options.depResults - Dependency info results.
+ * @returns {string} The formatted markdown string.
+ */
+export function buildLicenseSection({ name, license, licenseFile, depResults }: {
+    name: string | undefined;
+    license: string | undefined;
+    licenseFile: string | undefined;
+    depResults: Array<{
+        name: string;
+        license: string;
+        repo: string | null;
+    }>;
+}): string;
+export const PUBLIC_DOMAIN: string[];
+//# sourceMappingURL=lib.d.ts.map

package/types/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,8BAHW,MAAM,GAAC,IAAI,GAAC,SAAS,GACnB,MAAM,GAAC,IAAI,CAWvB;AAED;;;;;;GAMG;AACH,6BAJW,MAAM,GACJ,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAA;CAAC,CAAC,CAkBvE;AAED;;;;;;;;;;GAUG;AACH,gFAPG;IAAkC,IAAI,EAA9B,MAAM,GAAC,SAAS;IACU,OAAO,EAAjC,MAAM,GAAC,SAAS;IACU,WAAW,EAArC,MAAM,GAAC,SAAS;IAEd,UAAU,EADZ,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAA;KAAC,CAAC;CAEjE,GAAU,MAAM,CAiClB;AArFD,qCAAsE"}

package/UNLICENSE.txt

@@ -1,24 +0,0 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-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 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.
-
-For more information, please refer to <https://unlicense.org>

package/src/cli.js

@@ -1,83 +0,0 @@
-#!/usr/bin/env node
-
-import * as TK from "@gesslar/toolkit"
-
-import {execFile} from "node:child_process"
-import {promisify} from "node:util"
-
-;(async() => {
-  const exec = promisify(execFile)
-
-  const cwd = new TK.DirectoryObject()
-  const jsonFile = cwd.getFile("package.json")
-  const pkg = await jsonFile.loadData()
-
-  // Detect license file in project root
-  const licenseFile = (await cwd.glob("{LICEN[CS]E,UNLICEN[CS]E}{,.txt,.md}"))?.files[0]
-
-  // Project name without scope
-  const name = pkg.name?.replace(/^@[^/]+\//, "") ?? "this project"
-  const license = pkg.license ?? "Unknown"
-
-  const publicDomain = ["Unlicense", "0BSD", "CC0-1.0"]
-  const phrase = publicDomain.includes(license)
-    ? `${name} is released into the public domain under the`
-    : `${name} is released under the`
-
-  const lines = [
-    "## License",
-    "",
-    phrase,
-    `[${license}](${licenseFile?.name ?? "LICENSE"}).`,
-  ]
-
-  const deps = Object.keys(pkg.dependencies ?? {}).sort()
-
-  if(deps.length) {
-    lines.push(
-      "",
-      "This package includes or depends on third-party components under their own",
-      "licenses:",
-      "",
-      "| Dependency | License |",
-      "| --- | --- |",
-    )
-
-    const results = await Promise.all(deps.map(dep => npmView(dep)))
-
-    for(const {name: dep, license: depLicense, repo} of results) {
-      const link = repo ? `[${dep}](${repo})` : dep
-      lines.push(`| ${link} | ${depLicense} |`)
-    }
-  }
-
-  TK.Glog(lines.join("\n"))
-
-  async function npmView(dep) {
-    try {
-      const {stdout} = await exec(
-        "npm", ["view", dep, "repository.url", "license", "--json"]
-      )
-      const data = JSON.parse(stdout)
-
-      return {
-        name: dep,
-        license: data.license ?? "Unknown",
-        repo: cleanUrl(data["repository.url"]),
-      }
-    } catch {
-      return {name: dep, license: "Unknown", repo: null}
-    }
-  }
-
-  function cleanUrl(raw) {
-    if(!raw)
-      return null
-
-    return raw
-      .replace(/^git\+/, "")
-      .replace(/\.git$/, "")
-      .replace(/^ssh:\/\/git@github\.com/, "https://github.com")
-      .replace(/^git:\/\//, "https://")
-  }
-})()