@rwdocs/backstage-plugin-rw-common 0.1.4

package/config.d.ts

@@ -0,0 +1,56 @@
+export interface Config {
+  /** @visibility backend */
+  rw?: {
+    /**
+     * Local directory containing documentation source files.
+     * Mutually exclusive with `s3`.
+     */
+    projectDir?: string;
+    /**
+     * Entity ref that the local projectDir serves as (required when projectDir is set).
+     * Standard Backstage entity ref format: "kind:namespace/name" (e.g. "component:default/my-docs")
+     */
+    entity?: string;
+    /** Maximum number of cached RwSite instances. Default: 20. */
+    cacheSize?: number;
+    /**
+     * How often to check cached sites for upstream changes and reload if needed.
+     * If not set, no periodic reloading is performed.
+     *
+     * @example
+     * ```yaml
+     * rw:
+     *   reloadInterval: { minutes: 5 }
+     * ```
+     */
+    reloadInterval?: import("@backstage/types").HumanDuration;
+    /**
+     * S3 storage configuration. Shared across all entity sites.
+     * Mutually exclusive with `projectDir`.
+     */
+    s3?: {
+      /** S3 bucket name. */
+      bucket: string;
+      /** AWS region. */
+      region?: string;
+      /** Custom S3 endpoint URL. */
+      endpoint?: string;
+      /** Root path within the bucket. */
+      bucketRootPath?: string;
+      /** AWS access key ID. */
+      accessKeyId?: string;
+      /**
+       * AWS secret access key.
+       * @visibility secret
+       */
+      secretAccessKey?: string;
+    };
+    /** Diagram rendering configuration. Shared across all sites. */
+    diagrams?: {
+      /** Kroki server URL for rendering diagrams. */
+      krokiUrl?: string;
+      /** Diagram rendering DPI. */
+      dpi?: number;
+    };
+  };
+}

package/dist/config.cjs.js

@@ -0,0 +1,30 @@
+'use strict';
+
+function readRwSiteConfig(config) {
+  const projectDir = config.getOptionalString("rw.projectDir");
+  const entity = config.getOptionalString("rw.entity");
+  const s3Config = config.getOptionalConfig("rw.s3");
+  const s3 = s3Config ? {
+    bucket: s3Config.getString("bucket"),
+    region: s3Config.getOptionalString("region"),
+    endpoint: s3Config.getOptionalString("endpoint"),
+    bucketRootPath: s3Config.getOptionalString("bucketRootPath"),
+    accessKeyId: s3Config.getOptionalString("accessKeyId"),
+    secretAccessKey: s3Config.getOptionalString("secretAccessKey")
+  } : void 0;
+  const diagramsConfig = config.getOptionalConfig("rw.diagrams");
+  const diagrams = diagramsConfig ? {
+    krokiUrl: diagramsConfig.getOptionalString("krokiUrl"),
+    dpi: diagramsConfig.getOptionalNumber("dpi")
+  } : void 0;
+  if (!projectDir && !s3) {
+    throw new Error("Either rw.projectDir or rw.s3 must be configured");
+  }
+  if (projectDir && !entity) {
+    throw new Error("rw.entity is required when rw.projectDir is set");
+  }
+  return { projectDir, entity, s3, diagrams };
+}
+
+exports.readRwSiteConfig = readRwSiteConfig;
+//# sourceMappingURL=config.cjs.js.map

