@typecad/cuttlefish 1.0.0-alpha.10 → 1.0.0-alpha.12

package/dist/api/config.d.ts

@@ -8,8 +8,12 @@ type OptimizationLevel = 'none' | 'size' | 'speed' | 'balanced';
  * Output section — controls how generated C++ is laid out.
  */
 interface CuttlefishOutputConfig {
-    /** Target build framework. */
-    framework: OutputFramework;
+    /**
+     * Target build framework. Optional — the top-level `framework` field is the
+     * primary source; this mirrors it for the output section and is rarely set.
+     * Matches the optional Zod `output.framework` in config-schema.ts.
+     */
+    framework?: OutputFramework;
     /** Optimization level. */
     optimize?: OptimizationLevel;
     /** Directory to write generated files into (relative to project root). */
@@ -50,8 +54,12 @@ export interface CuttlefishConfig {
     /**
      * MCU package providing silicon definitions.
      * Example: '@typecad/mcu-atmega328p'
+     *
+     * Optional for native/host targets — a desktop build has no MCU (the
+     * loader generates a boardless `@typecad/board` shim). Embedded targets
+     * should set this (or the deprecated `board`).
      */
-    mcu: string;
+    mcu?: string;
     /**
      * Board package to use. (Deprecated — use mcu + contract instead)
      */

package/dist/api/shared/framework-manifest.d.ts

@@ -20,17 +20,17 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         generateHeaderFile: z.ZodBoolean;
         customBridgeShim: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
         entrypointFunctionName: string;
         requiresLoopFunction: boolean;
-        sourceExtension: "ino" | "cc" | "cpp" | "h";
         generateHeaderFile: boolean;
         overrideBaseName?: string | undefined;
         outputSubdirectory?: string | undefined;
         customBridgeShim?: string | undefined;
     }, {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
         entrypointFunctionName: string;
         requiresLoopFunction: boolean;
-        sourceExtension: "ino" | "cc" | "cpp" | "h";
         generateHeaderFile: boolean;
         overrideBaseName?: string | undefined;
         outputSubdirectory?: string | undefined;
@@ -41,13 +41,13 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         forcedIncludes: z.ZodArray<z.ZodString, "many">;
         symbolAliases: z.ZodRecord<z.ZodString, z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        targets: string[];
         forcedIncludes: string[];
         symbolAliases: Record<string, string>;
-    }, {
         targets: string[];
+    }, {
         forcedIncludes: string[];
         symbolAliases: Record<string, string>;
+        targets: string[];
     }>;
     hal: z.ZodObject<{
         [x: string]: z.ZodObject<{
@@ -57,12 +57,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             partialCoverage: z.ZodDefault<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
             partialCoverage: boolean;
             unsupportedReason?: string | undefined;
         }, {
             supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
             unsupportedReason?: string | undefined;
             partialCoverage?: boolean | undefined;
         }>;
@@ -81,12 +81,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         partialCoverage: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         supported: boolean;
-        ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
         partialCoverage: boolean;
         unsupportedReason?: string | undefined;
     }, {
         supported: boolean;
-        ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
         unsupportedReason?: string | undefined;
         partialCoverage?: boolean | undefined;
     }>, z.objectOutputType<{
@@ -97,12 +97,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             partialCoverage: z.ZodDefault<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
             partialCoverage: boolean;
             unsupportedReason?: string | undefined;
         }, {
             supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
             unsupportedReason?: string | undefined;
             partialCoverage?: boolean | undefined;
         }>;
@@ -121,12 +121,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         partialCoverage: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         supported: boolean;
-        ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
         partialCoverage: boolean;
         unsupportedReason?: string | undefined;
     }, {
         supported: boolean;
-        ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
         unsupportedReason?: string | undefined;
         partialCoverage?: boolean | undefined;
     }>, "strip">, z.objectInputType<{
@@ -137,12 +137,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             partialCoverage: z.ZodDefault<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
             partialCoverage: boolean;
             unsupportedReason?: string | undefined;
         }, {
             supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
             unsupportedReason?: string | undefined;
             partialCoverage?: boolean | undefined;
         }>;
