@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/foundation/doc-compiler/overlays.mjs

@@ -0,0 +1,206 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Translation overlays for component and hook docs.
+ *
+ * @input An authored component or hook doc and the translation its module
+ *   exports for the reading language (`docsZh`, `docsDense`).
+ * @output The doc in that language: translated text laid over the authored
+ *   doc, never dropping a prop, param, or field the translation has not
+ *   caught up with.
+ * @position Used by ./compile.mjs when it lowers a component or hook doc, so
+ *   every reader sees one overlay rule. Reference topics overlay by section in
+ *   ./compile.mjs instead.
+ */
+
+/**
+ * The translation a doc module exports for `lang`, or null.
+ * @param {Record<string, any>} mod
+ * @param {string | null} lang
+ * @returns {any}
+ */
+export function translationFor(mod, lang) {
+  const key = lang === 'zh' ? 'docsZh' : lang === 'dense' ? 'docsDense' : null;
+  return key && mod?.[key] ? mod[key] : null;
+}
+
+/**
+ * Lay a translation over an authored component or hook doc. A translation
+ * that carries props is a full translated doc, overlaid prop by prop; any other
+ * is a set of translated strings merged onto the doc.
+ * @param {any} docs
+ * @param {any} translation
+ * @returns {any}
+ */
+export function overlayAuthoredDoc(docs, translation) {
+  if (
+    translation.props ||
+    translation.components?.some((/** @type {any} */ c) => c.props)
+  ) {
+    return overlayComponentDoc(docs, translation);
+  }
+  return mergeTranslation(docs, translation);
+}
+
+/**
+ * @param {any} docs
+ * @param {any} translation
+ * @returns {any}
+ */
+export function mergeTranslation(docs, translation) {
+  if (!translation) return docs;
+
+  /** @type {any} */
+  const merged = {...docs};
+
+  // Merge prose into usage
+  if (merged.usage) {
+    merged.usage = {...merged.usage};
+    if (translation.usage?.description)
+      merged.usage.description = translation.usage.description;
+    else if (translation.description)
+      merged.usage.description = translation.description;
+    if (translation.usage?.bestPractices)
+      merged.usage.bestPractices = translation.usage.bestPractices;
+    if (translation.usage?.accessibility)
+      merged.usage.accessibility = translation.usage.accessibility;
+  }
+
+  // Legacy top-level fields (for docsZh that are full ComponentDoc clones)
+  if (translation.description && !merged.usage)
+    merged.description = translation.description;
+
+  // Merge prop descriptions for single-component docs
+  if (translation.propDescriptions && merged.props) {
+    merged.props = merged.props.map((/** @type {any} */ prop) => {
+      const desc = translation.propDescriptions[prop.name];
+      return desc != null ? {...prop, description: desc} : prop;
+    });
+  }
+
+  // Merge hook param descriptions (HookTranslationDoc). Params are an array of
+  // {name, type, description, required}; override description by name where the
+  // translation has an entry. Names may include dots (e.g. 'options.isActive');
+  // the lookup is keyed by the exact param name.
+  if (translation.paramDescriptions && merged.params) {
+    merged.params = merged.params.map((/** @type {any} */ param) => {
+      const desc = translation.paramDescriptions[param.name];
+      return desc != null ? {...param, description: desc} : param;
+    });
+  }
+
+  // Merge hook return descriptions (HookTranslationDoc). Returns are an array
+  // of {name, type, description}; override description by name where present.
+  if (translation.returnDescriptions && merged.returns) {
+    merged.returns = merged.returns.map((/** @type {any} */ ret) => {
+      const desc = translation.returnDescriptions[ret.name];
+      return desc != null ? {...ret, description: desc} : ret;
+    });
+  }
+
+  // Merge sub-component translations
+  if (translation.components && merged.components) {
+    merged.components = merged.components.map(
+      (/** @type {any} */ comp, /** @type {any} */ i) => {
+        const trans =
+          translation.components.find(
+            (/** @type {any} */ t) => t.name === comp.name,
+          ) || translation.components[i];
+        if (!trans) return comp;
+
+        const mergedComp = {...comp};
+        if (trans.description) mergedComp.description = trans.description;
+        if (trans.propDescriptions && comp.props) {
+          mergedComp.props = comp.props.map((/** @type {any} */ prop) => {
+            const desc = trans.propDescriptions[prop.name];
+            return desc != null ? {...prop, description: desc} : prop;
+          });
+        }
+        return mergedComp;
+      },
+    );
+  }
+
+  return merged;
+}
+
+/**
+ * Overlay a full-ComponentDoc-shaped translation onto the English doc.
+ *
+ * Base order and completeness win; the translation supplies text for the
+ * entries it covers. Props are matched by name, never by position, so a
+ * translation that is missing entries (or lists them in another order) can no
+ * longer drop or misattribute one.
+ *
+ * @param {any} docs Base (English) component doc.
+ * @param {any} translation Translated doc, possibly covering only some props.
+ * @returns {any} Merged doc with every base prop present.
+ */
+function overlayComponentDoc(docs, translation) {
+  /** Merge one prop list: keep base entries and order, translate what's covered.
+   * @param {any[] | undefined} baseProps
+   * @param {any[] | undefined} tProps
+   */
+  const overlayProps = (baseProps, tProps) => {
+    if (!baseProps) return baseProps;
+    const byName = new Map(
+      (tProps ?? []).map((/** @type {any} */ p) => [p.name, p]),
+    );
+    return baseProps.map((/** @type {any} */ prop) => {
+      const t = byName.get(prop.name);
+      // Take the translated text, but never let it drop the prop's contract
+      // (type/default/required stay authoritative from the English doc).
+      return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;
+    });
+  };
+
+  /** Preserve canonical structured guidance added after legacy full-doc translations,
+   * without changing established translated prose behavior.
+   * @param {any} baseUsage
+   * @param {any} translatedUsage
+   */
+  const mergeUsage = (baseUsage, translatedUsage) => {
+    if (!translatedUsage) return baseUsage;
+    return {
+      ...translatedUsage,
+      ...(translatedUsage.accessibility === undefined &&
+      baseUsage?.accessibility !== undefined
+        ? {accessibility: baseUsage.accessibility}
+        : null),
+      ...(translatedUsage.accessibilityThemeCoverage === undefined &&
+      baseUsage?.accessibilityThemeCoverage !== undefined
+        ? {accessibilityThemeCoverage: baseUsage.accessibilityThemeCoverage}
+        : null),
+      ...(translatedUsage.anatomy === undefined &&
+      baseUsage?.anatomy !== undefined
+        ? {anatomy: baseUsage.anatomy}
+        : null),
+    };
+  };
+
+  const merged = {
+    ...docs,
+    ...translation,
+    usage: mergeUsage(docs.usage, translation.usage),
+  };
+
+  merged.props = overlayProps(docs.props, translation.props);
+
+  if (docs.components) {
+    const tByName = new Map(
+      (translation.components ?? []).map((/** @type {any} */ c) => [c.name, c]),
+    );
+    merged.components = docs.components.map((/** @type {any} */ base) => {
+      const t = tByName.get(base.name);
+      if (!t) return base;
+      return {
+        ...base,
+        ...t,
+        usage: mergeUsage(base.usage, t.usage),
+        props: overlayProps(base.props, t.props),
+      };
+    });
+  }
+
+  return merged;
+}