package/dist/config.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.cjs.js","sources":["../src/config.ts"],"sourcesContent":["import type { Config } from \"@backstage/config\";\n\nexport interface S3Config {\n  bucket: string;\n  region?: string;\n  endpoint?: string;\n  bucketRootPath?: string;\n  accessKeyId?: string;\n  secretAccessKey?: string;\n}\n\nexport interface RwDiagramsConfig {\n  krokiUrl?: string;\n  dpi?: number;\n}\n\nexport interface RwSiteConfig {\n  projectDir?: string;\n  entity?: string;\n  s3?: S3Config;\n  diagrams?: RwDiagramsConfig;\n}\n\n/**\n * Reads the shared `rw` site configuration from Backstage config.\n *\n * Validates that either `rw.projectDir` or `rw.s3` is set, and that\n * `rw.entity` is present when `rw.projectDir` is used.\n */\nexport function readRwSiteConfig(config: Config): RwSiteConfig {\n  const projectDir = config.getOptionalString(\"rw.projectDir\");\n  const entity = config.getOptionalString(\"rw.entity\");\n\n  const s3Config = config.getOptionalConfig(\"rw.s3\");\n  const s3 = s3Config\n    ? {\n        bucket: s3Config.getString(\"bucket\"),\n        region: s3Config.getOptionalString(\"region\"),\n        endpoint: s3Config.getOptionalString(\"endpoint\"),\n        bucketRootPath: s3Config.getOptionalString(\"bucketRootPath\"),\n        accessKeyId: s3Config.getOptionalString(\"accessKeyId\"),\n        secretAccessKey: s3Config.getOptionalString(\"secretAccessKey\"),\n      }\n    : undefined;\n\n  const diagramsConfig = config.getOptionalConfig(\"rw.diagrams\");\n  const diagrams = diagramsConfig\n    ? {\n        krokiUrl: diagramsConfig.getOptionalString(\"krokiUrl\"),\n        dpi: diagramsConfig.getOptionalNumber(\"dpi\"),\n      }\n    : undefined;\n\n  if (!projectDir && !s3) {\n    throw new Error(\"Either rw.projectDir or rw.s3 must be configured\");\n  }\n\n  if (projectDir && !entity) {\n    throw new Error(\"rw.entity is required when rw.projectDir is set\");\n  }\n\n  return { projectDir, entity, s3, diagrams };\n}\n"],"names":[],"mappings":";;AA6BO,SAAS,iBAAiB,MAAA,EAA8B;AAC7D,EAAA,MAAM,UAAA,GAAa,MAAA,CAAO,iBAAA,CAAkB,eAAe,CAAA;AAC3D,EAAA,MAAM,MAAA,GAAS,MAAA,CAAO,iBAAA,CAAkB,WAAW,CAAA;AAEnD,EAAA,MAAM,QAAA,GAAW,MAAA,CAAO,iBAAA,CAAkB,OAAO,CAAA;AACjD,EAAA,MAAM,KAAK,QAAA,GACP;AAAA,IACE,MAAA,EAAQ,QAAA,CAAS,SAAA,CAAU,QAAQ,CAAA;AAAA,IACnC,MAAA,EAAQ,QAAA,CAAS,iBAAA,CAAkB,QAAQ,CAAA;AAAA,IAC3C,QAAA,EAAU,QAAA,CAAS,iBAAA,CAAkB,UAAU,CAAA;AAAA,IAC/C,cAAA,EAAgB,QAAA,CAAS,iBAAA,CAAkB,gBAAgB,CAAA;AAAA,IAC3D,WAAA,EAAa,QAAA,CAAS,iBAAA,CAAkB,aAAa,CAAA;AAAA,IACrD,eAAA,EAAiB,QAAA,CAAS,iBAAA,CAAkB,iBAAiB;AAAA,GAC/D,GACA,MAAA;AAEJ,EAAA,MAAM,cAAA,GAAiB,MAAA,CAAO,iBAAA,CAAkB,aAAa,CAAA;AAC7D,EAAA,MAAM,WAAW,cAAA,GACb;AAAA,IACE,QAAA,EAAU,cAAA,CAAe,iBAAA,CAAkB,UAAU,CAAA;AAAA,IACrD,GAAA,EAAK,cAAA,CAAe,iBAAA,CAAkB,KAAK;AAAA,GAC7C,GACA,MAAA;AAEJ,EAAA,IAAI,CAAC,UAAA,IAAc,CAAC,EAAA,EAAI;AACtB,IAAA,MAAM,IAAI,MAAM,kDAAkD,CAAA;AAAA,EACpE;AAEA,EAAA,IAAI,UAAA,IAAc,CAAC,MAAA,EAAQ;AACzB,IAAA,MAAM,IAAI,MAAM,iDAAiD,CAAA;AAAA,EACnE;AAEA,EAAA,OAAO,EAAE,UAAA,EAAY,MAAA,EAAQ,EAAA,EAAI,QAAA,EAAS;AAC5C;;;;"}

package/dist/config.esm.js

@@ -0,0 +1,28 @@
+function readRwSiteConfig(config) {
+  const projectDir = config.getOptionalString("rw.projectDir");
+  const entity = config.getOptionalString("rw.entity");
+  const s3Config = config.getOptionalConfig("rw.s3");
+  const s3 = s3Config ? {
+    bucket: s3Config.getString("bucket"),
+    region: s3Config.getOptionalString("region"),
+    endpoint: s3Config.getOptionalString("endpoint"),
+    bucketRootPath: s3Config.getOptionalString("bucketRootPath"),
+    accessKeyId: s3Config.getOptionalString("accessKeyId"),
+    secretAccessKey: s3Config.getOptionalString("secretAccessKey")
+  } : void 0;
+  const diagramsConfig = config.getOptionalConfig("rw.diagrams");
+  const diagrams = diagramsConfig ? {
+    krokiUrl: diagramsConfig.getOptionalString("krokiUrl"),
+    dpi: diagramsConfig.getOptionalNumber("dpi")
+  } : void 0;
+  if (!projectDir && !s3) {
+    throw new Error("Either rw.projectDir or rw.s3 must be configured");
+  }
+  if (projectDir && !entity) {
+    throw new Error("rw.entity is required when rw.projectDir is set");
+  }
+  return { projectDir, entity, s3, diagrams };
+}
+
+export { readRwSiteConfig };
+//# sourceMappingURL=config.esm.js.map

