@mandolin/jsdoc-plugin-hia-sys 0.1.0

package/src/micro-plugins/doclet-normalizer.cjs

@@ -0,0 +1,23 @@
+"use strict";
+
+module.exports = {
+  name: "doclet-normalizer",
+  order: 50,
+
+  newDoclet(event, context) {
+    if (!event || !event.doclet) {
+      return;
+    }
+
+    const doclet = event.doclet;
+    const metadata = context.markMicroPlugin(doclet, this.name);
+
+    metadata.doclet = {
+      name: doclet.name || "",
+      longname: doclet.longname || doclet.name || "",
+      kind: doclet.kind || "",
+      memberof: doclet.memberof || "",
+      scope: doclet.scope || ""
+    };
+  }
+};

package/src/micro-plugins/hia-ir-exporter.cjs

@@ -0,0 +1,68 @@
+"use strict";
+
+const {
+  buildOutputContract,
+  writeIntegrationOutput
+} = require("../runtime/output-contract.cjs");
+const { VERSION } = require("../version.cjs");
+
+function toNode(doclet, context) {
+  const metadata = context.ensureDocletHia(doclet);
+
+  return {
+    id: metadata.doclet.longname || metadata.doclet.name,
+    name: metadata.doclet.name,
+    longname: metadata.doclet.longname,
+    kind: metadata.doclet.kind,
+    source: metadata.source,
+    i18n: metadata.i18n
+  };
+}
+
+module.exports = {
+  name: "hia-ir-exporter",
+  order: 110,
+
+  parseComplete(event, context) {
+    const doclets = event && Array.isArray(event.doclets) ? event.doclets : [];
+
+    context.state.doclets = doclets;
+    context.state.integration.ir = {
+      version: VERSION,
+      mode: context.config.mode,
+      nodes: doclets.map((doclet) => toNode(doclet, context))
+    };
+  },
+
+  processingComplete(event, context) {
+    const doclets = event && Array.isArray(event.doclets)
+      ? event.doclets
+      : context.state.doclets;
+    const output = buildOutputContract(context.state, doclets);
+
+    context.state.output.standalone = output.standalone;
+    context.state.output.integration = output.integration;
+    context.state.output.themeContract = output.standalone.theme;
+    context.state.integration.ir = output.integration.ir;
+
+    try {
+      const writtenFile = writeIntegrationOutput(context.state, output.integration);
+
+      if (writtenFile) {
+        context.state.output.integrationOutputFile = writtenFile;
+      }
+    } catch (error) {
+      context.addDiagnostic({
+        code: "HIA_INTEGRATION_OUTPUT_WRITE_FAILED",
+        severity: "error",
+        message: `Cannot write HIA integration output: ${error.message}`,
+        plugin: this.name,
+        data: {
+          outputFile: context.config.integration.outputFile || ""
+        }
+      });
+      context.state.output.diagnostics = context.diagnostics.list();
+      context.state.output.diagnosticCounts = context.diagnostics.countBySeverity();
+    }
+  }
+};

package/src/micro-plugins/index.cjs

@@ -0,0 +1,23 @@
+"use strict";
+
+const codeFragment = require("./code-fragment.cjs");
+const diagnostics = require("./diagnostics.cjs");
+const docI18n = require("./doc-i18n.cjs");
+const docletNormalizer = require("./doclet-normalizer.cjs");
+const hiaIrExporter = require("./hia-ir-exporter.cjs");
+const sourceLink = require("./source-link.cjs");
+const sourcePreview = require("./source-preview.cjs");
+
+const builtInMicroPlugins = [
+  codeFragment,
+  sourceLink,
+  sourcePreview,
+  docI18n,
+  docletNormalizer,
+  hiaIrExporter,
+  diagnostics
+];
+
+module.exports = {
+  builtInMicroPlugins
+};

package/src/micro-plugins/source-link.cjs

@@ -0,0 +1,19 @@
+"use strict";
+
+module.exports = {
+  name: "source-link",
+  order: 20,
+
+  newDoclet(event, context) {
+    if (!event || !event.doclet) {
+      return;
+    }
+
+    const metadata = context.markMicroPlugin(event.doclet, this.name);
+    metadata.source.link = {
+      enabled: Boolean(context.config.source.link.enabled),
+      rootUrl: context.config.source.link.rootUrl,
+      openMode: context.config.source.link.openMode
+    };
+  }
+};