package/foundation/doc-compiler/parse-readable.d.mts

@@ -0,0 +1,9 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {any}
+ */
+export function parseReadableDoc(input: unknown, label?: string): any;

package/foundation/doc-compiler/parse-readable.mjs

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file parseDoc as every reader outside the themes root has always seen it.
+ *
+ * @input Any authored doc value and a label for messages.
+ * @output The parsed doc, or the parser's error.
+ * @position The public `parseDoc` also accepts theme descriptors. Component,
+ *   hook, self-doc, and topic readers never did: to them a theme descriptor is
+ *   an unsupported type, with the message they have always printed.
+ */
+
+import {parseDoc} from '../../authoring/doctypes/parse.mjs';
+
+/**
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {any}
+ */
+export function parseReadableDoc(input, label = 'doc') {
+  const type =
+    input && typeof input === 'object' && 'type' in input
+      ? /** @type {{type?: unknown}} */ (input).type
+      : undefined;
+  if (type === 'theme') {
+    throw new Error(`${label} has unsupported type ${JSON.stringify(type)}.`);
+  }
+  return parseDoc(input, label);
+}

package/foundation/doc-compiler/read.d.mts

@@ -0,0 +1,127 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Lower one descriptor file. Memoized per file and options for the life of the
+ * process; a file that failed to load is tried again on the next read, as a
+ * fresh import would be.
+ * @param {string} file absolute path
+ * @param {ReadOptions} options
+ * @param {{node?: boolean}} [want] also build the sealed node
+ * @returns {Promise<import('./compile.mjs').LoweredDoc>}
+ */
+export function compileDocFile(file: string, options: ReadOptions, { node }?: {
+    node?: boolean;
+}): Promise<import("./compile.mjs").LoweredDoc>;
+/**
+ * What a reader gets for one descriptor: the view it has always read.
+ *
+ * `strict` readers check the doc and throw what they always threw: the import
+ * error, the parser's error (for an empty export too), then a failed
+ * translation. Other readers skip the check, throw only what importing or
+ * translating threw, and read an empty export as the empty value itself.
+ * The view is shared, as the module's own export always was.
+ * @param {string} file absolute path
+ * @param {ReadOptions & {strict?: boolean}} options
+ * @returns {Promise<any>}
+ */
+export function readDocView(file: string, options: ReadOptions & {
+    strict?: boolean;
+}): Promise<any>;
+/**
+ * Freeze a value and everything in it.
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+export function deepFreeze<T>(value: T): T;
+/**
+ * Where the `lang` overlay of a doc file lives: `{topic}.doc.{lang}.mjs`.
+ * @param {string} docPath
+ * @param {string} lang
+ * @returns {string}
+ */
+export function overlayPath(docPath: string, lang: string): string;
+/**
+ * The overlay languages a topic ships for its own file or any extension.
+ * @param {import('../discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {string[]}
+ */
+export function overlayLanguages(entry: import("../discovery/docs-discovery.mjs").DocsTopicEntry): string[];
+/**
+ * Load one topic file and the overlay for `lang`. A failure is recorded on the
+ * result, not thrown, so the compiler reports it in reading order.
+ * @param {string} docPath
+ * @param {string | null} lang
+ * @returns {Promise<import('./compile.mjs').AuthoredFile>}
+ */
+export function loadTopicFile(docPath: string, lang: string | null): Promise<import("./compile.mjs").AuthoredFile>;
+/**
+ * Everything the compiler needs for one topic, read from disk.
+ * @param {import('../discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {string | null} lang
+ * @returns {Promise<import('./compile.mjs').ReferenceTopicInput>}
+ */
+export function loadTopicInput(entry: import("../discovery/docs-discovery.mjs").DocsTopicEntry, lang: string | null): Promise<import("./compile.mjs").ReferenceTopicInput>;
+/**
+ * How each root's module names its doc, in precedence order: the `??` chain
+ * each reader has always used, so a file that exports two docs keeps serving
+ * the one it served before.
+ */
+export const DOC_EXPORTS: Readonly<{
+    components: string[];
+    hooks: string[];
+    templates: string[];
+    'self-docs': string[];
+    tree: string[];
+}>;
+/** The localized overlays a docs read can apply. */
+export const OVERLAY_LANGUAGES: string[];
+export type ReadOptions = {
+    root: "components" | "hooks" | "templates" | "themes" | "self-docs" | "tree";
+    /**
+     * overlay language; null reads the authored
+     * text
+     */
+    lang?: string | null | undefined;
+    /**
+     * how a parse error names the file (default: its
+     * file name)
+     */
+    label?: string | undefined;
+    /**
+     * the owning package, when the caller knows it
+     */
+    provider?: string | undefined;
+    /**
+     * the node's id (default: provider, root, and file
+     * name)
+     */
+    id?: string | undefined;
+    /**
+     * how to import the module (default
+     * `user`)
+     */
+    loader?: "template" | "native" | "user" | undefined;
+    /**
+     * which exports name the doc, in
+     * precedence order, for a reader that has always read a narrower set than its
+     * root's default ({@link DOC_EXPORTS})
+     */
+    exports?: readonly string[] | undefined;
+    /**
+     * for themes: the descriptor value, read
+     * without executing the file
+     */
+    readStatic?: (() => unknown) | undefined;
+    /**
+     * which value the view carries: the
+     * authored export (default) or its parser's result, for a reader that has
+     * always read the checked value
+     */
+    value?: "authored" | "parsed" | undefined;
+    /**
+     * hold the doc to its kind's parser
+     */
+    check?: boolean | undefined;
+};