package/dist/config.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.esm.js","sources":["../src/config.ts"],"sourcesContent":["import type { Config } from \"@backstage/config\";\n\nexport interface S3Config {\n  bucket: string;\n  region?: string;\n  endpoint?: string;\n  bucketRootPath?: string;\n  accessKeyId?: string;\n  secretAccessKey?: string;\n}\n\nexport interface RwDiagramsConfig {\n  krokiUrl?: string;\n  dpi?: number;\n}\n\nexport interface RwSiteConfig {\n  projectDir?: string;\n  entity?: string;\n  s3?: S3Config;\n  diagrams?: RwDiagramsConfig;\n}\n\n/**\n * Reads the shared `rw` site configuration from Backstage config.\n *\n * Validates that either `rw.projectDir` or `rw.s3` is set, and that\n * `rw.entity` is present when `rw.projectDir` is used.\n */\nexport function readRwSiteConfig(config: Config): RwSiteConfig {\n  const projectDir = config.getOptionalString(\"rw.projectDir\");\n  const entity = config.getOptionalString(\"rw.entity\");\n\n  const s3Config = config.getOptionalConfig(\"rw.s3\");\n  const s3 = s3Config\n    ? {\n        bucket: s3Config.getString(\"bucket\"),\n        region: s3Config.getOptionalString(\"region\"),\n        endpoint: s3Config.getOptionalString(\"endpoint\"),\n        bucketRootPath: s3Config.getOptionalString(\"bucketRootPath\"),\n        accessKeyId: s3Config.getOptionalString(\"accessKeyId\"),\n        secretAccessKey: s3Config.getOptionalString(\"secretAccessKey\"),\n      }\n    : undefined;\n\n  const diagramsConfig = config.getOptionalConfig(\"rw.diagrams\");\n  const diagrams = diagramsConfig\n    ? {\n        krokiUrl: diagramsConfig.getOptionalString(\"krokiUrl\"),\n        dpi: diagramsConfig.getOptionalNumber(\"dpi\"),\n      }\n    : undefined;\n\n  if (!projectDir && !s3) {\n    throw new Error(\"Either rw.projectDir or rw.s3 must be configured\");\n  }\n\n  if (projectDir && !entity) {\n    throw new Error(\"rw.entity is required when rw.projectDir is set\");\n  }\n\n  return { projectDir, entity, s3, diagrams };\n}\n"],"names":[],"mappings":"AA6BO,SAAS,iBAAiB,MAAA,EAA8B;AAC7D,EAAA,MAAM,UAAA,GAAa,MAAA,CAAO,iBAAA,CAAkB,eAAe,CAAA;AAC3D,EAAA,MAAM,MAAA,GAAS,MAAA,CAAO,iBAAA,CAAkB,WAAW,CAAA;AAEnD,EAAA,MAAM,QAAA,GAAW,MAAA,CAAO,iBAAA,CAAkB,OAAO,CAAA;AACjD,EAAA,MAAM,KAAK,QAAA,GACP;AAAA,IACE,MAAA,EAAQ,QAAA,CAAS,SAAA,CAAU,QAAQ,CAAA;AAAA,IACnC,MAAA,EAAQ,QAAA,CAAS,iBAAA,CAAkB,QAAQ,CAAA;AAAA,IAC3C,QAAA,EAAU,QAAA,CAAS,iBAAA,CAAkB,UAAU,CAAA;AAAA,IAC/C,cAAA,EAAgB,QAAA,CAAS,iBAAA,CAAkB,gBAAgB,CAAA;AAAA,IAC3D,WAAA,EAAa,QAAA,CAAS,iBAAA,CAAkB,aAAa,CAAA;AAAA,IACrD,eAAA,EAAiB,QAAA,CAAS,iBAAA,CAAkB,iBAAiB;AAAA,GAC/D,GACA,MAAA;AAEJ,EAAA,MAAM,cAAA,GAAiB,MAAA,CAAO,iBAAA,CAAkB,aAAa,CAAA;AAC7D,EAAA,MAAM,WAAW,cAAA,GACb;AAAA,IACE,QAAA,EAAU,cAAA,CAAe,iBAAA,CAAkB,UAAU,CAAA;AAAA,IACrD,GAAA,EAAK,cAAA,CAAe,iBAAA,CAAkB,KAAK;AAAA,GAC7C,GACA,MAAA;AAEJ,EAAA,IAAI,CAAC,UAAA,IAAc,CAAC,EAAA,EAAI;AACtB,IAAA,MAAM,IAAI,MAAM,kDAAkD,CAAA;AAAA,EACpE;AAEA,EAAA,IAAI,UAAA,IAAc,CAAC,MAAA,EAAQ;AACzB,IAAA,MAAM,IAAI,MAAM,iDAAiD,CAAA;AAAA,EACnE;AAEA,EAAA,OAAO,EAAE,UAAA,EAAY,MAAA,EAAQ,EAAA,EAAI,QAAA,EAAS;AAC5C;;;;"}