package/src/micro-plugins/source-preview.cjs

@@ -0,0 +1,18 @@
+"use strict";
+
+module.exports = {
+  name: "source-preview",
+  order: 30,
+
+  newDoclet(event, context) {
+    if (!event || !event.doclet) {
+      return;
+    }
+
+    const metadata = context.markMicroPlugin(event.doclet, this.name);
+    metadata.source.preview = {
+      enabled: Boolean(context.config.source.preview.enabled),
+      defaultExpanded: Boolean(context.config.source.preview.defaultExpanded)
+    };
+  }
+};

package/src/runtime/create-plugin-system.cjs

@@ -0,0 +1,120 @@
+"use strict";
+
+const { loadConfig } = require("../config/defaults.cjs");
+const { DiagnosticsCollector } = require("./diagnostics.cjs");
+const {
+  attachDiagnostics,
+  ensureDocletHia,
+  markMicroPlugin
+} = require("./metadata.cjs");
+
+function createInitialState(config) {
+  return {
+    config,
+    diagnostics: new DiagnosticsCollector(),
+    sourceFiles: new Map(),
+    registries: {
+      sourceFragments: new Map()
+    },
+    doclets: [],
+    integration: {
+      ir: null
+    },
+    output: {}
+  };
+}
+
+function createPluginContext(state) {
+  return {
+    state,
+    get config() {
+      return state.config;
+    },
+    diagnostics: state.diagnostics,
+    addDiagnostic(diagnostic) {
+      return state.diagnostics.add(diagnostic);
+    },
+    ensureDocletHia(doclet) {
+      return ensureDocletHia(doclet, state);
+    },
+    markMicroPlugin(doclet, pluginName) {
+      return markMicroPlugin(doclet, state, pluginName);
+    },
+    attachDiagnostics(doclet) {
+      return attachDiagnostics(doclet, state);
+    }
+  };
+}
+
+function sortMicroPlugins(microPlugins) {
+  return microPlugins.slice().sort((left, right) => {
+    return (left.order || 100) - (right.order || 100);
+  });
+}
+
+function filterEnabledMicroPlugins(microPlugins, config) {
+  const enabledNames = new Set(config.microPlugins || []);
+  return sortMicroPlugins(
+    microPlugins.filter((plugin) => enabledNames.has(plugin.name))
+  );
+}
+
+function createPluginSystem(options) {
+  const config = loadConfig(options && options.configOverrides);
+  const state = createInitialState(config);
+  const context = createPluginContext(state);
+  const microPlugins = filterEnabledMicroPlugins(
+    (options && options.microPlugins) || [],
+    config
+  );
+
+  for (const plugin of microPlugins) {
+    if (typeof plugin.setup === "function") {
+      plugin.setup(context);
+    }
+  }
+
+  function runHook(hookName, event) {
+    for (const plugin of microPlugins) {
+      const hook = plugin[hookName];
+
+      if (typeof hook !== "function") {
+        continue;
+      }
+
+      try {
+        hook.call(plugin, event, context);
+      } catch (error) {
+        context.addDiagnostic({
+          code: "HIA_PLUGIN_HOOK_FAILED",
+          severity: "error",
+          message: `${plugin.name}.${hookName} failed: ${error.message}`,
+          plugin: plugin.name
+        });
+
+        if (config.diagnostics.throwOnError) {
+          throw error;
+        }
+      }
+    }
+  }
+
+  return {
+    defineTags(dictionary) {
+      runHook("defineTags", { dictionary });
+    },
+    handle(hookName, event) {
+      runHook(hookName, event);
+    },
+    getState() {
+      return state;
+    },
+    getMicroPlugins() {
+      return microPlugins.slice();
+    }
+  };
+}
+
+module.exports = {
+  createPluginSystem
+};

package/src/runtime/diagnostics.cjs

