@monosmith/plugin-sdk 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monosmith/plugin-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The TypeScript SDK for writing smith plugins: the protocol's types, the serve loop, a test host, the conformance checks, templating and key-order-keeping JSON editing. No runtime dependencies.",
   "license": "MIT",
   "type": "module",

package/protocol/protocol-schema.contract.js

@@ -207,6 +207,17 @@ export const protocolSchema = {
             },
             "capability": "latest",
             "notification": false
+        },
+        "sbom/components": {
+            "description": "Asks which components a project ships (its locked dependencies, read from a lockfile where the ecosystem has one and from the manifest otherwise), as package URLs, for the SBOM a release attaches.",
+            "params": {
+                "$ref": "#/$defs/ComponentsParams"
+            },
+            "result": {
+                "$ref": "#/$defs/ComponentsResult"
+            },
+            "capability": "components",
+            "notification": false
         }
     },
     "x-errorCodes": [
@@ -531,6 +542,10 @@ export const protocolSchema = {
                 "cancel": {
                     "type": "boolean",
                     "description": "Cancel says the plugin stops the work of a request when the host sends a cancel notification with its id, then answers that request with its result (if the work was already done) or the request-cancelled error. A host never sends the notification to a plugin without it."
+                },
+                "components": {
+                    "type": "boolean",
+                    "description": "Components lists a project's dependencies for its SBOM."
                 }
             }
         },
@@ -588,6 +603,62 @@ export const protocolSchema = {
                 }
             }
         },
+        "Component": {
+            "description": "Component is one dependency of a project.",
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "version": {
+                    "type": "string",
+                    "description": "Version is the locked version, or the declared range when the project has no lockfile."
+                },
+                "purl": {
+                    "type": "string",
+                    "description": "PURL is the package URL (https://github.com/package-url/purl-spec)."
+                }
+            },
+            "required": [
+                "name",
+                "purl"
+            ]
+        },
+        "ComponentsParams": {
+            "description": "ComponentsParams asks a plugin for the components one of its projects ships: what a CycloneDX SBOM lists.",
+            "type": "object",
+            "properties": {
+                "project": {
+                    "$ref": "#/$defs/Project"
+                }
+            },
+            "required": [
+                "project"
+            ]
+        },
+        "ComponentsResult": {
+            "description": "ComponentsResult lists the components, read from a lockfile where the ecosystem has one and from the manifest otherwise. An empty list is an answer: the project declares no dependencies.",
+            "type": "object",
+            "properties": {
+                "components": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/Component"
+                    }
+                },
+                "source": {
+                    "type": "string",
+                    "description": "Source is the workspace-relative file the list was read from, \"\" when the project has none."
+                },
+                "purl": {
+                    "type": "string",
+                    "description": "PURL is the project's own package URL when it has a registry identity (without a version: the release supplies it); \"\" otherwise."
+                }
+            },
+            "required": [
+                "components"
+            ]
+        },
         "ContributeParams": {
             "description": "ContributeParams hands a plugin the projects it applies to: those whose stack includes it, or, for a workspace-wide convention, those of the languages it supports that smith.toml enables it for.",
             "type": "object",

package/protocol/protocol-types.contract.d.ts

@@ -160,6 +160,8 @@ export interface Capabilities {
      * request-cancelled error. A host never sends the notification to a plugin without it.
      */
     cancel?: boolean;
+    /** Components lists a project's dependencies for its SBOM. */
+    components?: boolean;
 }
 /**
  * ChangeKindParams asks a plugin what changing a project's kind edits. The plugin writes nothing:
@@ -203,6 +205,35 @@ export interface ChangeKindResult {
      */
     warnings?: string[];
 }