package/dist/entityPath.cjs.js

@@ -0,0 +1,22 @@
+'use strict';
+
+var catalogModel = require('@backstage/catalog-model');
+var errors = require('@backstage/errors');
+
+function toEntityPath(ref) {
+  const parsed = typeof ref === "string" ? catalogModel.parseEntityRef(ref) : ref;
+  const ns = parsed.namespace ?? "default";
+  return `${ns}/${parsed.kind}/${parsed.name}`.toLocaleLowerCase("en-US");
+}
+function fromEntityPath(path) {
+  const parts = path.split("/");
+  if (parts.length !== 3 || parts.some((p) => !p)) {
+    throw new errors.InputError(`Invalid entity path: "${path}" (expected "namespace/kind/name")`);
+  }
+  const [namespace, kind, name] = parts;
+  return catalogModel.stringifyEntityRef({ kind, namespace, name });
+}
+
+exports.fromEntityPath = fromEntityPath;
+exports.toEntityPath = toEntityPath;
+//# sourceMappingURL=entityPath.cjs.js.map

package/dist/entityPath.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityPath.cjs.js","sources":["../src/entityPath.ts"],"sourcesContent":["import { parseEntityRef, stringifyEntityRef } from \"@backstage/catalog-model\";\nimport { InputError } from \"@backstage/errors\";\n\n/**\n * Converts an entity ref (e.g. \"component:default/arch\") or a compound ref\n * object to the slash-delimited, lowercased path used in API URLs\n * (e.g. \"default/component/arch\").\n *\n * Uses namespace/kind/name ordering to match Backstage catalog URL convention.\n */\nexport function toEntityPath(\n  ref: string | { kind: string; namespace?: string; name: string },\n): string {\n  const parsed = typeof ref === \"string\" ? parseEntityRef(ref) : ref;\n  const ns = parsed.namespace ?? \"default\";\n  return `${ns}/${parsed.kind}/${parsed.name}`.toLocaleLowerCase(\"en-US\");\n}\n\n/**\n * Converts a slash-delimited entity path (e.g. \"default/component/arch\")\n * back to the standard Backstage entity ref format (e.g. \"component:default/arch\").\n *\n * This is the inverse of `toEntityPath`. Note that the round-trip always\n * produces lowercased refs since `toEntityPath` lowercases its output.\n */\nexport function fromEntityPath(path: string): string {\n  const parts = path.split(\"/\");\n  if (parts.length !== 3 || parts.some((p) => !p)) {\n    throw new InputError(`Invalid entity path: \"${path}\" (expected \"namespace/kind/name\")`);\n  }\n  const [namespace, kind, name] = parts;\n  return stringifyEntityRef({ kind, namespace, name });\n}\n"],"names":["parseEntityRef","InputError","stringifyEntityRef"],"mappings":";;;;;AAUO,SAAS,aACd,GAAA,EACQ;AACR,EAAA,MAAM,SAAS,OAAO,GAAA,KAAQ,QAAA,GAAWA,2BAAA,CAAe,GAAG,CAAA,GAAI,GAAA;AAC/D,EAAA,MAAM,EAAA,GAAK,OAAO,SAAA,IAAa,SAAA;AAC/B,EAAA,OAAO,CAAA,EAAG,EAAE,CAAA,CAAA,EAAI,MAAA,CAAO,IAAI,IAAI,MAAA,CAAO,IAAI,CAAA,CAAA,CAAG,iBAAA,CAAkB,OAAO,CAAA;AACxE;AASO,SAAS,eAAe,IAAA,EAAsB;AACnD,EAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA;AAC5B,EAAA,IAAI,KAAA,CAAM,WAAW,CAAA,IAAK,KAAA,CAAM,KAAK,CAAC,CAAA,KAAM,CAAC,CAAC,CAAA,EAAG;AAC/C,IAAA,MAAM,IAAIC,iBAAA,CAAW,CAAA,sBAAA,EAAyB,IAAI,CAAA,kCAAA,CAAoC,CAAA;AAAA,EACxF;AACA,EAAA,MAAM,CAAC,SAAA,EAAW,IAAA,EAAM,IAAI,CAAA,GAAI,KAAA;AAChC,EAAA,OAAOC,+BAAA,CAAmB,EAAE,IAAA,EAAM,SAAA,EAAW,MAAM,CAAA;AACrD;;;;;"}

