@bendyline/docblocks 2.6.2 → 2.7.0

package/dist/chunk-UK7R3RC7.js

@@ -0,0 +1,514 @@
+import {
+  parseWorkspacePath
+} from "./chunk-AYWKIZLD.js";
+
+// src/workspace-settings/settings.ts
+var WORKSPACE_SETTINGS_DIRECTORY = ".docblocks";
+var WORKSPACE_SETTINGS_PATH = ".docblocks/workspace.json";
+var WORKSPACE_SETTINGS_VERSION = 1;
+var DEFAULT_CATALOG_TITLE = "Documents";
+var DEFAULT_CATALOG_HTML_PATH = "index.html";
+var DEFAULT_CATALOG_JSON_PATH = "catalog.json";
+var WORKSPACE_SETTINGS_LIMITS = {
+  maxFileBytes: 64 * 1024,
+  maxTitleCharacters: 256,
+  maxPathCharacters: 1024,
+  maxSchemaCharacters: 2048,
+  maxExcludes: 64,
+  minKeep: 1,
+  maxKeep: 1e3
+};
+var WORKSPACE_THEME_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var CATALOG_SORT_ORDERS = ["title", "path", "date"];
+var CATALOG_JSON_CONTENT_MODES = ["metadata", "markdown"];
+var EMPTY_WORKSPACE_SETTINGS = Object.freeze({
+  version: WORKSPACE_SETTINGS_VERSION
+});
+var WorkspaceSettingsShapeError = class extends Error {
+};
+function fail(message) {
+  throw new WorkspaceSettingsShapeError(message);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactRecord(value, label, allowed) {
+  if (!isRecord(value)) fail(`${label} must be an object.`);
+  const unknownKey = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unknownKey !== void 0) fail(`${label} has an unknown field "${unknownKey}".`);
+  return value;
+}
+function optionalBoolean(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "boolean") fail(`${label} must be true or false.`);
+  return value;
+}
+function optionalTheme(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || !WORKSPACE_THEME_ID_PATTERN.test(value)) {
+    fail(`${label} must be a theme id such as "warm-earth".`);
+  }
+  return value;
+}
+function optionalTitle(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || !value.trim() || value.length > WORKSPACE_SETTINGS_LIMITS.maxTitleCharacters || hasControlCharacter(value)) {
+    fail(
+      `${label} must be non-empty text of at most ${WORKSPACE_SETTINGS_LIMITS.maxTitleCharacters} characters.`
+    );
+  }
+  return value;
+}
+function optionalEnum(value, label, allowed) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    fail(`${label} must be one of ${allowed.map((option) => `"${option}"`).join(", ")}.`);
+  }
+  return value;
+}
+function hasControlCharacter(value) {
+  return [...value].some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 31 || codePoint === 127;
+  });
+}
+function boundedPath(value, label) {
+  if (typeof value !== "string" || !value || value.length > WORKSPACE_SETTINGS_LIMITS.maxPathCharacters) {
+    fail(`${label} must be a workspace-relative path.`);
+  }
+  let path;
+  try {
+    path = parseWorkspacePath(value);
+  } catch {
+    fail(`${label} must be a workspace-relative path without "." or ".." segments.`);
+  }
+  if (!path) fail(`${label} must not be the workspace root.`);
+  return path;
+}
+var OUTPUT_EXTENSIONS = {
+  html: [".html", ".htm"],
+  json: [".json"]
+};
+function validateCatalogOutputPath(value, kind) {
+  const label = `catalog.${kind}.path`;
+  const path = boundedPath(value, label);
+  const lower = path.toLowerCase();
+  if (!OUTPUT_EXTENSIONS[kind].some((extension) => lower.endsWith(extension))) {
+    fail(`${label} must end with ${OUTPUT_EXTENSIONS[kind].join(" or ")}.`);
+  }
+  const segments = path.split("/");
+  for (const segment of segments) {
+    if (segment.startsWith(".")) fail(`${label} must not be inside a hidden folder.`);
+  }
+  for (const directory of segments.slice(0, -1)) {
+    if (directory.toLowerCase().endsWith("_files")) {
+      fail(`${label} must not be inside a document's _files folder.`);
+    }
+    if (directory === "_squisq") fail(`${label} must not be inside the _squisq folder.`);
+    if (directory === "node_modules") fail(`${label} must not be inside node_modules.`);
+  }
+  return path;
+}
+function checkCatalogOutputPath(value, kind) {
+  try {
+    return { ok: true, path: validateCatalogOutputPath(value, kind) };
+  } catch (error) {
+    return { ok: false, message: shapeMessage(error) };
+  }
+}
+function parseExclude(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) fail("catalog.exclude must be a list of folder or file paths.");
+  if (value.length > WORKSPACE_SETTINGS_LIMITS.maxExcludes) {
+    fail(`catalog.exclude may list at most ${WORKSPACE_SETTINGS_LIMITS.maxExcludes} paths.`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  value.forEach((entry, index) => {
+    const path = boundedPath(entry, `catalog.exclude[${index}]`);
+    if (!seen.has(path)) {
+      seen.add(path);
+      result.push(path);
+    }
+  });
+  return result;
+}
+function parseKeep(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < WORKSPACE_SETTINGS_LIMITS.minKeep || value > WORKSPACE_SETTINGS_LIMITS.maxKeep) {
+    fail(
+      `versionHistory.keep must be a whole number from ${WORKSPACE_SETTINGS_LIMITS.minKeep} to ${WORKSPACE_SETTINGS_LIMITS.maxKeep}.`
+    );
+  }
+  return value;
+}
+function compact(value) {
+  const entries = Object.entries(value).filter(([, field]) => field !== void 0);
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+function parseWorkspaceSettings(value) {
+  const root = isRecord(value) ? value : fail("Workspace settings must be a JSON object.");
+  const version = root.version;
+  if (typeof version === "number" && Number.isInteger(version) && version > 1) {
+    throw new UnsupportedWorkspaceSettingsVersionError(version);
+  }
+  exactRecord(root, "Workspace settings", [
+    "$schema",
+    "version",
+    "documents",
+    "versionHistory",
+    "catalog"
+  ]);
+  if (version !== WORKSPACE_SETTINGS_VERSION) fail('Workspace settings must have "version": 1.');
+  let $schema;
+  if (root.$schema !== void 0) {
+    if (typeof root.$schema !== "string" || root.$schema.length > WORKSPACE_SETTINGS_LIMITS.maxSchemaCharacters) {
+      fail("$schema must be a bounded string.");
+    }
+    $schema = root.$schema;
+  }
+  let documents;
+  if (root.documents !== void 0) {
+    const record = exactRecord(root.documents, "documents", ["defaultTheme"]);
+    documents = compact({
+      defaultTheme: optionalTheme(record.defaultTheme, "documents.defaultTheme")
+    });
+  }
+  let versionHistory;
+  if (root.versionHistory !== void 0) {
+    const record = exactRecord(root.versionHistory, "versionHistory", ["enabled", "keep"]);
+    versionHistory = compact({
+      enabled: optionalBoolean(record.enabled, "versionHistory.enabled"),
+      keep: parseKeep(record.keep)
+    });
+  }
+  let catalog;
+  if (root.catalog !== void 0) {
+    const record = exactRecord(root.catalog, "catalog", [
+      "title",
+      "sort",
+      "exclude",
+      "html",
+      "json"
+    ]);
+    let html;
+    if (record.html !== void 0) {
+      const htmlRecord = exactRecord(record.html, "catalog.html", ["enabled", "path", "theme"]);
+      html = compact({
+        enabled: optionalBoolean(htmlRecord.enabled, "catalog.html.enabled"),
+        path: htmlRecord.path === void 0 ? void 0 : validateCatalogOutputPath(htmlRecord.path, "html"),
+        theme: optionalTheme(htmlRecord.theme, "catalog.html.theme")
+      });
+    }
+    let json;
+    if (record.json !== void 0) {
+      const jsonRecord = exactRecord(record.json, "catalog.json", ["enabled", "path", "content"]);
+      json = compact({
+        enabled: optionalBoolean(jsonRecord.enabled, "catalog.json.enabled"),
+        path: jsonRecord.path === void 0 ? void 0 : validateCatalogOutputPath(jsonRecord.path, "json"),
+        content: optionalEnum(
+          jsonRecord.content,
+          "catalog.json.content",
+          CATALOG_JSON_CONTENT_MODES
+        )
+      });
+    }
+    catalog = compact({
+      title: optionalTitle(record.title, "catalog.title"),
+      sort: optionalEnum(record.sort, "catalog.sort", CATALOG_SORT_ORDERS),
+      exclude: parseExclude(record.exclude),
+      html,
+      json
+    });
+    const htmlPath = (html?.path ?? DEFAULT_CATALOG_HTML_PATH).toLowerCase();
+    const jsonPath = (json?.path ?? DEFAULT_CATALOG_JSON_PATH).toLowerCase();
+    if (htmlPath === jsonPath) fail("catalog.html.path and catalog.json.path must differ.");
+  }
+  return {
+    ...$schema !== void 0 ? { $schema } : {},
+    version: WORKSPACE_SETTINGS_VERSION,
+    ...documents ? { documents } : {},
+    ...versionHistory ? { versionHistory } : {},
+    ...catalog ? { catalog } : {}
+  };
+}
+var UnsupportedWorkspaceSettingsVersionError = class extends Error {
+  constructor(version) {
+    super(
+      `These workspace settings were written by a newer version of DocBlocks (settings version ${version}). Update DocBlocks to use or change them.`
+    );
+    this.version = version;
+    this.name = "UnsupportedWorkspaceSettingsVersionError";
+  }
+};
+function shapeMessage(error) {
+  if (error instanceof WorkspaceSettingsShapeError) return error.message;
+  if (error instanceof Error) return error.message;
+  return "Workspace settings are invalid.";
+}
+function parseWorkspaceSettingsText(text) {
+  const source = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+  if (new TextEncoder().encode(source).byteLength > WORKSPACE_SETTINGS_LIMITS.maxFileBytes) {
+    return {
+      status: "invalid",
+      message: `${WORKSPACE_SETTINGS_PATH} is larger than ${WORKSPACE_SETTINGS_LIMITS.maxFileBytes / 1024} KiB.`
+    };
+  }
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch (error) {
+    return {
+      status: "invalid",
+      message: `${WORKSPACE_SETTINGS_PATH} is not valid JSON${error instanceof Error ? `: ${error.message}` : "."}`
+    };
+  }
+  try {
+    return { status: "ok", settings: parseWorkspaceSettings(value) };
+  } catch (error) {
+    if (error instanceof UnsupportedWorkspaceSettingsVersionError) {
+      return { status: "unsupported-version", message: error.message };
+    }
+    return { status: "invalid", message: shapeMessage(error) };
+  }
+}
+function serializeWorkspaceSettings(settings) {
+  const normalized = parseWorkspaceSettings(settings);
+  const ordered = {};
+  if (normalized.$schema !== void 0) ordered.$schema = normalized.$schema;
+  ordered.version = normalized.version;
+  if (normalized.documents) {
+    ordered.documents = pick(normalized.documents, ["defaultTheme"]);
+  }
+  if (normalized.versionHistory) {
+    ordered.versionHistory = pick(normalized.versionHistory, ["enabled", "keep"]);
+  }
+  if (normalized.catalog) {
+    const catalog = normalized.catalog;
+    ordered.catalog = {
+      ...pick(catalog, ["title", "sort", "exclude"]),
+      ...catalog.html ? { html: pick(catalog.html, ["enabled", "path", "theme"]) } : {},
+      ...catalog.json ? { json: pick(catalog.json, ["enabled", "path", "content"]) } : {}
+    };
+  }
+  return `${JSON.stringify(ordered, null, 2)}
+`;
+}
+function pick(value, keys) {
+  const result = {};
+  for (const key of keys) {
+    if (value[key] !== void 0) result[key] = value[key];
+  }
+  return result;
+}
+function patchFields(base, patch) {
+  if (!patch) return base;
+  const next = { ...base ?? {} };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === void 0) continue;
+    if (value === null) delete next[key];
+    else next[key] = value;
+  }
+  return compact(next);
+}
+function applyWorkspaceSettingsPatch(base, patch) {
+  const current = base ?? EMPTY_WORKSPACE_SETTINGS;
+  const catalogPatch = patch.catalog;
+  let catalog = current.catalog;
+  if (catalogPatch) {
+    const { html: htmlPatch, json: jsonPatch, ...topPatch } = catalogPatch;
+    const top = patchFields(
+      current.catalog ? pick(current.catalog, ["title", "sort", "exclude"]) : void 0,
+      topPatch
+    );
+    catalog = compact({
+      ...top ?? {},
+      html: patchFields(current.catalog?.html, htmlPatch),
+      json: patchFields(current.catalog?.json, jsonPatch)
+    });
+  }
+  return parseWorkspaceSettings({
+    ...current.$schema !== void 0 ? { $schema: current.$schema } : {},
+    version: WORKSPACE_SETTINGS_VERSION,
+    ...optionalSection("documents", patchFields(current.documents, patch.documents)),
+    ...optionalSection("versionHistory", patchFields(current.versionHistory, patch.versionHistory)),
+    ...optionalSection("catalog", catalog)
+  });
+}
+function optionalSection(key, value) {
+  return value ? { [key]: value } : {};
+}
+function diffWorkspaceSettings(before, after) {
+  const base = before ?? EMPTY_WORKSPACE_SETTINGS;
+  const documents = diffFields(base.documents, after.documents, ["defaultTheme"]);
+  const versionHistory = diffFields(base.versionHistory, after.versionHistory, ["enabled", "keep"]);
+  const top = diffFields(
+    base.catalog,
+    after.catalog,
+    ["title", "sort", "exclude"]
+  );
+  const html = diffFields(base.catalog?.html, after.catalog?.html, ["enabled", "path", "theme"]);
+  const json = diffFields(base.catalog?.json, after.catalog?.json, ["enabled", "path", "content"]);
+  const catalog = top || html || json ? { ...top ?? {}, ...html ? { html } : {}, ...json ? { json } : {} } : void 0;
+  return {
+    ...documents ? { documents } : {},
+    ...versionHistory ? { versionHistory } : {},
+    ...catalog ? { catalog } : {}
+  };
+}
+function diffFields(before, after, keys) {
+  const patch = {};
+  for (const key of keys) {
+    const previous = before?.[key];
+    const next = after?.[key];
+    if (JSON.stringify(previous) === JSON.stringify(next)) continue;
+    patch[key] = next === void 0 ? null : next;
+  }
+  return Object.keys(patch).length > 0 ? patch : void 0;
+}
+function isEmptyWorkspaceSettingsPatch(patch) {
+  return !patch.documents && !patch.versionHistory && !patch.catalog;
+}
+function parseWorkspaceSettingsPatch(value) {
+  const root = exactRecord(value, "Workspace settings patch", [
+    "documents",
+    "versionHistory",
+    "catalog"
+  ]);
+  const nullable = (field, parse) => field === null ? null : parse(field);
+  const result = {};
+  if (root.documents !== void 0) {
+    const record = exactRecord(root.documents, "documents", ["defaultTheme"]);
+    result.documents = compact({
+      defaultTheme: nullable(
+        record.defaultTheme,
+        (input) => optionalTheme(input, "documents.defaultTheme")
+      )
+    }) ?? {};
+  }
+  if (root.versionHistory !== void 0) {
+    const record = exactRecord(root.versionHistory, "versionHistory", ["enabled", "keep"]);
+    result.versionHistory = compact({
+      enabled: nullable(
+        record.enabled,
+        (input) => optionalBoolean(input, "versionHistory.enabled")
+      ),
+      keep: nullable(record.keep, parseKeep)
+    }) ?? {};
+  }
+  if (root.catalog !== void 0) {
+    const record = exactRecord(root.catalog, "catalog", [
+      "title",
+      "sort",
+      "exclude",
+      "html",
+      "json"
+    ]);
+    const catalog = {
+      ...compact({
+        title: nullable(record.title, (input) => optionalTitle(input, "catalog.title")),
+        sort: nullable(
+          record.sort,
+          (input) => optionalEnum(input, "catalog.sort", CATALOG_SORT_ORDERS)
+        ),
+        exclude: nullable(record.exclude, parseExclude)
+      }) ?? {}
+    };
+    if (record.html !== void 0) {
+      const html = exactRecord(record.html, "catalog.html", ["enabled", "path", "theme"]);
+      catalog.html = compact({
+        enabled: nullable(
+          html.enabled,
+          (input) => optionalBoolean(input, "catalog.html.enabled")
+        ),
+        path: nullable(html.path, (input) => validateCatalogOutputPath(input, "html")),
+        theme: nullable(html.theme, (input) => optionalTheme(input, "catalog.html.theme"))
+      }) ?? {};
+    }
+    if (record.json !== void 0) {
+      const json = exactRecord(record.json, "catalog.json", ["enabled", "path", "content"]);
+      catalog.json = compact({
+        enabled: nullable(
+          json.enabled,
+          (input) => optionalBoolean(input, "catalog.json.enabled")
+        ),
+        path: nullable(json.path, (input) => validateCatalogOutputPath(input, "json")),
+        content: nullable(
+          json.content,
+          (input) => optionalEnum(input, "catalog.json.content", CATALOG_JSON_CONTENT_MODES)
+        )
+      }) ?? {};
+    }
+    result.catalog = catalog;
+  }
+  return result;
+}
+function tryApplyWorkspaceSettingsPatch(base, patch) {
+  try {
+    return { ok: true, settings: applyWorkspaceSettingsPatch(base, patch) };
+  } catch (error) {
+    return { ok: false, message: shapeMessage(error) };
+  }
+}
+function isDefaultWorkspaceSettings(settings) {
+  return settings?.documents?.defaultTheme === void 0 && settings?.versionHistory?.enabled === void 0 && settings?.versionHistory?.keep === void 0 && settings?.catalog?.html?.enabled !== true && settings?.catalog?.json?.enabled !== true;
+}
+function resolveWorkspaceDefaultThemeId(settings) {
+  return settings?.documents?.defaultTheme;
+}
+function resolveFallbackThemeId(frontmatterThemeId, settings) {
+  if (frontmatterThemeId) return void 0;
+  return resolveWorkspaceDefaultThemeId(settings);
+}
+function resolveWorkspaceVersioningEnabled(settings) {
+  return settings?.versionHistory?.enabled;
+}
+function resolveCatalogOutputs(settings) {
+  const catalog = settings?.catalog;
+  const htmlEnabled = catalog?.html?.enabled === true;
+  const jsonEnabled = catalog?.json?.enabled === true;
+  if (!htmlEnabled && !jsonEnabled) return null;
+  return {
+    title: catalog?.title ?? DEFAULT_CATALOG_TITLE,
+    sort: catalog?.sort ?? "title",
+    exclude: catalog?.exclude ?? [],
+    html: htmlEnabled ? {
+      path: validateCatalogOutputPath(catalog?.html?.path ?? DEFAULT_CATALOG_HTML_PATH, "html"),
+      themeId: catalog?.html?.theme ?? settings?.documents?.defaultTheme
+    } : null,
+    json: jsonEnabled ? {
+      path: validateCatalogOutputPath(catalog?.json?.path ?? DEFAULT_CATALOG_JSON_PATH, "json"),
+      content: catalog?.json?.content ?? "metadata"
+    } : null
+  };
+}
+
+export {
+  WORKSPACE_SETTINGS_DIRECTORY,
+  WORKSPACE_SETTINGS_PATH,
+  WORKSPACE_SETTINGS_VERSION,
+  DEFAULT_CATALOG_TITLE,
+  DEFAULT_CATALOG_HTML_PATH,
+  DEFAULT_CATALOG_JSON_PATH,
+  WORKSPACE_SETTINGS_LIMITS,
+  WORKSPACE_THEME_ID_PATTERN,
+  CATALOG_SORT_ORDERS,
+  CATALOG_JSON_CONTENT_MODES,
+  EMPTY_WORKSPACE_SETTINGS,
+  validateCatalogOutputPath,
+  checkCatalogOutputPath,
+  parseWorkspaceSettings,
+  UnsupportedWorkspaceSettingsVersionError,
+  parseWorkspaceSettingsText,
+  serializeWorkspaceSettings,
+  applyWorkspaceSettingsPatch,
+  diffWorkspaceSettings,
+  isEmptyWorkspaceSettingsPatch,
+  parseWorkspaceSettingsPatch,
+  tryApplyWorkspaceSettingsPatch,
+  isDefaultWorkspaceSettings,
+  resolveWorkspaceDefaultThemeId,
+  resolveFallbackThemeId,
+  resolveWorkspaceVersioningEnabled,
+  resolveCatalogOutputs
+};