@@ -161,12 +161,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         partialCoverage: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         supported: boolean;
-        ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
         partialCoverage: boolean;
         unsupportedReason?: string | undefined;
     }, {
         supported: boolean;
-        ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
         unsupportedReason?: string | undefined;
         partialCoverage?: boolean | undefined;
     }>, "strip">>;
@@ -222,16 +222,19 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             compile: z.ZodBoolean;
             upload: z.ZodBoolean;
             monitor: z.ZodBoolean;
+            debug: z.ZodOptional<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             prepare: boolean;
             compile: boolean;
             upload: boolean;
             monitor: boolean;
+            debug?: boolean | undefined;
         }, {
             prepare: boolean;
             compile: boolean;
             upload: boolean;
             monitor: boolean;
+            debug?: boolean | undefined;
         }>;
         reexportedFrom: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
@@ -241,6 +244,7 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             compile: boolean;
             upload: boolean;
             monitor: boolean;
+            debug?: boolean | undefined;
         };
         reexportedFrom?: string | undefined;
     }, {
@@ -250,6 +254,7 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             compile: boolean;
             upload: boolean;
             monitor: boolean;
+            debug?: boolean | undefined;
         };
         reexportedFrom?: string | undefined;
     }>;
@@ -305,12 +310,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             recommendedStringImpl: "std_string" | "static_string";
         }>;
     }, "strip", z.ZodTypeAny, {
-        normalizeCppType: boolean;
-        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        needsIostream: boolean;
         needsStdString: boolean;
         needsStdVector: boolean;
-        needsIostream: boolean;
         needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
         stdlibSupport: {
             hasVector: boolean;
             hasString: boolean;
@@ -321,12 +326,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             recommendedStringImpl: "std_string" | "static_string";
         };
     }, {
-        normalizeCppType: boolean;
-        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        needsIostream: boolean;
         needsStdString: boolean;
         needsStdVector: boolean;
-        needsIostream: boolean;
         needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
         stdlibSupport: {
             hasVector: boolean;
             hasString: boolean;
@@ -371,42 +376,42 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         zephyr?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
+    hal: {
+        [x: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        };
+        raw?: unknown;
+    } & {
+        [k: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        };
+    };
+    packageName: string;
     schemaVersion: 1;
     frameworkId: string;
-    packageName: string;
     canonical: boolean;
     displayName: string;
     description: string;
     implementationMode: "from-scratch" | "extends-canonical" | "extends-other";
     entrypoint: {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
         entrypointFunctionName: string;
         requiresLoopFunction: boolean;
-        sourceExtension: "ino" | "cc" | "cpp" | "h";
         generateHeaderFile: boolean;
         overrideBaseName?: string | undefined;
         outputSubdirectory?: string | undefined;
         customBridgeShim?: string | undefined;
     };
     profile: {
-        targets: string[];
         forcedIncludes: string[];
         symbolAliases: Record<string, string>;
-    };
-    hal: {
-        [x: string]: {
-            supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
-        raw?: unknown;
-    } & {
-        [k: string]: {
-            supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
+        targets: string[];
     };
     polyfills: {
         emitted: {
@@ -426,16 +431,17 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             compile: boolean;
             upload: boolean;
             monitor: boolean;
+            debug?: boolean | undefined;
         };
         reexportedFrom?: string | undefined;
     };
     typeEmission: {
-        normalizeCppType: boolean;
-        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        needsIostream: boolean;
         needsStdString: boolean;
         needsStdVector: boolean;
-        needsIostream: boolean;
         needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
         stdlibSupport: {
             hasVector: boolean;
             hasString: boolean;
@@ -451,6 +457,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         hardwareTestGroups: string[];
         halResolutionTests: string[];
     };
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
     basedOn?: string | undefined;
     inheritsStrategyId?: string | undefined;
     libraryResolution?: {
@@ -460,51 +472,45 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         tryGenerateLibDecl: boolean;
         reexportedFrom?: string | undefined;
     } | undefined;
-    doctor?: {
-        available: boolean;
-    } | undefined;
-    licenses?: {
-        available: boolean;
-    } | undefined;
     compat?: {
         zephyr?: string | undefined;
     } | undefined;
 }, {
+    hal: {
+        [x: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        };
+        raw?: unknown;
+    } & {
+        [k: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        };
+    };
+    packageName: string;
     schemaVersion: 1;
     frameworkId: string;
-    packageName: string;
     displayName: string;
     description: string;
     implementationMode: "from-scratch" | "extends-canonical" | "extends-other";
     entrypoint: {
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
         entrypointFunctionName: string;
         requiresLoopFunction: boolean;
-        sourceExtension: "ino" | "cc" | "cpp" | "h";
         generateHeaderFile: boolean;
         overrideBaseName?: string | undefined;
         outputSubdirectory?: string | undefined;
         customBridgeShim?: string | undefined;
     };
     profile: {
-        targets: string[];
         forcedIncludes: string[];
         symbolAliases: Record<string, string>;
-    };
-    hal: {
-        [x: string]: {
-            supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
-            unsupportedReason?: string | undefined;
-            partialCoverage?: boolean | undefined;
-        };
-        raw?: unknown;
-    } & {
-        [k: string]: {
-            supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
-            unsupportedReason?: string | undefined;
-            partialCoverage?: boolean | undefined;
-        };
+        targets: string[];
     };
     polyfills: {
         emitted: {
@@ -524,16 +530,17 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
             compile: boolean;
             upload: boolean;
             monitor: boolean;
+            debug?: boolean | undefined;
         };
         reexportedFrom?: string | undefined;
     };
     typeEmission: {
-        normalizeCppType: boolean;
-        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        needsIostream: boolean;
         needsStdString: boolean;
         needsStdVector: boolean;
-        needsIostream: boolean;
         needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
         stdlibSupport: {
             hasVector: boolean;
             hasString: boolean;
@@ -549,6 +556,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         hardwareTestGroups: string[];
         halResolutionTests: string[];
     };
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
     canonical?: boolean | undefined;
     basedOn?: string | undefined;
     inheritsStrategyId?: string | undefined;
@@ -559,12 +572,6 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         tryGenerateLibDecl: boolean;
         reexportedFrom?: string | undefined;
     } | undefined;
-    doctor?: {
-        available: boolean;
-    } | undefined;
-    licenses?: {
-        available: boolean;
-    } | undefined;
     compat?: {
         zephyr?: string | undefined;
     } | undefined;

package/dist/api/shared/framework-manifest.js

@@ -84,6 +84,7 @@ const ToolchainCoverageSchema = z.object({
         compile: z.boolean(),
         upload: z.boolean(),
         monitor: z.boolean(),
+        debug: z.boolean().optional(),
     }),
     reexportedFrom: z.string().optional(),
 });

package/dist/api/shared/index.d.ts

@@ -42,3 +42,5 @@ export { KNOWN_FRAMEWORK_PACKAGES, loadFrameworkManifest, } from './framework-ma
 export type { KnownFrameworkPackage } from './framework-manifest-registry.js';
 export { validateFrameworkManifest } from './validate-framework-manifest.js';
 export type { ManifestValidationContext, ManifestValidationResult, ManifestValidationError, ManifestValidationWarning, } from './validate-framework-manifest.js';
+export type { CopyleftRisk, LicenseSource, LibraryLicenseEntry, DiscoveredDependency, ReadFile, ReadDir, ResolveLicenseOptions, } from './spdx-licenses.js';
+export { SPDX_TABLE, RISK_RANK, LICENSE_FILENAMES, normalize, identifySpdx, classifyRisk, readLicenseFileIn, readLicenseFile, readSourceHeaders, resolveLibraryLicense, riskBracket, statusMark, countByRisk, } from './spdx-licenses.js';

package/dist/api/shared/index.js

@@ -43,3 +43,4 @@ export { FrameworkManifestSchema, defineFrameworkManifest, HAL_CATEGORIES, POLYF
 export { KNOWN_FRAMEWORK_PACKAGES, loadFrameworkManifest, } from './framework-manifest-registry.js';
 // Framework manifest validator
 export { validateFrameworkManifest } from './validate-framework-manifest.js';
+export { SPDX_TABLE, RISK_RANK, LICENSE_FILENAMES, normalize, identifySpdx, classifyRisk, readLicenseFileIn, readLicenseFile, readSourceHeaders, resolveLibraryLicense, riskBracket, statusMark, countByRisk, } from './spdx-licenses.js';

package/dist/api/shared/spdx-licenses.d.ts

@@ -0,0 +1,139 @@
+export type CopyleftRisk = "permissive" | "weak-copyleft" | "strong-copyleft" | "unknown";
+/**
+ * Where a license declaration was found.
+ *
+ * `"library.properties"` is the Arduino library-manifest form (kept verbatim
+ * for Arduino parity); `"manifest"` is the framework-neutral form for any
+ * other manifest reader a framework supplies (e.g. a west module.yml).
+ */
+export type LicenseSource = "library.properties" | "manifest" | "license-file" | "source-header" | "none";
+/**
+ * A resolved license row for a single dependency. Frameworks render this into
+ * their own CLI tables.
+ */
+export interface LibraryLicenseEntry {
+    name: string;
+    version: string | undefined;
+    /** Install/root directory of the dependency (where its LICENSE lives). */
+    path: string;
+    /** Normalized SPDX ID (e.g. "BSD-3-Clause"); undefined if not determined. */
+    spdx: string | undefined;
+    risk: CopyleftRisk;
+    source: LicenseSource;
+}
+/**
+ * Neutral dependency shape every framework adapts its enumeration to. Arduino
+ * maps `{ name, version, install_dir }` → `{ name, version, installDir }`;
+ * Zephyr maps a west-listed project (`{ name, abspath }`) the same way.
+ */
+export interface DiscoveredDependency {
+    name: string;
+    version?: string;
+    /** Absolute path to the dependency's install/root directory. */
+    installDir?: string;
+}
+/** Injected file reader (returns undefined on missing/unreadable). */
+export type ReadFile = (p: string) => string | undefined;
+/** Injected directory lister (returns [] on missing/unreadable). */
+export type ReadDir = (d: string) => string[];
+interface SpdxEntry {
+    id: string;
+    aliases: string[];
+    risk: CopyleftRisk;
+    /** Substrings, ALL of which must appear in the normalized license text. */
+    markers: string[];
+    /**
+     * Short-form phrases for sparse source-header comments where the full license
+     * text is absent (e.g. Adafruit's "BSD license, all text here must be
+     * included"). ANY one match is sufficient. Lower-cased on use.
+     */
+    shortMarkers: string[];
+}
+export declare const SPDX_TABLE: readonly SpdxEntry[];
+export declare const RISK_RANK: Record<CopyleftRisk, number>;
+/**
+ * Candidate LICENSE filenames checked case-insensitively. Includes the British
+ * "LICENCE" spelling (e.g. lvgl ships LICENCE.txt) and the `.rst`
+ * (reStructuredText) form common in Zephyr/Linux modules (e.g.
+ * trusted-firmware-m ships `license.rst`).
+ *
+ * Deliberately does NOT match per-component `COPYING.<spec>` files (e.g.
+ * picolibc's COPYING.GPL2 / COPYING.NEWLIB / COPYING.picolibc): those name a
+ * specific license rather than the project license, and matching COPYING.GPL2
+ * would falsely flag a BSD project as strong-copyleft.
+ */
+export declare const LICENSE_FILENAMES: readonly string[];
+/**
+ * Normalize license input text for matching: trim, lowercase, strip surrounding
+ * quotes/whitespace.
+ */
+export declare function normalize(input: string): string;
+/**
+ * Resolve a raw license input (either a short manifest value, the full text of
+ * a LICENSE file, or a source-file header comment) to a canonical SPDX ID.
+ *
+ * Matching priority:
+ *   1. SPDX-License-Identifier: <id> marker (authoritative when present)
+ *   2. exact alias match (suits the short manifest value)
+ *   3. substring markers match, ALL markers required (suits full LICENSE text)
+ *   4. shortMarkers match, ANY one sufficient (suits sparse header comments
+ *      like Adafruit's "BSD license, all text here must be included")
+ *
+ * Returns the SPDX ID string, or undefined if nothing matched.
+ */
+export declare function identifySpdx(input: string): string | undefined;
+/**
+ * Classify the copyleft risk of a known SPDX ID. Returns "unknown" for
+ * unrecognized ids.
+ */
+export declare function classifyRisk(spdx: string): CopyleftRisk;
+/**
+ * Read the first LICENSE/COPYING file found in a directory and return its text.
+ * Checks the directory itself only (no recursion). The match is
+ * case-insensitive, but the file is read using its REAL on-disk name (not the
+ * canonical candidate) so it works on case-sensitive filesystems where a module
+ * ships e.g. `license.rst` rather than `LICENSE.rst`.
+ */
+export declare function readLicenseFileIn(dir: string, readFile: ReadFile, readdir: ReadDir): string | undefined;
+/**
+ * Read the first LICENSE/COPYING file found in installDir or one of its common
+ * subdirectories (e.g. `src/`, where Arduino's own libraries keep it).
+ */
+export declare function readLicenseFile(installDir: string, readFile: ReadFile, readdir: ReadDir, subdirs?: readonly string[]): string | undefined;
+/**
+ * Read the leading header comment of each candidate source file in installDir
+ * (and its subdirs) and concatenate them, so the SPDX matcher can look for
+ * license phrases. The license notice usually lives in the file named after the
+ * dependency itself, so such files are scanned first; then a cap of further
+ * headers/sources is scanned to keep this cheap.
+ */
+export declare function readSourceHeaders(depName: string, installDir: string, readFile: ReadFile, readdir: ReadDir, subdirs?: readonly string[]): string | undefined;
+export interface ResolveLicenseOptions {
+    /** Subdirs searched for a LICENSE file / source headers beyond the root. */
+    subdirs?: readonly string[];
+    /**
+     * Read a manifest file's text for a license field. Given the install dir and
+     * the readFile seam, return the raw license value (or undefined). Arduino
+     * wires this to read `library.properties` `license=`. Omit to skip the
+     * manifest step (e.g. a framework whose manifest carries no license field).
+     */
+    readManifestLicense?: (installDir: string, readFile: ReadFile) => string | undefined;
+    /**
+     * LicenseSource label attached when the license is found via
+     * `readManifestLicense`. Defaults to `"manifest"`; Arduino passes
+     * `"library.properties"` for parity with its existing output.
+     */
+    manifestSourceLabel?: LicenseSource;
+}
+/**
+ * Resolve a single dependency's license. Priority: manifest → LICENSE file →
+ * source-file header comments → none.
+ *
+ * Never throws: an unreadable manifest/LICENSE/source simply falls through to
+ * the next step, ending at a `"none"` / unknown entry.
+ */
+export declare function resolveLibraryLicense(dep: DiscoveredDependency, readFile: ReadFile, readdir: ReadDir, options?: ResolveLicenseOptions): LibraryLicenseEntry;
+export declare function riskBracket(risk: CopyleftRisk): string;
+export declare function statusMark(risk: CopyleftRisk): string;
+export declare function countByRisk(libs: LibraryLicenseEntry[]): Record<CopyleftRisk, number>;
+export {};