package/dist/entityPath.esm.js

@@ -0,0 +1,19 @@
+import { parseEntityRef, stringifyEntityRef } from '@backstage/catalog-model';
+import { InputError } from '@backstage/errors';
+
+function toEntityPath(ref) {
+  const parsed = typeof ref === "string" ? parseEntityRef(ref) : ref;
+  const ns = parsed.namespace ?? "default";
+  return `${ns}/${parsed.kind}/${parsed.name}`.toLocaleLowerCase("en-US");
+}
+function fromEntityPath(path) {
+  const parts = path.split("/");
+  if (parts.length !== 3 || parts.some((p) => !p)) {
+    throw new InputError(`Invalid entity path: "${path}" (expected "namespace/kind/name")`);
+  }
+  const [namespace, kind, name] = parts;
+  return stringifyEntityRef({ kind, namespace, name });
+}
+
+export { fromEntityPath, toEntityPath };
+//# sourceMappingURL=entityPath.esm.js.map

package/dist/entityPath.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityPath.esm.js","sources":["../src/entityPath.ts"],"sourcesContent":["import { parseEntityRef, stringifyEntityRef } from \"@backstage/catalog-model\";\nimport { InputError } from \"@backstage/errors\";\n\n/**\n * Converts an entity ref (e.g. \"component:default/arch\") or a compound ref\n * object to the slash-delimited, lowercased path used in API URLs\n * (e.g. \"default/component/arch\").\n *\n * Uses namespace/kind/name ordering to match Backstage catalog URL convention.\n */\nexport function toEntityPath(\n  ref: string | { kind: string; namespace?: string; name: string },\n): string {\n  const parsed = typeof ref === \"string\" ? parseEntityRef(ref) : ref;\n  const ns = parsed.namespace ?? \"default\";\n  return `${ns}/${parsed.kind}/${parsed.name}`.toLocaleLowerCase(\"en-US\");\n}\n\n/**\n * Converts a slash-delimited entity path (e.g. \"default/component/arch\")\n * back to the standard Backstage entity ref format (e.g. \"component:default/arch\").\n *\n * This is the inverse of `toEntityPath`. Note that the round-trip always\n * produces lowercased refs since `toEntityPath` lowercases its output.\n */\nexport function fromEntityPath(path: string): string {\n  const parts = path.split(\"/\");\n  if (parts.length !== 3 || parts.some((p) => !p)) {\n    throw new InputError(`Invalid entity path: \"${path}\" (expected \"namespace/kind/name\")`);\n  }\n  const [namespace, kind, name] = parts;\n  return stringifyEntityRef({ kind, namespace, name });\n}\n"],"names":[],"mappings":";;;AAUO,SAAS,aACd,GAAA,EACQ;AACR,EAAA,MAAM,SAAS,OAAO,GAAA,KAAQ,QAAA,GAAW,cAAA,CAAe,GAAG,CAAA,GAAI,GAAA;AAC/D,EAAA,MAAM,EAAA,GAAK,OAAO,SAAA,IAAa,SAAA;AAC/B,EAAA,OAAO,CAAA,EAAG,EAAE,CAAA,CAAA,EAAI,MAAA,CAAO,IAAI,IAAI,MAAA,CAAO,IAAI,CAAA,CAAA,CAAG,iBAAA,CAAkB,OAAO,CAAA;AACxE;AASO,SAAS,eAAe,IAAA,EAAsB;AACnD,EAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA;AAC5B,EAAA,IAAI,KAAA,CAAM,WAAW,CAAA,IAAK,KAAA,CAAM,KAAK,CAAC,CAAA,KAAM,CAAC,CAAC,CAAA,EAAG;AAC/C,IAAA,MAAM,IAAI,UAAA,CAAW,CAAA,sBAAA,EAAyB,IAAI,CAAA,kCAAA,CAAoC,CAAA;AAAA,EACxF;AACA,EAAA,MAAM,CAAC,SAAA,EAAW,IAAA,EAAM,IAAI,CAAA,GAAI,KAAA;AAChC,EAAA,OAAO,kBAAA,CAAmB,EAAE,IAAA,EAAM,SAAA,EAAW,MAAM,CAAA;AACrD;;;;"}

package/dist/index.cjs.js

