@syncbridge/common 1.1.4 → 2.0.1

package/registry/extension-registry.js

@@ -5,20 +5,21 @@ import { updateErrorMessage } from '@jsopen/objects';
 import { ResponsiveMap } from '@opra/common';
 import { AsyncEventEmitter } from 'node-events-async';
 import semver from 'semver';
+import { AppBase } from '../classes/app-base.js';
 import { ComponentBase } from '../classes/component-base.js';
-import { ProcessorBase } from '../classes/processor-base.js';
 import { SbError } from '../classes/sb-error.js';
 import { CLASS_METADATA, CLASS_TYPE } from '../constants.js';
 import { locatePackageJson } from '../utils/locate-package-json.js';
-import { normalizeComponentMetadata, normalizeProcessorMetadata, } from '../utils/normalize-metadata.js';
+import { normalizeAppMetadata, normalizeComponentMetadata, normalizePluginMetadata, } from '../utils/normalize-metadata.js';
 import { uriToId } from '../utils/uri-to-id.js';
-import { ComponentExtension, ExtensionPackage, ProcessorExtension, } from './extension-package.js';
+import { AppExtension, ComponentExtension, ExtensionPackage, PluginExtension, } from './extension-package.js';
+import { readExtensionManifest } from './package-manifest.js';
 const instanceSymbol = Symbol.for('instance');
 /**
- * The `ExtensionRegistry` class is responsible for managing component and processor extensions,
+ * The `ExtensionRegistry` class is responsible for managing component and app extensions,
  * as well as handling the registration of extension packages. It provides methods to locate and
  * retrieve extensions by their class name and version, and offers the ability to dynamically register
- * packages, components, and processors at runtime.
+ * packages, components, and apps at runtime.
  *
  * @class ExtensionRegistry
  */
