@taprootio/docs-artifact 1.0.1

package/fixtures/invalid/duplicate-json-key.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"schemaVersion":1}

package/fixtures/invalid/hash-drift/taproot-docs/fragments/welcome.html

@@ -0,0 +1 @@
+<p>Welcome to the documentatioN.</p>

package/fixtures/invalid/size-drift/taproot-docs/fragments/welcome.html

@@ -0,0 +1 @@
+<p>Welcome to the documentation.</p>

package/fixtures/invalid/unsafe-markup/taproot-docs/fragments/welcome.html

@@ -0,0 +1 @@
+<script>alert(1)</script>

package/fixtures/valid/complete/taproot-docs/assets/pixel.png.base64

@@ -0,0 +1 @@
+iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=

package/fixtures/valid/complete/taproot-docs/fragments/button.en-us.html

@@ -0,0 +1 @@
+<p>Use <code data-language="html">&lt;esp-button&gt;</code>.</p>

package/fixtures/valid/complete/taproot-docs/fragments/button.fr-fr.html

@@ -0,0 +1 @@
+<p>Utilisez <code data-language="html">&lt;esp-button&gt;</code>.</p>

package/fixtures/valid/complete/taproot-docs/fragments/getting-started.en-us.html

@@ -0,0 +1,3 @@
+<p>Start here. <a data-resource-key="reference:button">Button reference</a></p>
+<h2 id="install">Install</h2>
+<p><img data-asset-key="image:pixel" alt="A single pixel" width="1" height="1"></p>

package/fixtures/valid/complete/taproot-docs/fragments/getting-started.fr-fr.html

@@ -0,0 +1,3 @@
+<p>Commencez ici. <a data-resource-key="reference:button">Référence du bouton</a></p>
+<h2 id="installer">Installer</h2>
+<p><img data-asset-key="image:pixel" alt="Un pixel" width="1" height="1"></p>

package/fixtures/valid/complete/taproot-docs-manifest.json