@@ -0,0 +1,13 @@
+'use strict';
+
+var entityPath = require('./entityPath.cjs.js');
+var parseAnnotation = require('./parseAnnotation.cjs.js');
+var config = require('./config.cjs.js');
+
+
+
+exports.fromEntityPath = entityPath.fromEntityPath;
+exports.toEntityPath = entityPath.toEntityPath;
+exports.parseAnnotation = parseAnnotation.parseAnnotation;
+exports.readRwSiteConfig = config.readRwSiteConfig;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { Config } from '@backstage/config';
+
+/**
+ * Converts an entity ref (e.g. "component:default/arch") or a compound ref
+ * object to the slash-delimited, lowercased path used in API URLs
+ * (e.g. "default/component/arch").
+ *
+ * Uses namespace/kind/name ordering to match Backstage catalog URL convention.
+ */
+declare function toEntityPath(ref: string | {
+    kind: string;
+    namespace?: string;
+    name: string;
+}): string;
+/**
+ * Converts a slash-delimited entity path (e.g. "default/component/arch")
+ * back to the standard Backstage entity ref format (e.g. "component:default/arch").
+ *
+ * This is the inverse of `toEntityPath`. Note that the round-trip always
+ * produces lowercased refs since `toEntityPath` lowercases its output.
+ */
+declare function fromEntityPath(path: string): string;
+
+interface ParsedAnnotation {
+    /** Slash-delimited path for API URLs (e.g. "default/component/arch"). */
+    entityPath: string;
+    /** Standard Backstage entity ref (e.g. "component:default/arch"). */
+    entityRef: string;
+    sectionRef: string | undefined;
+}
+/**
+ * Parses an `rwdocs.org/ref` annotation value into its component parts.
+ *
+ * The annotation format is `<entityRef>[#<sectionRef>]`, where `entityRef` is
+ * a standard Backstage entity ref and `sectionRef` is an optional path within
+ * the documentation site.
+ *
+ * A special value of `"."` refers to the entity itself; this requires the
+ * `selfEntityPath` parameter to resolve.
+ *
+ * @param value - The raw annotation value
+ * @param selfEntityPath - The entity path of the entity bearing the annotation,
+ *   required to resolve `"."` self-references
+ */
+declare function parseAnnotation(value: string | undefined, selfEntityPath?: string): ParsedAnnotation | undefined;
+
+interface S3Config {
+    bucket: string;
+    region?: string;
+    endpoint?: string;
+    bucketRootPath?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+}
+interface RwDiagramsConfig {
+    krokiUrl?: string;
+    dpi?: number;
+}
+interface RwSiteConfig {
+    projectDir?: string;
+    entity?: string;
+    s3?: S3Config;
+    diagrams?: RwDiagramsConfig;
+}
+/**
+ * Reads the shared `rw` site configuration from Backstage config.
+ *
+ * Validates that either `rw.projectDir` or `rw.s3` is set, and that
+ * `rw.entity` is present when `rw.projectDir` is used.
+ */
+declare function readRwSiteConfig(config: Config): RwSiteConfig;
+
+export { fromEntityPath, parseAnnotation, readRwSiteConfig, toEntityPath };
+export type { ParsedAnnotation, RwDiagramsConfig, RwSiteConfig, S3Config };

package/dist/index.esm.js

@@ -0,0 +1,4 @@
+export { fromEntityPath, toEntityPath } from './entityPath.esm.js';
+export { parseAnnotation } from './parseAnnotation.esm.js';
+export { readRwSiteConfig } from './config.esm.js';
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/parseAnnotation.cjs.js

@@ -0,0 +1,34 @@
+'use strict';
+
+var catalogModel = require('@backstage/catalog-model');
+var entityPath = require('./entityPath.cjs.js');
+
+function parseAnnotation(value, selfEntityPath) {
+  if (!value) return void 0;
+  const hashIndex = value.indexOf("#");
+  let entity;
+  let sectionRef;
+  if (hashIndex === -1) {
+    entity = value;
+    sectionRef = void 0;
+  } else {
+    entity = value.slice(0, hashIndex);
+    sectionRef = value.slice(hashIndex + 1) || void 0;
+  }
+  if (entity === ".") {
+    if (!selfEntityPath) return void 0;
+    return { entityPath: selfEntityPath, entityRef: entityPath.fromEntityPath(selfEntityPath), sectionRef };
+  }
+  try {
+    return {
+      entityPath: entityPath.toEntityPath(entity),
+      entityRef: catalogModel.stringifyEntityRef(catalogModel.parseEntityRef(entity)),
+      sectionRef
+    };
+  } catch {
+    return void 0;
+  }
+}
+
+exports.parseAnnotation = parseAnnotation;
+//# sourceMappingURL=parseAnnotation.cjs.js.map

