@vormio/plugin-sdk 0.0.6 → 0.0.7-rc.1

package/README.md

@@ -1,8 +1,8 @@
 # @vormio/plugin-sdk
 
-The manifest schema, runtime helpers and packaging command for writing Vormio plugins, plus the commands that publish a signed plugin catalog. The package is versioned with Vormio-Core (currently 0.0.6) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.6`.
+The manifest schema, runtime helpers and packaging command for writing Vormio plugins, plus the commands that publish a signed plugin catalog. The package is versioned with Vormio-Core (currently 0.0.7) and published to npm under the MIT license: `npm install @vormio/plugin-sdk@0.0.7`.
 
-Plugin contract version: `apiVersion: 2`. During development (0.0.x) there is no cross-version compatibility promise: the host loads only plugins with the same `apiVersion` as its own.
+Plugin contract version: `apiVersion: 3`. During development (0.0.x) there is no cross-version compatibility promise: the host loads only plugins with the same `apiVersion` as its own.
 
 ## What a plugin can do
 
@@ -28,7 +28,7 @@ A plugin is a folder: a `manifest.json` at the root plus the built static files.
 
 ```json
 {
-  "apiVersion": 2,
+  "apiVersion": 3,
   "id": "acme.model-viewer",
   "version": "0.1.0",
   "name": "Model Viewer",
@@ -164,6 +164,7 @@ interface CompositionReport {
     key?: string // Points to a subresource in this file; give exactly one of uri and key
     role: string // Display role, e.g. "Base color texture"
     evidence?: string // Location in the file, e.g. "/images/2/uri"
+    inferred?: string // Not written in the file: how you inferred it, e.g. "Same name as the skeleton"
   }[]
   /** Problems found during analysis, at most 500. */
   diagnostics: { severity: 'error' | 'warning' | 'info'; message: string; key?: string }[]
@@ -172,12 +173,37 @@ interface CompositionReport {
 }
 ```
 
-- The host validates reports with `compositionReportSchema` (`parseReport` also checks the size); plugins can check themselves against the same schema before returning. The report serialized as JSON is at most 4 MiB (counted in UTF-8 bytes). Names and keys are at most 200 characters, kinds and roles 80, evidence 300, diagnostics 500 and addresses 2,048. Names, kinds, roles and evidence must not contain control characters.
-- The report is invalid if it has duplicate keys, a `parent`, `from` or `key` that points to a missing subresource, a cyclic hierarchy, or a reference with both or neither of `uri` and `key`.
+- The host validates reports with `compositionReportSchema` (`parseReport` also checks the size); plugins can check themselves against the same schema before returning. The report serialized as JSON is at most 4 MiB (counted in UTF-8 bytes). Names and keys are at most 200 characters, kinds and roles 80, bases of inference 120, evidence 300, diagnostics 500 and addresses 2,048. Names, kinds, roles, bases of inference and evidence must not contain control characters.
+- The report is invalid if it has duplicate keys, a `parent`, `from` or `key` that points to a missing subresource, a cyclic hierarchy, a reference with both or neither of `uri` and `key`, or an `inferred` reference with a `key`.
 - Write `uri` exactly as it appears in the file; do not resolve it yourself. The host decodes percent-encoding once, ignores everything after `?` and `#`, treats `\` as `/`, resolves it relative to the analyzed file and classifies it: a file in the linked folder, out of bounds (`..` leaving the linked folder), embedded (`data:`), external (absolute paths, drive letters, other schemes) or invalid (undecodable, containing control characters, or pointing to a folder). Whether the target exists is decided by the host at query time.
 - For embedded data (`data:`), report only the header up to the comma, e.g. `data:image/png;base64`. The host classifies it as embedded by prefix and does not store the content; a full `data:` address often exceeds 2,048 characters and would invalidate the whole report.
 - Reporting a reference does not require reading the target file, so you do not need `companionFormats` just to report references. Declare them only when the analysis actually reads companion files.
 
+### Inferred references
+
+Some formats pair files by convention rather than by an address in the file. A Spine skeleton does not name its atlas; the runtime pairs `hero.json` with `hero.atlas` because they share a name. Report such a relation as an inferred reference, with the basis of the inference in `inferred`:
+
+```ts
+analyzer(async (input) => {
+  const skeleton = parseSkeleton(await readInput(input))
+  const atlas = `${input.name.replace(/\.[^.]*$/, '')}.atlas`
+  return {
+    ...skeleton.report,
+    references: [
+      ...skeleton.report.references,
+      { uri: atlas, role: 'Atlas', inferred: 'Same name as the skeleton' },
+    ],
+  }
+})
+```
+
+- Mark a reference as inferred only when the file does not write the address. References read from the file stay as they are.
+- The basis is shown to the user as is. Say why you think the relation exists, not where it is.
+- Write the address relative to the analyzed file and do not check that the target exists: the host decides at query time, so a target that appears or disappears needs no new analysis.
+- The host shows inferred references apart from written ones. A missing target is shown as "not found": it does not count as a missing reference, does not appear in the missing references filter and gets no note about where a moved file went, because the convention may simply not apply.
+- The inference may depend on the file's name. When an analyzed file with inferred references is renamed or moved, the host analyzes it again.
+- Do not report the same target both as written and as inferred.
+
 ## Packaging and development
 
 The package declares `"sideEffects": false`: when a plugin page uses only the runtime helpers, bundlers (esbuild, Vite, Rollup, webpack) drop the manifest schema and its zod dependency, leaving about 1 KB of runtime code for a minimal page. Node-side packaging and validation are imported from `@vormio/plugin-sdk/node`.
@@ -190,6 +216,8 @@ The command validates the manifest and every file, then writes a zip-format `.vo
 
 During development, open the **插件** (Plugins) page in Vormio, choose **添加开发目录…** (Add development folder…) and point it at the build output folder. The host watches the folder: every change is validated again, and a valid build reloads the plugin. If validation fails, the last valid version stays loaded and the error is shown on the plugin card. Vormio never runs build commands.
 
+When the host lacks something your plugin needs, or behaves wrongly, open an issue at [Vormio/Vormio-Core](https://github.com/Vormio/Vormio-Core/issues) with the plugin request template: the scenario, the plugin capability it blocks, what you expect, and how to tell it works. Host capabilities are added in a generic form, never for one format. A contract change may first ship as a prerelease under the npm tag `next` (`npm install @vormio/plugin-sdk@next`) so you can try it; `latest` follows Vormio releases.
+
 ## Plugin catalogs
 
 A plugin catalog is a signed `catalog.json` plus the plugin packages it lists, on static hosting. Vormio installs and updates plugins from it. Publishers produce one with two commands:

package/dist/bridge.d.ts

@@ -39,6 +39,11 @@ export interface ReportReference {
     role: string;
     /** Where in the file the reference is, such as "/images/2/uri". */
     evidence?: string;
+    /**
+     * The reference is not written in the file: how the analyzer inferred it, shown to the user, such
+     * as "Same name as the skeleton". Only with `uri`. A missing target is "not found", not missing.
+     */
+    inferred?: string;
 }
 export interface ReportDiagnostic {
     severity: 'error' | 'warning' | 'info';

package/dist/manifest.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 /** The plugin contract version this SDK describes. Hosts load only plugins with this version. */
-export declare const pluginApiVersion = 2;
+export declare const pluginApiVersion = 3;
 declare const contributionSchema: z.ZodObject<{
     id: z.ZodString;
     entry: z.ZodString;
@@ -13,7 +13,7 @@ export declare const pluginIdSchema: z.ZodString;
 /** A semantic version without build metadata. */
 export declare const versionSchema: z.ZodString;
 export declare const manifestSchema: z.ZodObject<{
-    apiVersion: z.ZodLiteral<2>;
+    apiVersion: z.ZodLiteral<3>;
     id: z.ZodString;
     version: z.ZodString;
     name: z.ZodString;

package/dist/manifest.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { checkPackagePath } from "./package-rules.js";
 /** The plugin contract version this SDK describes. Hosts load only plugins with this version. */
-export const pluginApiVersion = 2;
+export const pluginApiVersion = 3;
 const unique = (values) => new Set(values).size === values.length;
 const extension = z.string().regex(/^[a-z0-9]{1,16}$/, 'Use a lower-case extension without a dot');
 const extensions = (min) => z.array(extension).min(min).max(64).refine(unique, 'Extensions must not repeat');

package/dist/report.js

@@ -27,9 +27,13 @@ const referenceSchema = z
     key: key.optional(),
     role: plain(80).min(1),
     evidence: plain(300).optional(),
+    inferred: plain(120).min(1).optional(),
 })
     .refine((reference) => (reference.uri === undefined) !== (reference.key === undefined), {
     message: 'Give exactly one of uri and key',
+})
+    .refine((reference) => reference.inferred === undefined || reference.uri !== undefined, {
+    message: 'Only a reference with a uri can be inferred',
 });
 const diagnosticSchema = z.strictObject({
     severity: z.enum(['error', 'warning', 'info']),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vormio/plugin-sdk",
-  "version": "0.0.6",
+  "version": "0.0.7-rc.1",
   "description": "Manifest schema, runtime helpers and packaging for Vormio plugins.",
   "license": "MIT",
   "keywords": [