package/foundation/doc-compiler/read.mjs

@@ -0,0 +1,325 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Doc reader — authored files in, lowered docs out, for every doc kind.
+ *
+ * @input A descriptor file, the root that reads it (components, hooks,
+ *   templates, themes, self-docs, or doc topics), the reading language, and
+ *   how strictly the reader checks.
+ * @output The lowered doc for that file. Readers get the view they have always
+ *   read, lowered afresh on every read; a whole-project compile also gets the
+ *   sealed node, memoized per file for the life of the process. For doc
+ *   topics: the compiler input for a topic, with its extensions and overlays
+ *   loaded.
+ * @position Loads authored doc files for the readers in api/ and clients/ and
+ *   hands each to ./compile.mjs. Each reader keeps its own loader, export
+ *   order, and strictness, so what it prints is what it printed before.
+ *   ./doc-loads.test.mjs lists, site by site, every other place the CLI runs
+ *   anything but its static imports of other CLI code, the doc reads that skip
+ *   this module among them: discovery's catalog fields, each command's
+ *   self-docs for its help text, and the build-time README. A new site fails
+ *   it. It catches every ordinary way of running code, whatever the local
+ *   names; deliberate obfuscation is out of scope. Internal to the CLI:
+ *   nothing here is public API.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  importDocModule,
+  importNativeModule,
+  importTemplateModule,
+} from './import.mjs';
+import {lowerDoc, parserFor} from './compile.mjs';
+import {translationFor} from './overlays.mjs';
+import {parseReadableDoc} from './parse-readable.mjs';
+import {packageOf, packageSource} from './source.mjs';
+
+/**
+ * How each root's module names its doc, in precedence order: the `??` chain
+ * each reader has always used, so a file that exports two docs keeps serving
+ * the one it served before.
+ */
+export const DOC_EXPORTS = Object.freeze({
+  components: ['default', 'docs'],
+  hooks: ['default', 'docs'],
+  templates: ['default', 'doc'],
+  'self-docs': ['doc', 'docs', 'default'],
+  // The docs tree's own files: namespace docs and the guides it places.
+  tree: ['docs', 'default'],
+});
+
+/** How a reader imports a doc module. */
+const LOADERS = Object.freeze({
+  // jiti for `.ts`, native otherwise: the checked loaders' import.
+  user: importDocModule,
+  // A plain `import()`: what the unchecked readers have always used.
+  native: importNativeModule,
+  // jiti with JSX for `.ts`: template discovery's import.
+  template: importTemplateModule,
+});
+
+/**
+ * @typedef {object} ReadOptions
+ * @property {'components' | 'hooks' | 'templates' | 'themes' | 'self-docs' | 'tree'} root
+ * @property {string | null} [lang] overlay language; null reads the authored
+ *   text
+ * @property {string} [label] how a parse error names the file (default: its
+ *   file name)
+ * @property {string} [provider] the owning package, when the caller knows it
+ * @property {string} [id] the node's id (default: provider, root, and file
+ *   name)
+ * @property {keyof typeof LOADERS} [loader] how to import the module (default
+ *   `user`)
+ * @property {readonly string[]} [exports] which exports name the doc, in
+ *   precedence order, for a reader that has always read a narrower set than its
+ *   root's default ({@link DOC_EXPORTS})
+ * @property {() => unknown} [readStatic] for themes: the descriptor value, read
+ *   without executing the file
+ * @property {'authored' | 'parsed'} [value] which value the view carries: the
+ *   authored export (default) or its parser's result, for a reader that has
+ *   always read the checked value
+ * @property {boolean} [check] hold the doc to its kind's parser
+ */
+
+/** @type {Map<string, Promise<import('./compile.mjs').LoweredDoc>>} */
+const lowered = new Map();
+
+/**
+ * Lower one descriptor file. Memoized per file and options for the life of the
+ * process; a file that failed to load is tried again on the next read, as a
+ * fresh import would be.
+ * @param {string} file absolute path
+ * @param {ReadOptions} options
+ * @param {{node?: boolean}} [want] also build the sealed node
+ * @returns {Promise<import('./compile.mjs').LoweredDoc>}
+ */
+export function compileDocFile(file, options, {node = false} = {}) {
+  const lang = options.lang ?? null;
+  const check = options.check === true;
+  const key = JSON.stringify([
+    path.resolve(file),
+    options.root,
+    lang,
+    options.label ?? null,
+    options.provider ?? null,
+    options.id ?? null,
+    options.loader ?? 'user',
+    options.exports ?? null,
+    options.value ?? 'authored',
+    check,
+    node,
+  ]);
+  let result = lowered.get(key);
+  if (!result) {
+    result = loadAuthored(file, options, lang).then(authored => {
+      const provider = options.provider ?? packageOf(file);
+      const out = lowerDoc(
+        {
+          id:
+            options.id ?? `${provider}:${options.root}:${path.basename(file)}`,
+          root: options.root,
+          provider,
+          source: packageSource(file),
+          lang,
+          file: authored,
+          ...(options.label ? {label: options.label} : {}),
+          ...(options.value === 'parsed' ? {useParsed: true} : {}),
+        },
+        {check, node},
+      );
+      if (out.node) deepFreeze(out.node);
+      if (out.loadFailed || 'overlayError' in authored) {
+        lowered.delete(key);
+      }
+      return out;
+    });
+    lowered.set(key, result);
+  }
+  return result;
+}
+
+/**
+ * What a reader gets for one descriptor: the view it has always read.
+ *
+ * `strict` readers check the doc and throw what they always threw: the import
+ * error, the parser's error (for an empty export too), then a failed
+ * translation. Other readers skip the check, throw only what importing or
+ * translating threw, and read an empty export as the empty value itself.
+ * The view is shared, as the module's own export always was.
+ * @param {string} file absolute path
+ * @param {ReadOptions & {strict?: boolean}} options
+ * @returns {Promise<any>}
+ */
+export async function readDocView(file, options) {
+  const strict = options.strict === true;
+  const lang = options.lang ?? null;
+  // Lowered on every read, as the readers always loaded: Node caches the
+  // module, and the translation and the check run fresh each time, so a
+  // reader never shares a translated or parsed result with the next one.
+  const provider = options.provider ?? packageOf(file);
+  const result = lowerDoc(
+    {
+      id: options.id ?? `${provider}:${options.root}:${path.basename(file)}`,
+      root: options.root,
+      provider,
+      source: packageSource(file),
+      lang,
+      file: await loadAuthored(file, options, lang),
+      ...(options.label ? {label: options.label} : {}),
+      ...(options.value === 'parsed' ? {useParsed: true} : {}),
+    },
+    {check: strict || options.check === true, node: false},
+  );
+  if (result.loadFailed) throw result.loadFailure;
+  if (result.missing) {
+    if (strict)
+      parserFor(options.root)(result.missingValue, options.label ?? file);
+    return result.missingValue;
+  }
+  if (strict && result.failed) throw result.failure;
+  if (result.overlayFailed) throw result.overlayFailure;
+  return result.view;
+}
+
+/**
+ * Load one file as its root reads it: the doc its module exports and, for a
+ * component or hook, the translation it exports for `lang`.
+ * @param {string} file
+ * @param {ReadOptions} options
+ * @param {string | null} lang
+ * @returns {Promise<import('./compile.mjs').AuthoredFile>}
+ */
+async function loadAuthored(file, options, lang) {
+  const name = path.basename(file);
+  if (options.root === 'themes') {
+    if (!options.readStatic) {
+      throw new Error(
+        'A theme descriptor is read statically; pass readStatic.',
+      );
+    }
+    try {
+      return {file: name, doc: options.readStatic()};
+    } catch (error) {
+      return {file: name, error};
+    }
+  }
+  let mod;
+  try {
+    mod = await LOADERS[options.loader ?? 'user'](file);
+  } catch (error) {
+    return {file: name, error};
+  }
+  // `a ?? b ?? c`, exactly: the first value that is not null or undefined,
+  // else the last one.
+  const [first, ...rest] = options.exports ?? DOC_EXPORTS[options.root];
+  let doc = mod?.[first];
+  for (const key of rest) doc = doc ?? mod?.[key];
+  const overlay =
+    lang && (options.root === 'components' || options.root === 'hooks')
+      ? translationFor(mod, lang)
+      : null;
+  return overlay ? {file: name, doc, overlay} : {file: name, doc};
+}
+
+/**
+ * Freeze a value and everything in it.
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+export function deepFreeze(value) {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+// ── Doc topics ─────────────────────────────────────────────────────────────
+
+/** The localized overlays a docs read can apply. */
+export const OVERLAY_LANGUAGES = ['zh', 'dense'];
+
+/**
+ * Where the `lang` overlay of a doc file lives: `{topic}.doc.{lang}.mjs`.
+ * @param {string} docPath
+ * @param {string} lang
+ * @returns {string}
+ */
+export function overlayPath(docPath, lang) {
+  return path.join(
+    path.dirname(docPath),
+    `${path.basename(docPath, '.doc.mjs')}.doc.${lang}.mjs`,
+  );
+}
+
+/**
+ * The overlay languages a topic ships for its own file or any extension.
+ * @param {import('../discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {string[]}
+ */
+export function overlayLanguages(entry) {
+  const files = [entry.path, ...entry.extensions.map(ext => ext.path)];
+  return OVERLAY_LANGUAGES.filter(lang =>
+    files.some(file => fs.existsSync(overlayPath(file, lang))),
+  );
+}
+
+/**
+ * Load one topic file and the overlay for `lang`. A failure is recorded on the
+ * result, not thrown, so the compiler reports it in reading order.
+ * @param {string} docPath
+ * @param {string | null} lang
+ * @returns {Promise<import('./compile.mjs').AuthoredFile>}
+ */
+export async function loadTopicFile(docPath, lang) {
+  const file = path.basename(docPath);
+  let doc;
+  try {
+    const mod = await importNativeModule(docPath);
+    doc = parseReadableDoc(mod.docs ?? mod.default, file);
+  } catch (error) {
+    return {file, error};
+  }
+  if (!lang) return {file, doc};
+  const translationPath = overlayPath(docPath, lang);
+  if (!fs.existsSync(translationPath)) return {file, doc};
+  try {
+    const translationMod = await importNativeModule(translationPath);
+    return {
+      file,
+      doc,
+      overlay: translationMod.docsZh || translationMod.docsDense || null,
+    };
+  } catch (overlayError) {
+    return {file, doc, overlayError};
+  }
+}
+
+/**
+ * Everything the compiler needs for one topic, read from disk.
+ * @param {import('../discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {string | null} lang
+ * @returns {Promise<import('./compile.mjs').ReferenceTopicInput>}
+ */
+export async function loadTopicInput(entry, lang) {
+  const extensions = [];
+  for (const extension of entry.extensions) {
+    extensions.push({
+      ...(await loadTopicFile(extension.path, lang)),
+      provider: extension.package,
+      providerId: extension.providerId ?? extension.package,
+    });
+  }
+  return {
+    id: entry.name,
+    provider: entry.package,
+    providerId: entry.providerId ?? entry.package,
+    replaces: entry.replaces ?? null,
+    lang,
+    base: await loadTopicFile(entry.path, lang),
+    extensions,
+    ...(entry.tree === true ? {tree: true} : {}),
+  };
+}