@@ -0,0 +1,45 @@
+"use strict";
+
+const VALID_SEVERITIES = new Set(["error", "warning", "info"]);
+
+function normalizeSeverity(severity) {
+  return severity === "hint" ? "info" : severity;
+}
+
+class DiagnosticsCollector {
+  constructor() {
+    this.items = [];
+  }
+
+  add(diagnostic) {
+    const item = {
+      code: diagnostic.code || "HIA0000",
+      severity: VALID_SEVERITIES.has(normalizeSeverity(diagnostic.severity))
+        ? normalizeSeverity(diagnostic.severity)
+        : "warning",
+      message: diagnostic.message || "Unknown HIA diagnostic.",
+      plugin: diagnostic.plugin || "core",
+      filePath: diagnostic.filePath || "",
+      range: diagnostic.range || null,
+      data: diagnostic.data || null
+    };
+
+    this.items.push(item);
+    return item;
+  }
+
+  list() {
+    return this.items.slice();
+  }
+
+  countBySeverity() {
+    return this.items.reduce((counts, item) => {
+      counts[item.severity] = (counts[item.severity] || 0) + 1;
+      return counts;
+    }, {});
+  }
+}
+
+module.exports = {
+  DiagnosticsCollector
+};

package/src/runtime/i18n.cjs

@@ -0,0 +1,221 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function parseLocaleValue(value) {
+  const text = String(value || "").trim();
+  const match = /^(\S+)\s+([\s\S]+)$/.exec(text);
+
+  if (!match) {
+    return {
+      locale: "",
+      value: text
+    };
+  }
+
+  return {
+    locale: match[1],
+    value: match[2].trim()
+  };
+}
+
+function ensureLocaleBucket(target, locale) {
+  if (!target[locale]) {
+    target[locale] = {};
+  }
+
+  return target[locale];
+}
+
+function resolveResourcePath(resourcePath, config) {
+  if (path.isAbsolute(resourcePath)) {
+    return resourcePath;
+  }
+
+  const basePath =
+    config.i18n.resourceBasePath || config.source.basePath || process.cwd();
+
+  return path.resolve(basePath, resourcePath);
+}
+
+function toPosixPath(filePath) {
+  return String(filePath || "").split(path.sep).join("/");
+}
+
+function isSafeRelativePath(filePath) {
+  const text = toPosixPath(filePath);
+
+  return Boolean(text) &&
+    !path.isAbsolute(text) &&
+    !/^[A-Za-z]:\//.test(text) &&
+    !text.startsWith("/") &&
+    !text.startsWith("//") &&
+    !text.split("/").includes("..");
+}
+
+function getResourceRelativePath(absolutePath, resourcePath, config) {
+  if (isSafeRelativePath(resourcePath)) {
+    return toPosixPath(resourcePath);
+  }
+
+  const basePath =
+    config.i18n.resourceBasePath || config.source.basePath || process.cwd();
+  const relativePath = toPosixPath(path.relative(basePath, absolutePath));
+
+  if (isSafeRelativePath(relativePath)) {
+    return relativePath;
+  }
+
+  return path.basename(absolutePath);
+}
+
+function collectResourceFields(entries) {
+  const fields = new Set();
+
+  for (const localeEntries of Object.values(entries || {})) {
+    for (const [key, value] of Object.entries(localeEntries || {})) {
+      fields.add(key);
+
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        const nestedFields = value.fields && typeof value.fields === "object"
+          ? Object.keys(value.fields)
+          : [];
+
+        for (const fieldPath of nestedFields) {
+          fields.add(fieldPath);
+        }
+      }
+    }
+  }
+
+  return Array.from(fields).sort();
+}
+
+function normalizeResourceData(data, absolutePath) {
+  if (data && typeof data.locale === "string" && data.entries) {
+    return {
+      filePath: absolutePath,
+      entries: {
+        [data.locale]: data.entries
+      }
+    };
+  }
+
+  return {
+    filePath: absolutePath,
+    entries: data && typeof data === "object" ? data : {}
+  };
+}
+
+function loadLocalizationResources(config, diagnostics) {
+  const resources = [];
+  const entries = {};
+
+  for (const resourcePath of config.i18n.resources || []) {
+    const absolutePath = resolveResourcePath(resourcePath, config);
+
+    if (!fs.existsSync(absolutePath)) {
+      diagnostics.add({
+        code: "HIA_I18N_RESOURCE_MISSING",
+        severity: "error",
+        message: `Localization resource does not exist: ${resourcePath}`,
+        plugin: "doc-i18n",
+        filePath: absolutePath,
+        data: {
+          resourcePath
+        }
+      });
+      continue;
+    }
+
+    try {
+      const resource = normalizeResourceData(
+        JSON.parse(fs.readFileSync(absolutePath, "utf8")),
+        absolutePath
+      );
+
+      resources.push({
+        kind: "external-resource",
+        path: getResourceRelativePath(absolutePath, resourcePath, config),
+        format: "hia-i18n-json",
+        fields: collectResourceFields(resource.entries),
+        locales: Object.keys(resource.entries).sort(),
+        localeCount: Object.keys(resource.entries).length
+      });
+
+      for (const [locale, localeEntries] of Object.entries(resource.entries)) {
+        const bucket = ensureLocaleBucket(entries, locale);
+
+        for (const [key, value] of Object.entries(localeEntries || {})) {
+          if (Object.prototype.hasOwnProperty.call(bucket, key)) {
+            diagnostics.add({
+              code: "HIA_I18N_RESOURCE_KEY_DUPLICATE",
+              severity: "error",
+              message: `Duplicate localization resource key: ${locale}:${key}`,
+              plugin: "doc-i18n",
+              filePath: absolutePath,
+              data: {
+                locale,
+                key
+              }
+            });
+          }
+
+          bucket[key] = value;
+        }
+      }
+    } catch (error) {
+      diagnostics.add({
+        code: "HIA_I18N_RESOURCE_INVALID",
+        severity: "error",
+        message: `Cannot read localization resource ${resourcePath}: ${error.message}`,
+        plugin: "doc-i18n",
+        filePath: absolutePath,
+        data: {
+          resourcePath
+        }
+      });
+    }
+  }
+
+  return {
+    resources,
+    entries
+  };
+}
+
+function getResourceEntry(entries, locale, key) {
+  const bucket = entries[locale];
+
+  if (!bucket) {
+    return null;
+  }
+
+  return bucket[key] || null;
+}
+
+function normalizeLocalizedValue(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return {
+      text: value.text || value.description || "",
+      block: value.block || value.markdown || "",
+      source: "resource",
+      data: value
+    };
+  }
+
+  return {
+    text: String(value || ""),
+    block: "",
+    source: "resource",
+    data: value
+  };
+}
+
+module.exports = {
+  getResourceEntry,
+  loadLocalizationResources,
+  normalizeLocalizedValue,
+  parseLocaleValue
+};

