From 96c0995ad8d53f99d0ecb98316246b096cc2ee1e Mon Sep 17 00:00:00 2001 From: Masaharu Tashiro Date: Mon, 28 Oct 2024 21:30:44 +0900 Subject: [PATCH] add JSDoc --- src/plugin/core/contents/index.ts | 10 +++++++ src/plugin/core/crypto/private-key.ts | 32 +++++++++++++---------- src/plugin/core/crypto/public-key.ts | 19 +++++++++----- src/plugin/core/driver/interface.ts | 27 +++++++++++++++++++ src/plugin/core/driver/local-fs.ts | 3 +++ src/plugin/core/driver/zip.ts | 3 +++ src/plugin/core/manifest/factory.ts | 6 ++--- src/plugin/core/manifest/interface.ts | 23 ++++++++++++++++ src/plugin/core/manifest/v1/index.ts | 3 --- src/plugin/core/manifest/v1/sourcelist.ts | 2 +- src/plugin/core/manifest/v2/index.ts | 3 --- src/plugin/core/manifest/v2/sourcelist.ts | 2 +- src/plugin/core/plugin/index.ts | 3 +++ 13 files changed, 105 insertions(+), 31 deletions(-) diff --git a/src/plugin/core/contents/index.ts b/src/plugin/core/contents/index.ts index b08ec248a1..1b15d7ef7c 100644 --- a/src/plugin/core/contents/index.ts +++ b/src/plugin/core/contents/index.ts @@ -5,8 +5,18 @@ import type { DriverInterface } from "../driver"; import { ZipFileDriver } from "../driver"; import { createContentsZip } from "./zip"; +/** + * Contents represents the plugin source files aggregated by Manifest + */ export interface ContentsInterface extends DriverInterface { + /** + * returns Manifest + */ manifest(): Promise; + + /** + * validate contents + */ validate(): Promise; } diff --git a/src/plugin/core/crypto/private-key.ts b/src/plugin/core/crypto/private-key.ts index b13360b435..aeb009385d 100644 --- a/src/plugin/core/crypto/private-key.ts +++ b/src/plugin/core/crypto/private-key.ts @@ -2,10 +2,28 @@ import RSA from "node-rsa"; import { uuid } from "./uuid"; import { sign } from "./sign"; +/** + * PrivateKey represents private key to pack, sign, and verify plugin + */ export interface PrivateKeyInterface { + /** + * Export private key file + * @return {string} ppk formated private key + */ exportPrivateKey(): string; + /** + * Export public key file + * @returns {string} der formated public key + */ exportPublicKey(): Buffer; + /** + * Generate UUID for this key + */ uuid(): string; + /** + * Generate signature for the contents + * @param contents {Buffer} + */ sign(contents: Buffer): Buffer; } @@ -35,32 +53,18 @@ export class PrivateKey implements PrivateKeyInterface { return new PrivateKey(new RSA(key)); } - /** - * Export private key - * @return {string} ppk format string - */ public exportPrivateKey(): string { return this.key.exportKey("pkcs1-private") + "\n"; } - /** - * Export public key - */ public exportPublicKey(): Buffer { return this.key.exportKey("pkcs8-public-der"); } - /** - * Generate UUID for this key - */ public uuid(): string { return uuid(this.exportPublicKey()); } - /** - * Generate signature for the contents - * @param contents {Buffer} - */ public sign(contents: Buffer): Buffer { return sign(contents, this.exportPrivateKey()); } diff --git a/src/plugin/core/crypto/public-key.ts b/src/plugin/core/crypto/public-key.ts index 92dddaadb0..7b426f3c84 100644 --- a/src/plugin/core/crypto/public-key.ts +++ b/src/plugin/core/crypto/public-key.ts @@ -3,8 +3,21 @@ import { uuid } from "./uuid"; import crypto from "crypto"; export interface PublicKeyInterface { + /** + * Export public key file + * @returns {string} der formated public key + */ exportPublicKey(): Buffer; + /** + * Generate UUID for this key + */ uuid(): string; + + /** + * Verify data with signature + * @param data + * @param signature + */ verify(data: Buffer, signature: Buffer): boolean; } @@ -34,16 +47,10 @@ export class PublicKey implements PublicKeyInterface { return new PublicKey(rsa); } - /** - * Export public key - */ public exportPublicKey(): Buffer { return this.key.exportKey("pkcs8-public-der"); } - /** - * Generate UUID for this key - */ public uuid(): string { return uuid(this.exportPublicKey()); } diff --git a/src/plugin/core/driver/interface.ts b/src/plugin/core/driver/interface.ts index 3baf9f777e..52ccb6144b 100644 --- a/src/plugin/core/driver/interface.ts +++ b/src/plugin/core/driver/interface.ts @@ -7,13 +7,40 @@ export type FileStats = { size: number; }; +/** + * Driver represents filesystem like a local disc, zip file, memory, etc. + */ export interface DriverInterface { + /** + * Returns files in the filesystem + */ fileList(): Promise; + + /** + * Returns file information + * @param fileName + */ stat(fileName: string): Promise; // TODO: Delete this function after https://github.com/kintone/js-sdk/pull/3037 merged statSync(fileName: string): FileStats; + + /** + * Read the entire contents of a file. + * @param fileName + */ readFile(fileName: string): Promise; readFile(fileName: string, encoding: "utf-8"): Promise; + + /** + * Create readable stream to read a file contents. + * @param fileName + */ openReadStream(fileName: string): Promise; + + /** + * Write the entire contents to a file. + * @param fileName + * @param data + */ writeFile(fileName: string, data: string | Buffer): Promise; } diff --git a/src/plugin/core/driver/local-fs.ts b/src/plugin/core/driver/local-fs.ts index 6e570f985a..485dcf66c5 100644 --- a/src/plugin/core/driver/local-fs.ts +++ b/src/plugin/core/driver/local-fs.ts @@ -5,6 +5,9 @@ import { statSync, createReadStream } from "fs"; import path from "path"; import type { Readable } from "node:stream"; +/** + * LocalFSDriver is a Driver for the local disc + */ export class LocalFSDriver implements DriverInterface { private currentDir: string; diff --git a/src/plugin/core/driver/zip.ts b/src/plugin/core/driver/zip.ts index 8241cf0fb2..10b65d430b 100644 --- a/src/plugin/core/driver/zip.ts +++ b/src/plugin/core/driver/zip.ts @@ -6,6 +6,9 @@ import consumers from "node:stream/consumers"; type Entries = Map; +/** + * ZipFileDriver is a Driver for a zip file + */ export class ZipFileDriver implements DriverInterface { private readonly _buffer: Buffer; diff --git a/src/plugin/core/manifest/factory.ts b/src/plugin/core/manifest/factory.ts index 461d9e45c9..a9e3a777bd 100644 --- a/src/plugin/core/manifest/factory.ts +++ b/src/plugin/core/manifest/factory.ts @@ -4,6 +4,9 @@ import type { ManifestInterface, ManifestStaticInterface } from "./interface"; import { ManifestV1 } from "./v1"; import { ManifestV2 } from "./v2"; +/** + * Factory to instantiate Manifest + */ export class ManifestFactory { private constructor() { /* noop */ @@ -35,9 +38,6 @@ export class ManifestFactory { } } - /** - * Load JSON file without caching - */ public static async loadJsonFile( jsonFilePath: string, driver?: DriverInterface, diff --git a/src/plugin/core/manifest/interface.ts b/src/plugin/core/manifest/interface.ts index 28bc085178..a6a537ef51 100644 --- a/src/plugin/core/manifest/interface.ts +++ b/src/plugin/core/manifest/interface.ts @@ -3,7 +3,14 @@ import type { ContentsZip } from "../contents"; import type { ValidationResult } from "./validate"; export interface ManifestStaticInterface { + /** + * Parse JSON object to Manifest + * @param manifestJson + */ parseJson(manifestJson: string): ManifestInterface; + /** + * Load and parse JSON file to Manifest + */ loadJsonFile( jsonFilePath: string, driver?: DriverInterface, @@ -11,8 +18,21 @@ export interface ManifestStaticInterface { } export interface ManifestInterface { + /** + * Validate Manifest + * @param driver If set, also validate file existence and file size. + */ validate(driver?: DriverInterface): Promise; + + /** + * Returns files described in a Manifest + */ sourceList(): string[]; + + /** + * Generate contents.zip from Manifest and Driver + * @param driver + */ generateContentsZip(driver: DriverInterface): Promise; // Accessor @@ -22,5 +42,8 @@ export interface ManifestInterface { get description(): string | undefined; get homepageUrl(): string | undefined; + /** + * Returns JSON object represents Manifest raw object. + */ get json(): object; } diff --git a/src/plugin/core/manifest/v1/index.ts b/src/plugin/core/manifest/v1/index.ts index 72a4c54b2a..3f4a7d3313 100644 --- a/src/plugin/core/manifest/v1/index.ts +++ b/src/plugin/core/manifest/v1/index.ts @@ -17,9 +17,6 @@ export class ManifestV1 implements ManifestInterface { return new ManifestV1(JSON.parse(manifestJson)); } - /** - * Load JSON file without caching - */ public static async loadJsonFile( jsonFilePath: string, driver?: DriverInterface, diff --git a/src/plugin/core/manifest/v1/sourcelist.ts b/src/plugin/core/manifest/v1/sourcelist.ts index 767f4f3dd3..a4ded7c831 100644 --- a/src/plugin/core/manifest/v1/sourcelist.ts +++ b/src/plugin/core/manifest/v1/sourcelist.ts @@ -1,7 +1,7 @@ import type { ManifestV1JsonObject } from "./index"; /** - * Create content file list from manifest.json + * Create contents file list from manifest.json */ export const sourceList = (manifest: ManifestV1JsonObject): string[] => { const list = ([] as string[]).concat( diff --git a/src/plugin/core/manifest/v2/index.ts b/src/plugin/core/manifest/v2/index.ts index 91c6d4d25c..89864de565 100644 --- a/src/plugin/core/manifest/v2/index.ts +++ b/src/plugin/core/manifest/v2/index.ts @@ -15,9 +15,6 @@ export class ManifestV2 implements ManifestInterface { return new ManifestV2(JSON.parse(manifestJson)); } - /** - * Load JSON file without caching - */ public static async loadJsonFile( jsonFilePath: string, driver?: DriverInterface, diff --git a/src/plugin/core/manifest/v2/sourcelist.ts b/src/plugin/core/manifest/v2/sourcelist.ts index a7f49c9dfc..a5e2f42bda 100644 --- a/src/plugin/core/manifest/v2/sourcelist.ts +++ b/src/plugin/core/manifest/v2/sourcelist.ts @@ -1,7 +1,7 @@ import type { ManifestV2JsonObject } from "./index"; /** - * Create content file list from manifest.json + * Create contents file list from manifest.json */ export const sourceListV2 = (manifest: ManifestV2JsonObject): string[] => { const list: string[] = []; diff --git a/src/plugin/core/plugin/index.ts b/src/plugin/core/plugin/index.ts index 05c685373e..9adbbd333d 100644 --- a/src/plugin/core/plugin/index.ts +++ b/src/plugin/core/plugin/index.ts @@ -8,6 +8,9 @@ import type { ManifestInterface } from "../manifest"; import consumers from "node:stream/consumers"; import { logger } from "../../../utils/log"; +/** + * Plugin represents plugin includes Contents, public key, and signature. + */ export interface PluginInterface extends DriverInterface {} export class PluginZip extends ZipFileDriver implements PluginInterface {