@@ -29,7 +30,7 @@ export class ExtensionRegistry extends AsyncEventEmitter {
     /** Registries made current with `use`, the last one in effect */
     static _inUse = [];
     /**
-     * The registry the static methods act on, and so ProcessorFactory and
+     * The registry the static methods act on, and so AppFactory and
      * the metadata helpers: the process's own, unless another is in use.
      */
     static get current() {
@@ -64,11 +65,11 @@ export class ExtensionRegistry extends AsyncEventEmitter {
     static get componentsByClassName() {
         return this[instanceSymbol].componentsByClassName;
     }
-    static get processors() {
-        return this[instanceSymbol].processors;
+    static get apps() {
+        return this[instanceSymbol].apps;
     }
-    static get processorsByClassName() {
-        return this[instanceSymbol].processorsByClassName;
+    static get appsByClassName() {
+        return this[instanceSymbol].appsByClassName;
     }
     static setResolver(fn) {
         this[instanceSymbol].setResolver(fn);
@@ -79,11 +80,11 @@ export class ExtensionRegistry extends AsyncEventEmitter {
     static getComponent(uri, version = '*') {
         return this[instanceSymbol].getComponent(uri, version);
     }
-    static findProcessor(uri, version = '*') {
-        return this[instanceSymbol].findProcessor(uri, version);
+    static findApp(uri, version = '*') {
+        return this[instanceSymbol].findApp(uri, version);
     }
-    static getProcessor(uri, version = '*') {
-        return this[instanceSymbol].getProcessor(uri, version);
+    static getApp(uri, version = '*') {
+        return this[instanceSymbol].getApp(uri, version);
     }
     static async registerPackage(specifier) {
         return this[instanceSymbol].registerPackage(specifier);
@@ -100,8 +101,8 @@ export class ExtensionRegistry extends AsyncEventEmitter {
     static onRegisterComponent(fn) {
         this[instanceSymbol].on('register-component', fn);
     }
-    static onRegisterProcessor(fn) {
-        this[instanceSymbol].on('register-processor', fn);
+    static onRegisterApp(fn) {
+        this[instanceSymbol].on('register-app', fn);
     }
     constructor() {
         super();
@@ -111,8 +112,8 @@ export class ExtensionRegistry extends AsyncEventEmitter {
     packages = new ResponsiveMap();
     components = new ResponsiveMap();
     componentsByClassName = new ResponsiveMap();
-    processors = new ResponsiveMap();
-    processorsByClassName = new ResponsiveMap();
+    apps = new ResponsiveMap();
+    appsByClassName = new ResponsiveMap();
     /**
      *
      */
@@ -140,18 +141,18 @@ export class ExtensionRegistry extends AsyncEventEmitter {
     /**
      *
      */
-    findProcessor(uri, version = '*') {
-        return this.processors
+    findApp(uri, version = '*') {
+        return this.apps
             .get(uriToId(uri))
             ?.find(v => semver.satisfies(v.version, version || '*'));
     }
     /**
      *
      */
-    getProcessor(uri, version = '*') {
-        const cmp = this.findProcessor(uri, version);
+    getApp(uri, version = '*') {
+        const cmp = this.findApp(uri, version);
         if (!cmp) {
-            throw new SbError(`Processor "${uri}${version ? `:${version}` : ''}" not found in registry`);
+            throw new SbError(`App "${uri}${version ? `:${version}` : ''}" not found in registry`);
         }
         return cmp;
     }
@@ -168,8 +169,11 @@ export class ExtensionRegistry extends AsyncEventEmitter {
         if (path.isAbsolute(entryPoint) && process.platform === 'win32') {
             entryPoint = pathToFileURL(entryPoint).href;
         }
+        const read = readExtensionManifest(pkgDir, pkgJson);
         const pkg = new ExtensionPackage();
-        pkg.assignManifest(pkgJson);
+        pkg.assignManifest(pkgJson, read?.manifest);
+        for (const field of read?.unknownFields || [])
+            pkg.warnings.push(`The manifest of "${pkg.name}": "${field}" is not known, passed over`);
         pkg.path = pkgDir;
         pkg.entryPoint = entryPoint;
         const module = await import(entryPoint);
@@ -194,19 +198,30 @@ export class ExtensionRegistry extends AsyncEventEmitter {
                 pkg.components = pkg.components || [];
                 pkg.components.push(new ComponentExtension(pkg, ctorName, metadata));
             }
-            else if (classType === 'processor') {
+            else if (classType === 'app') {
                 try {
-                    metadata = await normalizeProcessorMetadata(metadata);
+                    metadata = await normalizeAppMetadata(metadata);
                 }
                 catch (e) {
-                    updateErrorMessage(e, `Processor (${ctorName}) metadata validation error. ` + e.message);
+                    updateErrorMessage(e, `App (${ctorName}) metadata validation error. ` + e.message);
                     pkg.errors.push(e);
                     continue;
                 }
                 if (metadata.abstract)
                     continue;
-                pkg.processors = pkg.processors || [];
-                pkg.processors.push(new ProcessorExtension(pkg, ctorName, metadata));
+                pkg.apps = pkg.apps || [];
+                pkg.apps.push(new AppExtension(pkg, ctorName, metadata));
+            }
+            else if (classType === 'plugin') {
+                try {
+                    metadata = await normalizePluginMetadata(metadata);
+                }
+                catch (e) {
+                    updateErrorMessage(e, `Plugin (${ctorName}) metadata validation error. ` + e.message);
+                    pkg.errors.push(e);
+                    continue;
+                }
+                pkg.plugins.push(new PluginExtension(pkg, ctorName, metadata));
             }
         }
         this.storePackage(pkg);
@@ -222,8 +237,8 @@ export class ExtensionRegistry extends AsyncEventEmitter {
         if (classType === 'component') {
             metadata = await normalizeComponentMetadata(metadata);
         }
-        else if (classType === 'processor') {
-            metadata = await normalizeProcessorMetadata(metadata);
+        else if (classType === 'app') {
+            metadata = await normalizeAppMetadata(metadata);
         }
         else
             /* c8 ignore next */
@@ -250,8 +265,8 @@ export class ExtensionRegistry extends AsyncEventEmitter {
             pkg.components.push(out);
         }
         else {
-            out = new ProcessorExtension(pkg, ctor.name, metadata, ctor);
-            pkg.processors.push(out);
+            out = new AppExtension(pkg, ctor.name, metadata, ctor);
+            pkg.apps.push(out);
         }
         this.storePackage(pkg);
         return out;
@@ -273,8 +288,8 @@ export class ExtensionRegistry extends AsyncEventEmitter {
         pkgVersions.sort((a, b) => semver.compare(b.version, a.version));
         if (pkg.components?.length) {
             for (const cmp of pkg.components) {
-                if (this.findProcessor(cmp.uri, '*'))
-                    throw new SbError(`Component "${cmp.uri}" is already registered as a processor.`);
+                if (this.findApp(cmp.uri, '*'))
+                    throw new SbError(`Component "${cmp.uri}" is already registered as an app.`);
                 /** Store to components */
                 const id = uriToId(cmp.uri);
                 let items = this.components.get(id);
@@ -301,16 +316,16 @@ export class ExtensionRegistry extends AsyncEventEmitter {
                 this.emitSafe('register-component', cmp);
             }
         }
-        if (pkg.processors?.length) {
-            for (const prc of pkg.processors) {
+        if (pkg.apps?.length) {
+            for (const prc of pkg.apps) {
                 if (this.findComponent(prc.uri, '*'))
-                    throw new SbError(`Processor "${prc.uri}" is already registered as a component.`);
-                /** Store to processors */
+                    throw new SbError(`App "${prc.uri}" is already registered as a component.`);
+                /** Store to apps */
                 const id = uriToId(prc.uri);
-                let items = this.processors.get(id);
+                let items = this.apps.get(id);
                 if (!items) {
                     items = [];
-                    this.processors.set(id, items);
+                    this.apps.set(id, items);
                 }
                 i = items.findIndex(v => v.version === prc.version);
                 if (i >= 0)
@@ -320,10 +335,10 @@ export class ExtensionRegistry extends AsyncEventEmitter {
                     items.sort((a, b) => semver.compare(b.version, a.version));
                 }
                 /** Store to componentsByClassName */
-                items = this.processors.get(prc.className);
+                items = this.apps.get(prc.className);
                 if (!items) {
                     items = [];
-                    this.processorsByClassName.set(prc.className, items);
+                    this.appsByClassName.set(prc.className, items);
                 }
                 i = items.findIndex(v => v.version === prc.version);
                 if (i >= 0)
@@ -332,10 +347,9 @@ export class ExtensionRegistry extends AsyncEventEmitter {
                     items.push(prc);
                     items.sort((a, b) => semver.compare(b.version, a.version));
                 }
-                this.emitSafe('register-processor', prc);
+                this.emitSafe('register-app', prc);
             }
         }
         this.emitSafe('register-package', pkg);
     }
 }
-//# sourceMappingURL=extension-registry.js.map

package/registry/module-catalog.d.ts

@@ -0,0 +1,31 @@
+export declare const SUMMARY_MAX_LENGTH = 160;
+export declare const SCREENSHOTS_MAX = 8;
+/** A summary as told: one in the package's docs language, or one per language */
+export type ModuleSummary = string | Record<string, string>;
+/** What the Marketplace is told of a module, as its makers wrote it */
+export interface ModuleCatalogInput {
+    className: string;
+    summary?: ModuleSummary;
+    screenshots?: string[];
+}
+/** What is kept of it: its summary by language, its screenshots' paths */
+export interface ModuleCatalog {
+    summary?: Record<string, string>;
+    screenshots?: string[];
+}
+/**
+ * A module's Marketplace fields checked, and made what is kept: its
+ * summary by language (one alone, in the package's docs language), its
+ * screenshots as paths in the package (docs/<ClassName>/...), each among
+ * its documents. Problems told, none thrown: spm and the registry tell
+ * them their own way.
+ */
+export declare function checkModuleCatalog(input: ModuleCatalogInput, context: {
+    /** The package's docs language */
+    docsLanguage: string;
+    /** A file is among the package's documents */
+    hasDoc: (file: string) => boolean;
+}): {
+    catalog: ModuleCatalog;
+    problems: string[];
+};

package/registry/module-catalog.js

@@ -0,0 +1,88 @@
+import { DOC_TYPES, DOCS_DIR, isDocsLanguage } from './package-docs.js';
+/*
+ * How an app or a component is told in the Marketplace: what it is for, in
+ * a sentence (its summary), and how it looks (its screenshots, among its
+ * documents - not installed). Told by its makers on @App / @Component,
+ * checked by spm as it packs and by the registry as it takes the package.
+ * Where it is shown - what it does, what it talks to - is not its own to
+ * tell: the registry's groups, asked for in Console and decided there.
+ */
+export const SUMMARY_MAX_LENGTH = 160;
+export const SCREENSHOTS_MAX = 8;
+/**
+ * A module's Marketplace fields checked, and made what is kept: its
+ * summary by language (one alone, in the package's docs language), its
+ * screenshots as paths in the package (docs/<ClassName>/...), each among
+ * its documents. Problems told, none thrown: spm and the registry tell
+ * them their own way.
+ */
+export function checkModuleCatalog(input, context) {
+    const problems = [];
+    const catalog = {};
+    const name = input.className;
+    if (input.summary !== undefined) {
+        const told = typeof input.summary === 'string'
+            ? { [context.docsLanguage]: input.summary }
+            : input.summary && typeof input.summary === 'object'
+                ? input.summary
+                : {};
+        if (typeof input.summary !== 'string' && !Object.keys(told).length)
+            problems.push(`${name}'s summary is a sentence, or one per language: { en: '...', tr: '...' }`);
+        const summary = {};
+        for (const [language, text] of Object.entries(told)) {
+            if (!isDocsLanguage(language)) {
+                problems.push(`${name}'s summary is told in "${language}", not a language: en, tr, pt-BR...`);
+                continue;
+            }
+            if (typeof text !== 'string' || !text.trim()) {
+                problems.push(`${name}'s summary in ${language} is empty`);
+                continue;
+            }
+            const sentence = text.trim().replace(/\s+/g, ' ');
+            if (sentence.length > SUMMARY_MAX_LENGTH) {
+                problems.push(`${name}'s summary in ${language} is ${sentence.length} characters: ${SUMMARY_MAX_LENGTH} at most, a sentence`);
+                continue;
+            }
+            summary[language] = sentence;
+        }
+        if (Object.keys(summary).length)
+            catalog.summary = summary;
+    }
+    if (input.screenshots !== undefined) {
+        const own = `${DOCS_DIR}/${name}/`;
+        const screenshots = [];
+        for (const shot of input.screenshots) {
+            /* Told within its own documents' folder, or as a path in the package */
+            const file = typeof shot === 'string'
+                ? shot.startsWith(own)
+                    ? shot
+                    : own + shot.replace(/^\.?\//, '')
+                : '';
+            if (!file.startsWith(own) || file.includes('..')) {
+                problems.push(`${name}'s screenshot ${String(shot)} is not in ${own}: its own documents`);
+                continue;
+            }
+            const type = DOC_TYPES[extensionOf(file)];
+            if (type?.kind !== 'image') {
+                problems.push(`${name}'s screenshot ${file} is not an image: PNG, JPEG, GIF, WebP or SVG`);
+                continue;
+            }
+            if (!context.hasDoc(file)) {
+                problems.push(`${name}'s screenshot ${file} is not among the package's documents`);
+                continue;
+            }
+            screenshots.push(file);
+        }
+        if (screenshots.length > SCREENSHOTS_MAX)
+            problems.push(`${name} tells ${screenshots.length} screenshots: ${SCREENSHOTS_MAX} at most`);
+        else if (screenshots.length)
+            catalog.screenshots = [...new Set(screenshots)];
+    }
+    return { catalog, problems };
+}
+/** A file's extension, lower-cased: ".png" */
+function extensionOf(file) {
+    const base = file.slice(file.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    return dot > 0 ? base.slice(dot).toLowerCase() : '';
+}

package/registry/package-docs.d.ts

@@ -0,0 +1,98 @@
+/**
+ * A package's documents: docs/ in its source, put in what spm packs, taken
+ * out of it by the registry on publish - the field reads them from the
+ * registry, never from what it installs.
+ *
+ *   docs/<ClassName>/README.md      an app's, component's or plugin's page
+ *   docs/<ClassName>/**             its documents
+ *   docs/**                         the package's own (guides/, images/)
+ *
+ * A document is Markdown or PDF; an image is what they show. A document's
+ * languages share its name, each other than the package's own before its
+ * extension: network.md, network.tr.md, network.pt-BR.md - the one naming
+ * none in the language the manifest's `docsLanguage` names (English, if
+ * none). A document may be in another language alone (user-guide.en.pdf).
+ * How they are listed, a sidebar.json may tell (see docs-sidebar).
+ */
+export declare const DOCS_DIR = "docs";
+/** An app's, component's or plugin's page, in docs/<ClassName>/ */
+export declare const README_FILE = "README.md";
+/** The language of documents that name none, when the manifest names none */
+export declare const DEFAULT_DOCS_LANGUAGE = "en";
+/** All of a package's documents together, at most */
+export declare const DOCS_MAX_TOTAL_BYTES: number;
+/** What a file in docs/ is: read as a page, or shown in one */
+export type DocKind = 'document' | 'image';
+export interface DocType {
+    kind: DocKind;
+    contentType: string;
+    /** Its largest: larger, it is refused */
+    maxBytes: number;
+}
+/** The files docs/ may hold, by extension: no other is packed */
+export declare const DOC_TYPES: Readonly<Record<string, DocType>>;
+/**
+ * A directory in docs/ named as a class would be (UdpSocket): an app's,
+ * component's or plugin's. Others (guides, images, API) the package's own.
+ */
+export declare const CLASS_DIR_PATTERN: RegExp;
+/** Whether a document may be in this language: `tr`, `pt-BR` */
+export declare function isDocsLanguage(code: unknown): code is string;
+/** A file in docs/, as its path tells */
+export interface DocPath {
+    /** Its path in the package: docs/ModbusGateway/network.tr.md */
+    path: string;
+    type: DocType;
+    /** The class whose documents it is among; none: the package's own */
+    module?: string;
+    /** Its language, when its name tells one: a document's alone */
+    language?: string;
+    /**
+     * The document it is in another language of: docs/ModbusGateway/network.md
+     * for network.tr.md - itself, when it names no language
+     */
+    base: string;
+}
+/**
+ * Reads what a file in docs/ is from its path in the package (docs/...).
+ * Throws when docs/ may not hold it: a type it does not take, a name a link
+ * would need escaping for, or no path in docs/.
+ */
+export declare function parseDocPath(file: string): DocPath;
+/**
+ * Whether a file's bytes are what its extension says: a PDF begins as one,
+ * an image as its type, Markdown is UTF-8 text
+ */
+export declare function isDocContent(type: DocType, content: Uint8Array): boolean;
+/**
+ * What a publish tells of a package's documents when it leaves out the
+ * files its registry has: at the archive's root, each file of docs/ by its
+ * path, SHA-256 and size. A Markdown document is always sent - what it
+ * tells is read from it; a PDF or an image may be left out, if the
+ * package's earlier versions had it.
+ */
+export declare const DOCS_MANIFEST_FILE = "syncbridge-docs.json";
+export interface DocsManifest {
+    files: DocsManifestFile[];
+}
+export interface DocsManifestFile {
+    /** Its path in the package: docs/Gw/user-guide.en.pdf */
+    path: string;
+    /** Hex SHA-256 of the file */
+    sha256: string;
+    size: number;
+}
+/** Whether a publish may leave a file out, its registry having it */
+export declare function isDocLeftOut(type: DocType): boolean;
+/** A file of a package, by its path in the archive and its SHA-256 */
+export interface PackageFileDigest {
+    path: string;
+    sha256: string;
+}
+/**
+ * What a package holds, as one SHA-256: every file of its archive by its
+ * path and hash, sorted - the same however the archive was zipped, or
+ * whichever of its documents' files were left out (told by their hash).
+ * A publish is approved for it.
+ */
+export declare function packageDigest(files: readonly PackageFileDigest[]): Promise<string>;

package/registry/package-docs.js

@@ -0,0 +1,159 @@
+import { SbError } from '../classes/sb-error.js';
+/**
+ * A package's documents: docs/ in its source, put in what spm packs, taken
+ * out of it by the registry on publish - the field reads them from the
+ * registry, never from what it installs.
+ *
+ *   docs/<ClassName>/README.md      an app's, component's or plugin's page
+ *   docs/<ClassName>/**             its documents
+ *   docs/**                         the package's own (guides/, images/)
+ *
+ * A document is Markdown or PDF; an image is what they show. A document's
+ * languages share its name, each other than the package's own before its
+ * extension: network.md, network.tr.md, network.pt-BR.md - the one naming
+ * none in the language the manifest's `docsLanguage` names (English, if
+ * none). A document may be in another language alone (user-guide.en.pdf).
+ * How they are listed, a sidebar.json may tell (see docs-sidebar).
+ */
+export const DOCS_DIR = 'docs';
+/** An app's, component's or plugin's page, in docs/<ClassName>/ */
+export const README_FILE = 'README.md';
+/** The language of documents that name none, when the manifest names none */
+export const DEFAULT_DOCS_LANGUAGE = 'en';
+/** All of a package's documents together, at most */
+export const DOCS_MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+const KB = 1024;
+const MB = 1024 * KB;
+/** The files docs/ may hold, by extension: no other is packed */
+export const DOC_TYPES = {
+    '.md': {
+        kind: 'document',
+        contentType: 'text/markdown; charset=utf-8',
+        maxBytes: 256 * KB,
+    },
+    '.pdf': {
+        kind: 'document',
+        contentType: 'application/pdf',
+        maxBytes: 20 * MB,
+    },
+    '.png': { kind: 'image', contentType: 'image/png', maxBytes: 5 * MB },
+    '.jpg': { kind: 'image', contentType: 'image/jpeg', maxBytes: 5 * MB },
+    '.jpeg': { kind: 'image', contentType: 'image/jpeg', maxBytes: 5 * MB },
+    '.gif': { kind: 'image', contentType: 'image/gif', maxBytes: 5 * MB },
+    '.webp': { kind: 'image', contentType: 'image/webp', maxBytes: 5 * MB },
+    '.svg': { kind: 'image', contentType: 'image/svg+xml', maxBytes: 5 * MB },
+};
+/**
+ * A directory in docs/ named as a class would be (UdpSocket): an app's,
+ * component's or plugin's. Others (guides, images, API) the package's own.
+ */
+export const CLASS_DIR_PATTERN = /^[A-Z][a-z0-9][A-Za-z0-9]*$/;
+/** A file's or directory's name in docs/: one a link needs no escaping for */
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** A language a document is in: ISO 639-1, its region if any (pt-BR) */
+const LANGUAGE_PATTERN = /^([a-z]{2})(?:-([A-Z]{2}))?$/;
+/** A document's language in its name: network.tr.md, setup.pt-BR.pdf */
+const LANGUAGE_IN_NAME = /^(.+)\.([a-z]{2}(?:-[A-Z]{2})?)(\.(?:md|pdf))$/;
+/** ISO 639-1: the languages a document may be in */
+const LANGUAGES = new Set(('aa ab ae af ak am an ar as av ay az ba be bg bh bi bm bn bo br bs ca ce ' +
+    'ch co cr cs cu cv cy da de dv dz ee el en eo es et eu fa ff fi fj fo fr ' +
+    'fy ga gd gl gn gu gv ha he hi ho hr ht hu hy hz ia id ie ig ii ik io is ' +
+    'it iu ja jv ka kg ki kj kk kl km kn ko kr ks ku kv kw ky la lb lg li ln ' +
+    'lo lt lu lv mg mh mi mk ml mn mr ms mt my na nb nd ne ng nl nn no nr nv ' +
+    'ny oc oj om or os pa pi pl ps pt qu rm rn ro ru rw sa sc sd se sg si sk ' +
+    'sl sm sn so sq sr ss st su sv sw ta te tg th ti tk tl tn to tr ts tt tw ' +
+    'ty ug uk ur uz ve vi vo wa wo xh yi yo za zh zu').split(' '));
+/** Whether a document may be in this language: `tr`, `pt-BR` */
+export function isDocsLanguage(code) {
+    if (typeof code !== 'string')
+        return false;
+    const m = LANGUAGE_PATTERN.exec(code);
+    return !!m && LANGUAGES.has(m[1]);
+}
+/**
+ * Reads what a file in docs/ is from its path in the package (docs/...).
+ * Throws when docs/ may not hold it: a type it does not take, a name a link
+ * would need escaping for, or no path in docs/.
+ */
+export function parseDocPath(file) {
+    const segments = file.split('/');
+    if (segments[0] !== DOCS_DIR || segments.length < 2)
+        throw new SbError(`${file}: not in ${DOCS_DIR}/`);
+    const names = segments.slice(1);
+    const bad = names.find(n => !NAME_PATTERN.test(n));
+    if (bad !== undefined)
+        throw new SbError(`${file}: "${bad}" is not a name docs/ takes - letters, digits, ".", "_" and "-" alone, not starting with "." "_" or "-"`);
+    const name = names[names.length - 1];
+    const dot = name.lastIndexOf('.');
+    const type = dot > 0 ? DOC_TYPES[name.slice(dot).toLowerCase()] : undefined;
+    if (!type)
+        throw new SbError(`${file}: docs/ takes ${Object.keys(DOC_TYPES).join(', ')} files alone`);
+    const module = names.length > 1 && CLASS_DIR_PATTERN.test(names[0]) ? names[0] : undefined;
+    const m = type.kind === 'document' ? LANGUAGE_IN_NAME.exec(name) : null;
+    if (m && LANGUAGES.has(m[2].slice(0, 2)))
+        return {
+            path: file,
+            type,
+            module,
+            language: m[2],
+            base: [...segments.slice(0, -1), m[1] + m[3]].join('/'),
+        };
+    return { path: file, type, module, base: file };
+}
+/** The first bytes each type begins with: what a file claims, checked */
+const SIGNATURES = {
+    'application/pdf': b => ascii(b, 0, 5) === '%PDF-',
+    'image/png': b => ascii(b, 1, 4) === 'PNG' && b[0] === 0x89,
+    'image/jpeg': b => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff,
+    'image/gif': b => ascii(b, 0, 4) === 'GIF8',
+    'image/webp': b => ascii(b, 0, 4) === 'RIFF' && ascii(b, 8, 12) === 'WEBP',
+    'image/svg+xml': b => /<svg[\s>]/.test(ascii(b, 0, Math.min(b.length, 4096))),
+};
+function ascii(b, start, end) {
+    return String.fromCharCode(...b.subarray(start, end));
+}
+/**
+ * Whether a file's bytes are what its extension says: a PDF begins as one,
+ * an image as its type, Markdown is UTF-8 text
+ */
+export function isDocContent(type, content) {
+    if (type.contentType.startsWith('text/markdown')) {
+        try {
+            new TextDecoder('utf-8', { fatal: true }).decode(content);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return SIGNATURES[type.contentType]?.(content) ?? false;
+}
+/**
+ * What a publish tells of a package's documents when it leaves out the
+ * files its registry has: at the archive's root, each file of docs/ by its
+ * path, SHA-256 and size. A Markdown document is always sent - what it
+ * tells is read from it; a PDF or an image may be left out, if the
+ * package's earlier versions had it.
+ */
+export const DOCS_MANIFEST_FILE = 'syncbridge-docs.json';
+/** Whether a publish may leave a file out, its registry having it */
+export function isDocLeftOut(type) {
+    return !type.contentType.startsWith('text/markdown');
+}
+/**
+ * What a package holds, as one SHA-256: every file of its archive by its
+ * path and hash, sorted - the same however the archive was zipped, or
+ * whichever of its documents' files were left out (told by their hash).
+ * A publish is approved for it.
+ */
+export async function packageDigest(files) {
+    const lines = files
+        .filter(f => f.path !== DOCS_MANIFEST_FILE && !f.path.endsWith('/'))
+        .map(f => `${f.path}\t${f.sha256}\n`)
+        .sort()
+        .join('');
+    const hash = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(lines));
+    return [...new Uint8Array(hash)]
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}