@kirchdev/duxt 0.2.0 → 0.3.0

package/app/types/duxt.d.ts

@@ -143,6 +143,16 @@ declare global {
     | 'deprecated'
     | 'eol';
 
+  /** Lifecycle defaults a source may opt into for its different ref kinds. */
+  type DuxtSourceStatusDefaultsInput = {
+    /** The moving `latest` shorthand. */
+    latest?: DuxtSourceStatusInput;
+    /** An explicitly listed tag. */
+    tag?: DuxtSourceStatusInput;
+    /** A named branch, such as `main`. */
+    branch?: DuxtSourceStatusInput;
+  };
+
   /**
    * A branch by name, or a tag stated as one.
    *
@@ -154,12 +164,16 @@ declare global {
     | {
         branch: string;
         label?: string;
+        /** Serve this ref without a version prefix. */
+        default?: boolean;
         status?: DuxtSourceStatusInput;
         locales?: DuxtSourceLocaleInput[];
       }
     | {
         tag: string;
         label?: string;
+        /** Serve this ref without a version prefix. */
+        default?: boolean;
         status?: DuxtSourceStatusInput;
         locales?: DuxtSourceLocaleInput[];
       };
@@ -215,8 +229,8 @@ declare global {
      *
      * Named here, everything else follows the ref path exactly: the URL segment,
      * the switcher entry (scoped to the same artefact), the banner and the
-     * canonical. `sourceOptions.defaultRef` names which of them is served without
-     * a prefix, whether it is a ref or one of these.
+     * canonical. A ref may name itself as the default; otherwise
+     * `sourceOptions.defaultRef` names which is served without a prefix.
      *
      * Never beside `refs` — a source with both would have to be served at two
      * prefixes at once, and the resolver says so rather than picking one.
@@ -234,6 +248,8 @@ declare global {
     slug?: string;
     /** Lifecycle of every version this entry publishes, unless a ref says otherwise. */
     status?: DuxtSourceStatusInput;
+    /** Lifecycle defaults by ref kind; an explicit ref status wins. */
+    statusDefaults?: DuxtSourceStatusDefaultsInput;
     /**
      * The repository a source read off disk lives in, for links back to it.
      * Not `repo`, which is what makes Content download a source.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@kirchdev/duxt",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Nuxt documentation layer on Content v3 — multi-repo, versioned docs from one compact source list.",
   "keywords": [
     "content-v3",

package/sources-git.ts

@@ -4,6 +4,8 @@ import {
   expandSources,
   isLatestRef,
   newestTag,
+  refIsTag,
+  refName,
   repoUrl
 } from './sources-resolve';
 
@@ -102,19 +104,33 @@ export function resolveLatestRefs(sources: DuxtSource[]): DuxtSource[] {
 
     return {
       ...source,
-      refs: source.refs.map((ref) =>
-        isLatestRef(ref)
-          ? {
-              tag: newest,
-              // The URL keeps saying `latest`, so a bookmark survives the next
-              // release; only the ref underneath moves. `label` is what the
-              // switcher and the prefix are built from.
-              label:
-                typeof ref === 'object' ? (ref.label ?? 'latest') : 'latest',
-              status: typeof ref === 'object' ? ref.status : undefined
-            }
-          : ref
-      )
+      refs: source.refs.flatMap((ref) => {
+        if (isLatestRef(ref)) {
+          return {
+            tag: newest,
+            // The URL keeps saying `latest`, so a bookmark survives the next
+            // release; only the ref underneath moves. `label` is what the
+            // switcher and the prefix are built from.
+            label: typeof ref === 'object' ? (ref.label ?? 'latest') : 'latest',
+            // `latest` stops being distinguishable from an ordinary tag after
+            // resolution, so settle its source-level default while that fact
+            // still exists. An explicit ref or all-refs source status wins.
+            status:
+              (typeof ref === 'object' ? ref.status : undefined) ??
+              source.status ??
+              source.statusDefaults?.latest,
+            locales: typeof ref === 'object' ? ref.locales : undefined,
+            default: typeof ref === 'object' ? ref.default : undefined
+          };
+        }
+
+        // Keep an older release ready in the declaration, without serving the
+        // current release twice. Once a newer tag exists this condition stops
+        // matching and the retained release becomes its own edition.
+        if (refIsTag(ref) && refName(ref) === newest) return [];
+
+        return ref;
+      })
     };
   });
 }

package/sources-resolve.ts

@@ -55,8 +55,8 @@ export interface DuxtSource {
    *
    * Named here, everything else follows the ref path exactly: the URL segment,
    * the switcher entry (scoped to the same artefact), the banner and the
-   * canonical. `sourceOptions.defaultRef` names which of them is served without
-   * a prefix, whether it is a ref or one of these.
+   * canonical. A ref may name itself as the default; otherwise
+   * `sourceOptions.defaultRef` names which is served without a prefix.
    *
    * Never beside `refs` — a source with both would have to be served at two
    * prefixes at once, and the resolver says so rather than picking one.
@@ -80,6 +80,12 @@ export interface DuxtSource {
    * otherwise. See `DuxtSourceStatus`.
    */
   status?: DuxtSourceStatus;
+  /**
+   * Lifecycle defaults by ref kind. An explicit ref `status` wins; `status`
+   * above remains the legacy all-refs fallback. A source opts in because only
+   * its maintainer knows whether an older release is really deprecated.
+   */
+  statusDefaults?: DuxtSourceStatusDefaults;
   /**
    * The repository these pages live in, for a source read off disk.
    *
@@ -134,6 +140,16 @@ export type DuxtSourceStatus =
   | 'deprecated'
   | 'eol';
 
+/** Lifecycle defaults a source may opt into for its different ref kinds. */
+export interface DuxtSourceStatusDefaults {
+  /** The moving `latest` shorthand, before it becomes a concrete tag. */
+  latest?: DuxtSourceStatus;
+  /** A tag explicitly listed beside `latest`. */
+  tag?: DuxtSourceStatus;
+  /** A named branch, such as `main` or a preview branch. */
+  branch?: DuxtSourceStatus;
+}
+
 /** A branch by name, or a tag stated as one. */
 export type DuxtRef =
   | string
@@ -143,6 +159,13 @@ export type DuxtRef =
 interface DuxtRefOptions {
   /** Shown in the switcher and used in the URL; defaults to the ref name. */
   label?: string;
+  /**
+   * Serve this ref without a version prefix, even when another source has its
+   * own default. A site with several independently versioned trees needs this:
+   * its docs can serve the newest release at `/` while an API stays at its own
+   * current edition.
+   */
+  default?: boolean;
   /** This one version's lifecycle, overriding the source's. */
   status?: DuxtSourceStatus;
   /**
@@ -577,7 +600,10 @@ export function resolveSources(
     const code = locale ? localeCode(locale) : defaultLocale;
     const isDefaultLocale = !code || code === defaultLocale;
     const version = name ? slugify(label ?? name) : undefined;
-    const isDefault = !name || name === defaultRef;
+    const isDefault =
+      !name ||
+      (ref && typeof ref === 'object' && Boolean(ref.default)) ||
+      name === defaultRef;
 
     const segments: string[] = [];
     if (segmented(source)) segments.push(repoSlug(source));
@@ -639,6 +665,11 @@ export function resolveSources(
       status:
         (ref && typeof ref === 'object' ? ref.status : undefined) ??
         source.status ??
+        (effectiveRef
+          ? refIsTag(effectiveRef)
+            ? source.statusDefaults?.tag
+            : source.statusDefaults?.branch
+          : undefined) ??
         'current',
       // A local source is a full checkout already; a remote one has to be
       // unshallowed, which is why it has to be asked for.