package/dist/parseAnnotation.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseAnnotation.cjs.js","sources":["../src/parseAnnotation.ts"],"sourcesContent":["import { parseEntityRef, stringifyEntityRef } from \"@backstage/catalog-model\";\nimport { toEntityPath, fromEntityPath } from \"./entityPath\";\n\nexport interface ParsedAnnotation {\n  /** Slash-delimited path for API URLs (e.g. \"default/component/arch\"). */\n  entityPath: string;\n  /** Standard Backstage entity ref (e.g. \"component:default/arch\"). */\n  entityRef: string;\n  sectionRef: string | undefined;\n}\n\n/**\n * Parses an `rwdocs.org/ref` annotation value into its component parts.\n *\n * The annotation format is `<entityRef>[#<sectionRef>]`, where `entityRef` is\n * a standard Backstage entity ref and `sectionRef` is an optional path within\n * the documentation site.\n *\n * A special value of `\".\"` refers to the entity itself; this requires the\n * `selfEntityPath` parameter to resolve.\n *\n * @param value - The raw annotation value\n * @param selfEntityPath - The entity path of the entity bearing the annotation,\n *   required to resolve `\".\"` self-references\n */\nexport function parseAnnotation(\n  value: string | undefined,\n  selfEntityPath?: string,\n): ParsedAnnotation | undefined {\n  if (!value) return undefined;\n\n  const hashIndex = value.indexOf(\"#\");\n  let entity: string;\n  let sectionRef: string | undefined;\n\n  if (hashIndex === -1) {\n    entity = value;\n    sectionRef = undefined;\n  } else {\n    entity = value.slice(0, hashIndex);\n    sectionRef = value.slice(hashIndex + 1) || undefined;\n  }\n\n  if (entity === \".\") {\n    if (!selfEntityPath) return undefined;\n    return { entityPath: selfEntityPath, entityRef: fromEntityPath(selfEntityPath), sectionRef };\n  }\n\n  try {\n    return {\n      entityPath: toEntityPath(entity),\n      entityRef: stringifyEntityRef(parseEntityRef(entity)),\n      sectionRef,\n    };\n  } catch {\n    return undefined;\n  }\n}\n"],"names":["fromEntityPath","toEntityPath","stringifyEntityRef","parseEntityRef"],"mappings":";;;;;AAyBO,SAAS,eAAA,CACd,OACA,cAAA,EAC8B;AAC9B,EAAA,IAAI,CAAC,OAAO,OAAO,MAAA;AAEnB,EAAA,MAAM,SAAA,GAAY,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA;AACnC,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI,UAAA;AAEJ,EAAA,IAAI,cAAc,EAAA,EAAI;AACpB,IAAA,MAAA,GAAS,KAAA;AACT,IAAA,UAAA,GAAa,MAAA;AAAA,EACf,CAAA,MAAO;AACL,IAAA,MAAA,GAAS,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA;AACjC,IAAA,UAAA,GAAa,KAAA,CAAM,KAAA,CAAM,SAAA,GAAY,CAAC,CAAA,IAAK,MAAA;AAAA,EAC7C;AAEA,EAAA,IAAI,WAAW,GAAA,EAAK;AAClB,IAAA,IAAI,CAAC,gBAAgB,OAAO,MAAA;AAC5B,IAAA,OAAO,EAAE,UAAA,EAAY,cAAA,EAAgB,WAAWA,yBAAA,CAAe,cAAc,GAAG,UAAA,EAAW;AAAA,EAC7F;AAEA,EAAA,IAAI;AACF,IAAA,OAAO;AAAA,MACL,UAAA,EAAYC,wBAAa,MAAM,CAAA;AAAA,MAC/B,SAAA,EAAWC,+BAAA,CAAmBC,2BAAA,CAAe,MAAM,CAAC,CAAA;AAAA,MACpD;AAAA,KACF;AAAA,EACF,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,MAAA;AAAA,EACT;AACF;;;;"}

package/dist/parseAnnotation.esm.js

@@ -0,0 +1,32 @@
+import { stringifyEntityRef, parseEntityRef } from '@backstage/catalog-model';
+import { fromEntityPath, toEntityPath } from './entityPath.esm.js';
+
+function parseAnnotation(value, selfEntityPath) {
+  if (!value) return void 0;
+  const hashIndex = value.indexOf("#");
+  let entity;
+  let sectionRef;
+  if (hashIndex === -1) {
+    entity = value;
+    sectionRef = void 0;
+  } else {
+    entity = value.slice(0, hashIndex);
+    sectionRef = value.slice(hashIndex + 1) || void 0;
+  }
+  if (entity === ".") {
+    if (!selfEntityPath) return void 0;
+    return { entityPath: selfEntityPath, entityRef: fromEntityPath(selfEntityPath), sectionRef };
+  }
+  try {
+    return {
+      entityPath: toEntityPath(entity),
+      entityRef: stringifyEntityRef(parseEntityRef(entity)),
+      sectionRef
+    };
+  } catch {
+    return void 0;
+  }
+}
+
+export { parseAnnotation };
+//# sourceMappingURL=parseAnnotation.esm.js.map