+/** Component is one dependency of a project. */
+export interface Component {
+    name: string;
+    /** Version is the locked version, or the declared range when the project has no lockfile. */
+    version?: string;
+    /** PURL is the package URL (https://github.com/package-url/purl-spec). */
+    purl: string;
+}
+/**
+ * ComponentsParams asks a plugin for the components one of its projects ships: what a CycloneDX
+ * SBOM lists.
+ */
+export interface ComponentsParams {
+    project: Project;
+}
+/**
+ * ComponentsResult lists the components, read from a lockfile where the ecosystem has one and from
+ * the manifest otherwise. An empty list is an answer: the project declares no dependencies.
+ */
+export interface ComponentsResult {
+    components: Component[];
+    /** Source is the workspace-relative file the list was read from, "" when the project has none. */
+    source?: string;
+    /**
+     * PURL is the project's own package URL when it has a registry identity (without a version: the
+     * release supplies it); "" otherwise.
+     */
+    purl?: string;
+}
 /**
  * ContributeParams hands a plugin the projects it applies to: those whose stack includes it, or,
  * for a workspace-wide convention, those of the languages it supports that smith.toml enables it
@@ -1156,6 +1187,16 @@ export interface ProtocolMethods {
         result: LatestResult;
         capability: 'latest';
     };
+    /**
+     * Asks which components a project ships (its locked dependencies, read from a lockfile where the
+     * ecosystem has one and from the manifest otherwise), as package URLs, for the SBOM a release
+     * attaches.
+     */
+    'sbom/components': {
+        params: ComponentsParams;
+        result: ComponentsResult;
+        capability: 'components';
+    };
 }
 export type MethodName = keyof ProtocolMethods;
 export type ParamsOf<M extends MethodName> = ProtocolMethods[M]['params'];

package/serve/index.d.ts

@@ -1,4 +1,4 @@
 export { serve, serveStreams } from './serve.use-case.ts';
 export { capabilitiesOf, implementsMethod } from './capabilities-of.algorithm.ts';
-export type { Awaitable, Cancellable, CIContributor, Contributor, DeclarationEditor, DependencyManager, Discoverer, DoctorContributor, Generator, KindChanger, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
+export type { Awaitable, Cancellable, CIContributor, ComponentLister, Contributor, DeclarationEditor, DependencyManager, Discoverer, DoctorContributor, Generator, KindChanger, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
 export type { FrameSink, ServeStreams } from './protocol-streams.contract.ts';

package/serve/plugin-members.config.js

@@ -23,4 +23,5 @@ export const PLUGIN_MEMBERS = {
     'dependencies/declared': { member: 'declared', requires: ['declared', 'rewrite'] },
     'dependencies/rewrite': { member: 'rewrite', requires: ['declared', 'rewrite'] },
     'dependencies/latest': { member: 'latest', requires: ['latest'] },
+    'sbom/components': { member: 'components', requires: ['components'] },
 };

package/serve/plugin.contract.d.ts

@@ -1,4 +1,4 @@
-import type { ChangeKindParams, ChangeKindResult, CIParams, CIResult, ContributeParams, ContributeResult, DeclaredParams, DeclaredResult, DependencyResult, DiscoverParams, DiscoverResult, DoctorParams, DoctorResult, GenerateParams, GenerateResult, InitializeParams, InitializeResult, InstallParams, LatestParams, LatestResult, PublishedParams, PublishedResult, PublishParams, PublishResult, RemoveParams, RemoveResult, RewriteParams, UninstallParams, VersionParams, VersionResult } from '../protocol/index.ts';
+import type { ChangeKindParams, ChangeKindResult, CIParams, CIResult, ComponentsParams, ComponentsResult, ContributeParams, ContributeResult, DeclaredParams, DeclaredResult, DependencyResult, DiscoverParams, DiscoverResult, DoctorParams, DoctorResult, GenerateParams, GenerateResult, InitializeParams, InitializeResult, InstallParams, LatestParams, LatestResult, PublishedParams, PublishedResult, PublishParams, PublishResult, RemoveParams, RemoveResult, RewriteParams, UninstallParams, VersionParams, VersionResult } from '../protocol/index.ts';
 /** A result now or later: every method of a plugin may be `async`. */
 export type Awaitable<T> = T | Promise<T>;
 /** What a plugin says about itself. The serve loop fills in `protocolVersion` and `capabilities`. */
@@ -44,6 +44,10 @@ export interface Remover {
 export interface KindChanger {
     changeKind: (params: ChangeKindParams, signal: AbortSignal) => Awaitable<ChangeKindResult>;
 }
+/** `sbom/components`: the components a project ships, for the SBOM a release attaches. */
+export interface ComponentLister {
+    components: (params: ComponentsParams, signal: AbortSignal) => Awaitable<ComponentsResult>;
+}
 /** `dependencies/install` and `dependencies/uninstall`: both, or the capability is not advertised. */
 export interface DependencyManager {
     install: (params: InstallParams, signal: AbortSignal) => Awaitable<DependencyResult>;
@@ -81,4 +85,4 @@ export interface Cancellable {
  * from `cancellable`. How many requests it can work on at once is declared in
  * `describe`'s `concurrency`: omit it for one at a time, in order.
  */
-export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & KindChanger & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;
+export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & KindChanger & ComponentLister & DependencyManager & DeclarationEditor & LatestReader & Contributor & Cancellable>;