@@ -0,0 +1,231 @@
+{
+  "schemaVersion": 1,
+  "defaultLocale": "en-US",
+  "source": {
+    "provider": "github",
+    "repositoryId": "R_fixture_complete",
+    "repository": "taprootio/docs-fixture",
+    "repositoryUrl": "https://github.com/taprootio/docs-fixture",
+    "revision": "0123456789abcdef0123456789abcdef01234567",
+    "ref": "refs/heads/main"
+  },
+  "build": {
+    "producer": "@taprootio/wtfm",
+    "producerVersion": "1.0.0",
+    "configurationSha256": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+    "sourceDateEpoch": 1767225600
+  },
+  "capabilities": {
+    "required": [
+      "taproot.docs.fragments.html.v1"
+    ],
+    "optional": [
+      "taproot.docs.future-annotation.v1"
+    ]
+  },
+  "locales": [
+    {
+      "tag": "en-US",
+      "label": "English"
+    },
+    {
+      "tag": "fr-FR",
+      "label": "Français"
+    }
+  ],
+  "resources": [
+    {
+      "key": "guide:getting-started",
+      "semantic": {
+        "kind": "guide",
+        "audiences": [
+          "developer",
+          "user"
+        ],
+        "tags": [
+          "installation",
+          "quickstart"
+        ]
+      },
+      "variants": [
+        {
+          "locale": "en-US",
+          "route": "/guides/getting-started/",
+          "title": "Getting started",
+          "description": "Install the library and render your first button.",
+          "headings": [
+            {
+              "id": "install",
+              "text": "Install",
+              "level": 2
+            }
+          ],
+          "source": {
+            "path": "guides/getting-started.md",
+            "url": "https://github.com/taprootio/docs-fixture/blob/0123456789abcdef0123456789abcdef01234567/guides/getting-started.md"
+          },
+          "fragments": [
+            {
+              "key": "body",
+              "role": "body",
+              "path": "taproot-docs/fragments/getting-started.en-us.html",
+              "mediaType": "text/html; charset=utf-8",
+              "bytes": 194,
+              "sha256": "sha256:bc6882d8168672285d292fc40a289a4daa0f4fb3204409dd0d8665f6fef96d1c"
+            }
+          ]
+        },
+        {
+          "locale": "fr-FR",
+          "route": "/fr/guides/demarrage/",
+          "title": "Bien démarrer",
+          "description": "Installez la bibliothèque et affichez votre premier bouton.",
+          "headings": [
+            {
+              "id": "installer",
+              "text": "Installer",
+              "level": 2
+            }
+          ],
+          "source": {
+            "path": "guides/fr/getting-started.md",
+            "url": "https://github.com/taprootio/docs-fixture/blob/0123456789abcdef0123456789abcdef01234567/guides/fr/getting-started.md"
+          },
+          "fragments": [
+            {
+              "key": "body",
+              "role": "body",
+              "path": "taproot-docs/fragments/getting-started.fr-fr.html",
+              "mediaType": "text/html; charset=utf-8",
+              "bytes": 200,
+              "sha256": "sha256:0485393e88fb00ab1310430a15e968f96459696fd0d6363ed34e25e1df3430ea"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "key": "reference:button",
+      "semantic": {
+        "kind": "reference",
+        "audiences": [
+          "developer"
+        ],
+        "tags": [
+          "components"
+        ]
+      },
+      "variants": [
+        {
+          "locale": "en-US",
+          "route": "/components/button/",
+          "title": "Button",
+          "description": "Button component reference.",
+          "headings": [],
+          "source": {
+            "path": "src/button.ts",
+            "url": "https://github.com/taprootio/docs-fixture/blob/0123456789abcdef0123456789abcdef01234567/src/button.ts"
+          },
+          "fragments": [
+            {
+              "key": "body",
+              "role": "body",
+              "path": "taproot-docs/fragments/button.en-us.html",
+              "mediaType": "text/html; charset=utf-8",
+              "bytes": 65,
+              "sha256": "sha256:dfab2576f38131e44b1c583aa1ffca0624d60210e8d2d4fbf481f0cbf24e6625"
+            }
+          ]
+        },
+        {
+          "locale": "fr-FR",
+          "route": "/fr/composants/bouton/",
+          "title": "Bouton",
+          "description": "Référence du composant bouton.",
+          "headings": [],
+          "source": {
+            "path": "src/button.ts",
+            "url": "https://github.com/taprootio/docs-fixture/blob/0123456789abcdef0123456789abcdef01234567/src/button.ts"
+          },
+          "fragments": [
+            {
+              "key": "body",
+              "role": "body",
+              "path": "taproot-docs/fragments/button.fr-fr.html",
+              "mediaType": "text/html; charset=utf-8",
+              "bytes": 70,
+              "sha256": "sha256:1d275771bcb0e927d04d5fe97d546b4f3e99b077166ec6328ccec1d91881d459"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "navigation": [
+    {
+      "locale": "en-US",
+      "items": [
+        {
+          "label": "Guides",
+          "children": [
+            {
+              "label": "Getting started",
+              "resourceKey": "guide:getting-started"
+            }
+          ]
+        },
+        {
+          "label": "Reference",
+          "children": [
+            {
+              "label": "Button",
+              "resourceKey": "reference:button"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "locale": "fr-FR",
+      "items": [
+        {
+          "label": "Guides",
+          "children": [
+            {
+              "label": "Bien démarrer",
+              "resourceKey": "guide:getting-started"
+            }
+          ]
+        },
+        {
+          "label": "Référence",
+          "children": [
+            {
+              "label": "Bouton",
+              "resourceKey": "reference:button"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "redirects": [
+    {
+      "from": "/start/",
+      "toResourceKey": "guide:getting-started",
+      "locale": "en-US",
+      "status": 308
+    }
+  ],
+  "assets": [
+    {
+      "key": "image:pixel",
+      "path": "taproot-docs/assets/pixel.png",
+      "mediaType": "image/png",
+      "bytes": 68,
+      "sha256": "sha256:431ced6916a2a21a156e38701afe55bbd7f88969fbbfc56d7fe099d47f265460",
+      "width": 1,
+      "height": 1
+    }
+  ]
+}

package/fixtures/valid/minimal/taproot-docs/fragments/welcome.html

@@ -0,0 +1 @@
+<p>Welcome to the documentation.</p>

package/fixtures/valid/minimal/taproot-docs-manifest.json

@@ -0,0 +1,80 @@
+{
+  "schemaVersion": 1,
+  "defaultLocale": "en-US",
+  "source": {
+    "provider": "github",
+    "repositoryId": "R_fixture_minimal",
+    "repository": "taprootio/docs-fixture",
+    "repositoryUrl": "https://github.com/taprootio/docs-fixture",
+    "revision": "0123456789abcdef0123456789abcdef01234567",
+    "ref": "refs/heads/main"
+  },
+  "build": {
+    "producer": "@taprootio/wtfm",
+    "producerVersion": "1.0.0",
+    "configurationSha256": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+    "sourceDateEpoch": 1767225600
+  },
+  "capabilities": {
+    "required": [
+      "taproot.docs.fragments.html.v1"
+    ],
+    "optional": []
+  },
+  "locales": [
+    {
+      "tag": "en-US",
+      "label": "English"
+    }
+  ],
+  "resources": [
+    {
+      "key": "guide:welcome",
+      "semantic": {
+        "kind": "guide",
+        "audiences": [
+          "user"
+        ],
+        "tags": []
+      },
+      "variants": [
+        {
+          "locale": "en-US",
+          "route": "/welcome/",
+          "title": "Welcome",
+          "description": "A minimal conforming documentation resource.",
+          "headings": [],
+          "source": {
+            "path": "guides/welcome.md",
+            "url": "https://github.com/taprootio/docs-fixture/blob/0123456789abcdef0123456789abcdef01234567/guides/welcome.md",
+            "startLine": 1,
+            "endLine": 3
+          },
+          "fragments": [
+            {
+              "key": "body",
+              "role": "body",
+              "path": "taproot-docs/fragments/welcome.html",
+              "mediaType": "text/html; charset=utf-8",
+              "bytes": 37,
+              "sha256": "sha256:13977afe13c21fc2fd5962f7155c0df0ca57bb4550f5fd08ec982a46e28709a1"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "navigation": [
+    {
+      "locale": "en-US",
+      "items": [
+        {
+          "label": "Welcome",
+          "resourceKey": "guide:welcome"
+        }
+      ]
+    }
+  ],
+  "redirects": [],
+  "assets": []
+}

package/index.d.ts

@@ -0,0 +1,204 @@
+export interface DocsArtifactSource {
+  provider: "github";
+  repositoryId: string;
+  repository: string;
+  repositoryUrl: string;
+  revision: string;
+  ref: string;
+}
+
+export interface DocsArtifactBuild {
+  producer: string;
+  producerVersion: string;
+  configurationSha256: string;
+  sourceDateEpoch: number;
+}
+
+export interface DocsArtifactCapabilities {
+  required: string[];
+  optional: string[];
+}
+
+export interface DocsLocale {
+  tag: string;
+  label: string;
+}
+
+export type DocsResourceKind = "api" | "changelog" | "concept" | "guide" | "other" | "reference";
+export type DocsAudience = "administrator" | "developer" | "operator" | "user";
+
+export interface DocsSemanticMetadata {
+  kind: DocsResourceKind;
+  audiences: DocsAudience[];
+  tags: string[];
+}
+
+export interface DocsHeading {
+  id: string;
+  text: string;
+  level: 2 | 3 | 4 | 5 | 6;
+}
+
+export interface DocsSourceLocation {
+  path: string;
+  url: string;
+  startLine?: number;
+  endLine?: number;
+}
+
+export type DocsFragmentRole = "aside" | "body" | "example";
+
+export interface DocsFragment {
+  key: string;
+  role: DocsFragmentRole;
+  path: string;
+  mediaType: "text/html; charset=utf-8";
+  bytes: number;
+  sha256: string;
+}
+
+export interface DocsResourceVariant {
+  locale: string;
+  route: string;
+  title: string;
+  description: string;
+  headings: DocsHeading[];
+  source: DocsSourceLocation;
+  fragments: DocsFragment[];
+}
+
+export interface DocsResource {
+  key: string;
+  semantic: DocsSemanticMetadata;
+  variants: DocsResourceVariant[];
+}
+
+export interface DocsNavigationNode {
+  label: string;
+  resourceKey?: string;
+  children?: DocsNavigationNode[];
+}
+
+export interface DocsNavigation {
+  locale: string;
+  items: DocsNavigationNode[];
+}
+
+export interface DocsRedirect {
+  from: string;
+  toResourceKey: string;
+  locale: string;
+  status: 301 | 308;
+}
+
+export type DocsAssetMediaType = "image/gif" | "image/jpeg" | "image/png" | "image/webp";
+
+export interface DocsAsset {
+  key: string;
+  path: string;
+  mediaType: DocsAssetMediaType;
+  bytes: number;
+  sha256: string;
+  width: number;
+  height: number;
+}
+
+export interface DocsArtifactManifest {
+  schemaVersion: 1;
+  defaultLocale: string;
+  source: DocsArtifactSource;
+  build: DocsArtifactBuild;
+  capabilities: DocsArtifactCapabilities;
+  locales: DocsLocale[];
+  resources: DocsResource[];
+  navigation: DocsNavigation[];
+  redirects: DocsRedirect[];
+  assets: DocsAsset[];
+}
+
+export interface DocsArtifactValidationErrorItem {
+  code: string;
+  path: string;
+  message: string;
+}
+
+export type ValidationResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; errors: DocsArtifactValidationErrorItem[] };
+
+export interface ValidationOptions {
+  /**
+   * At most LIMITS.supportedCapabilities canonical resource-key strings, each
+   * no longer than LIMITS.resourceKey.
+   */
+  supportedCapabilities?: Iterable<string> & object;
+}
+
+export type ManifestInput = DocsArtifactManifest | string | Uint8Array | ArrayBuffer;
+export type ArtifactFileContent = string | Uint8Array | ArrayBuffer;
+
+export interface ArtifactFileEntry {
+  path: string;
+  content: ArtifactFileContent;
+}
+
+export interface ValidatedArtifact {
+  manifest: DocsArtifactManifest;
+  fileCount: number;
+  totalBytes: number;
+}
+
+export class DocsArtifactValidationError extends Error {
+  readonly errors: DocsArtifactValidationErrorItem[];
+  constructor(errors: DocsArtifactValidationErrorItem[]);
+}
+
+export interface NormalizedPath {
+  ok: true;
+  value: string;
+}
+
+export interface InvalidPath {
+  ok: false;
+  code: string;
+  message: string;
+}
+
+export interface DocsArtifactLimits {
+  readonly [name: string]: number;
+  readonly decodedPixels: number;
+  readonly decodedAnimationPixels: number;
+  readonly animationFrames: number;
+  readonly supportedCapabilities: number;
+  readonly resourceKey: number;
+}
+
+export const MANIFEST_FILE_NAME: "taproot-docs-manifest.json";
+export const SCHEMA_VERSION: 1;
+export const HTML_FRAGMENT_CAPABILITY: "taproot.docs.fragments.html.v1";
+export const SUPPORTED_CAPABILITIES: readonly string[];
+export const ASSET_MEDIA_TYPES: readonly DocsAssetMediaType[];
+export const AUDIENCES: readonly DocsAudience[];
+export const FRAGMENT_MEDIA_TYPE: "text/html; charset=utf-8";
+export const FRAGMENT_ROLES: readonly DocsFragmentRole[];
+export const RESOURCE_KINDS: readonly DocsResourceKind[];
+export const RESERVED_ROUTE_PREFIXES: readonly string[];
+export const RESERVED_ROUTES: readonly string[];
+export const LIMITS: Readonly<DocsArtifactLimits>;
+
+export function normalizeArtifactPath(value: unknown): NormalizedPath | InvalidPath;
+export function normalizeSourcePath(value: unknown): NormalizedPath | InvalidPath;
+export function normalizeRoute(value: unknown): NormalizedPath | InvalidPath;
+export function validateManifest(input: unknown, options?: ValidationOptions): ValidationResult<DocsArtifactManifest>;
+export function assertValidManifest(input: unknown, options?: ValidationOptions): DocsArtifactManifest;
+export function serializeManifest(input: unknown, options?: ValidationOptions): string;
+export function validateArtifact(
+  manifest: unknown,
+  files: Iterable<ArtifactFileEntry>,
+  options?: ValidationOptions,
+): Promise<ValidationResult<ValidatedArtifact>>;
+export function assertValidArtifact(
+  manifest: unknown,
+  files: Iterable<ArtifactFileEntry>,
+  options?: ValidationOptions,
+): Promise<ValidatedArtifact>;

package/node.d.ts

@@ -0,0 +1,6 @@
+import type { ValidatedArtifact, ValidationOptions, ValidationResult } from "./index.js";
+
+export function validateArtifactDirectory(
+  rootDirectory: string,
+  options?: ValidationOptions,
+): Promise<ValidationResult<ValidatedArtifact>>;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@taprootio/docs-artifact",
+  "version": "1.0.1",
+  "description": "Canonical Taproot Docs artifact schema, validator, and conformance fixtures",
+  "type": "module",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/taprootio/trunk.git",
+    "directory": "packages/docs-artifact"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./node": {
+      "types": "./node.d.ts",
+      "import": "./src/node.js"
+    },
+    "./conformance": {
+      "types": "./conformance.d.ts",
+      "import": "./src/conformance.js"
+    },
+    "./schema": "./schema/taproot-docs-manifest.schema.json",
+    "./fixtures/conformance.json": "./fixtures/conformance.json"
+  },
+  "bin": {
+    "taproot-docs-validate": "./bin/taproot-docs-validate.js"
+  },
+  "files": [
+    "bin/",
+    "fixtures/",
+    "schema/",
+    "src/",
+    "LICENSE",
+    "README.md",
+    "index.d.ts",
+    "node.d.ts",
+    "conformance.d.ts"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "conformance": "node ./bin/taproot-docs-conformance.js",
+    "prepack": "npm test && npm run conformance"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}