package/src/runtime/metadata.cjs

@@ -0,0 +1,52 @@
+"use strict";
+
+const { VERSION } = require("../version.cjs");
+
+function ensureDocletHia(doclet, state) {
+  const key = state.config.metadataKey || "hia";
+
+  if (!doclet[key]) {
+    doclet[key] = {
+      version: VERSION,
+      mode: state.config.mode,
+      microPlugins: [],
+      doclet: {},
+      source: {
+        model: "hia-jsdoc-source",
+        modelVersion: "0.2.0",
+        mode: state.config.source.mode || "all",
+        definedIn: null,
+        primaryBlock: null,
+        fragments: [],
+        references: [],
+        diagnostics: []
+      },
+      i18n: {},
+      diagnostics: []
+    };
+  }
+
+  return doclet[key];
+}
+
+function markMicroPlugin(doclet, state, pluginName) {
+  const metadata = ensureDocletHia(doclet, state);
+
+  if (!metadata.microPlugins.includes(pluginName)) {
+    metadata.microPlugins.push(pluginName);
+  }
+
+  return metadata;
+}
+
+function attachDiagnostics(doclet, state) {
+  const metadata = ensureDocletHia(doclet, state);
+  metadata.diagnostics = state.diagnostics.list();
+  return metadata;
+}
+
+module.exports = {
+  attachDiagnostics,
+  ensureDocletHia,
+  markMicroPlugin
+};