From e9c3c6b5f2cc64243123f540728a0436d6aa2228 Mon Sep 17 00:00:00 2001 From: Jamie Magee Date: Wed, 9 Jul 2025 13:35:56 -0700 Subject: [PATCH 1/2] Add `.d.ts` types Follow-up from https://github.com/clearlydefined/service/pull/1334#discussion_r2195255073 --- index.d.ts | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 1 + tsconfig.json | 2 +- 3 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 index.d.ts diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 0000000..5ca5094 --- /dev/null +++ b/index.d.ts @@ -0,0 +1,122 @@ +/** Represents a parsed SPDX license expression as an Abstract Syntax Tree (AST) */ +export interface SpdxExpression { + /** The SPDX license identifier (e.g., 'MIT', 'Apache-2.0') */ + license?: string + /** Whether the license allows later versions (indicated by '+' suffix) */ + plus?: boolean + /** License exception identifier (e.g., 'Classpath-exception-2.0') */ + exception?: string + /** Logical conjunction operator ('and' or 'or') */ + conjunction?: 'and' | 'or' + /** Left operand in a binary expression */ + left?: SpdxExpression + /** Right operand in a binary expression */ + right?: SpdxExpression + /** Indicates this is a NOASSERTION expression */ + noassertion?: boolean | null +} + +/** + * Visitor function type for processing license nodes during parsing + * + * @param license - The license identifier to process + * @returns The normalized license identifier or null if invalid + */ +export type LicenseVisitor = (license: string) => string | null + +/** + * Lookup function type for resolving license references + * + * @param licenseRef - The license reference to resolve + * @returns The resolved license identifier or null if not found + */ +export type LicenseRefLookup = (licenseRef: string) => string | null + +/** Mode for merging license expressions */ +export type MergeMode = 'OR' | 'AND' + +/** + * Parses an SPDX expression into an Abstract Syntax Tree (AST) and corrects each node + * + * @param expression - SPDX expression string to parse + * @param licenseVisitor - Optional visitor function to clean each license node + * @param licenseRefLookup - Optional lookup function to resolve license references + * @returns The AST representing the parsed expression + */ +export function parse( + expression: string | SpdxExpression, + licenseVisitor?: LicenseVisitor, + licenseRefLookup?: LicenseRefLookup +): SpdxExpression + +/** + * Converts a parsed expression AST back into an SPDX expression string + * + * @param obj - An AST representing the parsed expression + * @returns The SPDX expression string + */ +export function stringify(obj: SpdxExpression): string + +/** + * Normalizes and returns back a given SPDX expression. Corrects case and formatting inconsistencies. + * + * @param expression - SPDX expression to normalize + * @returns The normalized SPDX expression or null if invalid/empty + */ +export function normalize(expression: string | null | undefined): string | null + +/** + * Normalizes and returns back a single SPDX license identifier + * + * @param license - Single license identifier to normalize + * @returns The normalized SPDX license identifier or null if invalid + */ +export function normalizeSingle(license: string | null | undefined): string | null + +/** + * Checks if the first expression satisfies the second expression + * + * @param expression1 - First SPDX expression + * @param expression2 - Second SPDX expression to check against + * @returns True if expression1 satisfies expression2 + */ +export function satisfies(expression1: string, expression2: string): boolean + +/** + * Looks up an SPDX identifier by the full license name. Case insensitive matching. + * + * @param licenseName - Full name of the license + * @returns SPDX identifier or null if not found + */ +export function lookupByName(licenseName: string | null | undefined): string | null + +/** + * Merges the proposed expression into the base expression + * + * @param proposed - The proposed license expression to merge + * @param base - The base license expression to merge into + * @param mode - Merge mode, either 'OR' (default) or 'AND' + * @returns The merged license expression + */ +export function merge( + proposed: string | SpdxExpression, + base: string | SpdxExpression, + mode?: MergeMode +): string | SpdxExpression + +/** + * Expands the given expression into an equivalent array where each member is an array of licenses AND'd together and + * the members are OR'd together + * + * @param expression - An SPDX license expression in string or object form + * @returns The normalized list of license expression leaves equivalent to the input + */ +export function expand(expression: string | SpdxExpression): string[][] + +/** + * Flattens the given expression into an array of all licenses mentioned in the expression + * + * @param expression - An SPDX license expression in string or object form + * @returns An array of all license identifiers in the expression + */ +export function flatten(expression: string | SpdxExpression): string[] | undefined diff --git a/package.json b/package.json index b9b1089..206d7ea 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,7 @@ "url": "git+https://github.com/clearlydefined/spdx.git" }, "main": "index.js", + "types": "index.d.ts", "keywords": [ "spdx" ], diff --git a/tsconfig.json b/tsconfig.json index a5d3eb9..96e80da 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -5,5 +5,5 @@ "checkJs": true, "noEmit": true }, - "include": ["index.js"] + "include": ["index.js", "index.d.ts"] } From 610c40181e24b9689a1a3d39fbc95aca92ad65cc Mon Sep 17 00:00:00 2001 From: Jamie Magee Date: Mon, 6 Apr 2026 20:29:09 -0700 Subject: [PATCH 2/2] Add copyright header and fix merge types Add the copyright/SPDX header to index.d.ts to match index.js. Allow null/undefined in merge() params and return type to match runtime behavior. --- index.d.ts | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/index.d.ts b/index.d.ts index 5ca5094..bba1044 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,3 +1,6 @@ +// Copyright (c) Microsoft Corporation and others. Licensed under the MIT license. +// SPDX-License-Identifier: MIT + /** Represents a parsed SPDX license expression as an Abstract Syntax Tree (AST) */ export interface SpdxExpression { /** The SPDX license identifier (e.g., 'MIT', 'Apache-2.0') */ @@ -99,10 +102,10 @@ export function lookupByName(licenseName: string | null | undefined): string | n * @returns The merged license expression */ export function merge( - proposed: string | SpdxExpression, - base: string | SpdxExpression, + proposed: string | SpdxExpression | null | undefined, + base: string | SpdxExpression | null | undefined, mode?: MergeMode -): string | SpdxExpression +): string | SpdxExpression | null | undefined /** * Expands the given expression into an equivalent array where each member is an array of licenses AND'd together and