package/dist/parseAnnotation.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseAnnotation.esm.js","sources":["../src/parseAnnotation.ts"],"sourcesContent":["import { parseEntityRef, stringifyEntityRef } from \"@backstage/catalog-model\";\nimport { toEntityPath, fromEntityPath } from \"./entityPath\";\n\nexport interface ParsedAnnotation {\n  /** Slash-delimited path for API URLs (e.g. \"default/component/arch\"). */\n  entityPath: string;\n  /** Standard Backstage entity ref (e.g. \"component:default/arch\"). */\n  entityRef: string;\n  sectionRef: string | undefined;\n}\n\n/**\n * Parses an `rwdocs.org/ref` annotation value into its component parts.\n *\n * The annotation format is `<entityRef>[#<sectionRef>]`, where `entityRef` is\n * a standard Backstage entity ref and `sectionRef` is an optional path within\n * the documentation site.\n *\n * A special value of `\".\"` refers to the entity itself; this requires the\n * `selfEntityPath` parameter to resolve.\n *\n * @param value - The raw annotation value\n * @param selfEntityPath - The entity path of the entity bearing the annotation,\n *   required to resolve `\".\"` self-references\n */\nexport function parseAnnotation(\n  value: string | undefined,\n  selfEntityPath?: string,\n): ParsedAnnotation | undefined {\n  if (!value) return undefined;\n\n  const hashIndex = value.indexOf(\"#\");\n  let entity: string;\n  let sectionRef: string | undefined;\n\n  if (hashIndex === -1) {\n    entity = value;\n    sectionRef = undefined;\n  } else {\n    entity = value.slice(0, hashIndex);\n    sectionRef = value.slice(hashIndex + 1) || undefined;\n  }\n\n  if (entity === \".\") {\n    if (!selfEntityPath) return undefined;\n    return { entityPath: selfEntityPath, entityRef: fromEntityPath(selfEntityPath), sectionRef };\n  }\n\n  try {\n    return {\n      entityPath: toEntityPath(entity),\n      entityRef: stringifyEntityRef(parseEntityRef(entity)),\n      sectionRef,\n    };\n  } catch {\n    return undefined;\n  }\n}\n"],"names":[],"mappings":";;;AAyBO,SAAS,eAAA,CACd,OACA,cAAA,EAC8B;AAC9B,EAAA,IAAI,CAAC,OAAO,OAAO,MAAA;AAEnB,EAAA,MAAM,SAAA,GAAY,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA;AACnC,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI,UAAA;AAEJ,EAAA,IAAI,cAAc,EAAA,EAAI;AACpB,IAAA,MAAA,GAAS,KAAA;AACT,IAAA,UAAA,GAAa,MAAA;AAAA,EACf,CAAA,MAAO;AACL,IAAA,MAAA,GAAS,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA;AACjC,IAAA,UAAA,GAAa,KAAA,CAAM,KAAA,CAAM,SAAA,GAAY,CAAC,CAAA,IAAK,MAAA;AAAA,EAC7C;AAEA,EAAA,IAAI,WAAW,GAAA,EAAK;AAClB,IAAA,IAAI,CAAC,gBAAgB,OAAO,MAAA;AAC5B,IAAA,OAAO,EAAE,UAAA,EAAY,cAAA,EAAgB,WAAW,cAAA,CAAe,cAAc,GAAG,UAAA,EAAW;AAAA,EAC7F;AAEA,EAAA,IAAI;AACF,IAAA,OAAO;AAAA,MACL,UAAA,EAAY,aAAa,MAAM,CAAA;AAAA,MAC/B,SAAA,EAAW,kBAAA,CAAmB,cAAA,CAAe,MAAM,CAAC,CAAA;AAAA,MACpD;AAAA,KACF;AAAA,EACF,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,MAAA;AAAA,EACT;AACF;;;;"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@rwdocs/backstage-plugin-rw-common",
+  "version": "0.1.4",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rwdocs/backstage-plugins.git",
+    "directory": "plugins/rw-common"
+  },
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "common-library",
+    "pluginId": "rw",
+    "pluginPackages": [
+      "@rwdocs/backstage-plugin-rw",
+      "@rwdocs/backstage-plugin-rw-backend",
+      "@rwdocs/backstage-plugin-rw-common"
+    ]
+  },
+  "configSchema": "config.d.ts",
+  "files": [
+    "dist",
+    "config.d.ts",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/catalog-model": "^1.7.6",
+    "@backstage/config": "^1.3.6",
+    "@backstage/errors": "^1.2.7",
+    "@backstage/types": "^1.2.2"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.36.0",
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.0"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
+  "module": "dist/index.esm.js"
+}