@kirchdev/duxt 0.3.4 → 0.3.5-dev-main.43-3310f4b

package/sections-changelog.ts

@@ -18,15 +18,29 @@
  * the one page it was written as, for a project that just wants it shown. The
  * cost of two rendering paths was weighed and accepted, and the difference runs
  * further than the page count: a flat changelog is an ORDINARY docs page and
- * keeps the docs chrome, which is why `layout` is answered per declaration.
+ * keeps the docs shell, which is why `layout` is answered per declaration.
  *
- * Pure text in, files out. What the split history LOOKS like — the timeline,
+ * Text in, files out — plus ONE FACT THE FILE DOES NOT HOLD. A release is a
+ * range of commits, and who wrote them is in the repository rather than in the
+ * changelog; the authors of the changelog FILE are whoever ran the release
+ * tool, which is not the same set of people and is the wrong answer given
+ * confidently. So where an input names a checkout the build may read
+ * (`DuxtSectionInput.root`) the people behind each tag are read out of git;
+ * where it does not — a remote clone, a test, a fixture — nothing is read and
+ * no release names anybody. What the split history LOOKS like — the timeline,
  * the group badges, the filters — belongs to `layouts/changelog.vue` and the
  * two components this file writes calls to.
  */
 import { stringify as stringifyYaml } from 'yaml';
+import { frontmatterBlock } from './frontmatter';
+import type { DuxtContributor } from './git-contributors';
+import {
+  contributorsForVersion,
+  releaseContributors
+} from './git-contributors';
 import type {
   DuxtSectionContext,
+  DuxtSectionInput,
   DuxtSectionOptions,
   DuxtSectionPage,
   DuxtSectionType
@@ -39,7 +53,7 @@ import { slugify } from './sources-resolve';
  * A layout and two MDC components, because that is the whole of what a
  * consumer can override: dropping a `ChangelogGroup.vue` of their own into
  * `app/components/content/` replaces the layer's, exactly as it does for a
- * callout, and a `layouts/changelog.vue` replaces the chrome around it.
+ * callout, and a `layouts/changelog.vue` replaces the shell around it.
  */
 export const DUXT_CHANGELOG_LAYOUT = 'changelog';
 export const DUXT_CHANGELOG_RELEASES = 'changelog-releases';
@@ -119,14 +133,22 @@ interface Group {
 export const changelogSectionType: DuxtSectionType = {
   parse: parseChangelog,
   /**
-   * ONE GLOBAL HISTORY, read from the default version.
+   * PER VERSION, like the documentation and the API reference beside it.
    *
-   * A changelog is not a per-version document that happens to mention other
-   * versions — it is the list OF the versions, and building one copy per
-   * version would publish the same file under three URLs, each of them missing
-   * the releases that came after it.
+   * Every documentation version publishes the CHANGELOG.md it shipped with, at
+   * a route inside that version — `/v2.x/releases` beside `/v2.x/guides`. It
+   * used to be one global history at a version-neutral URL, and that is what
+   * made the switcher special: it could not keep a reader in the changelog
+   * when they chose another version. Each copy holds everything its own file
+   * holds, earlier releases included, which is exactly what that version knew.
    */
-  versioning: 'global',
+  versioning: 'per-version',
+  /**
+   * REQUIRED in every published version. A version with no CHANGELOG.md is a
+   * build error: leaving the version out, or falling back to another version's
+   * history, would both publish something the version never shipped.
+   */
+  artefact: 'required',
   /**
    * The original, in every language.
    *
@@ -141,7 +163,7 @@ export const changelogSectionType: DuxtSectionType = {
    *
    * The split history is a timeline: the releases in the sidebar, a page per
    * release, no table of contents over four bullet points. The flat file is a
-   * long ordinary page, and the docs chrome is exactly what it wants — a
+   * long ordinary page, and the docs shell is exactly what it wants — a
    * contents column listing the releases most of all. Same type, two products,
    * so the question is answered from the declaration's own options.
    */
@@ -188,10 +210,10 @@ function granularityOf(options: DuxtSectionOptions): Granularity {
 }
 
 function parseChangelog(
-  artefact: string,
+  input: DuxtSectionInput,
   context: DuxtSectionContext
 ): DuxtSectionPage[] {
-  const lines = artefact.split(/\r?\n/);
+  const lines = input.text().split(/\r?\n/);
   const headings = headingsOf(lines);
   const starts = headings.filter((heading) => release(heading.text));
 
@@ -222,7 +244,15 @@ function parseChangelog(
   const width = String(releases.length).length;
 
   return [
-    index(preamble, releases, context),
+    // Read once for the whole file, not once per release: the answer is a map
+    // over every tag the checkout has, and asking git per release would be one
+    // process per release for the same bytes.
+    index(
+      preamble,
+      releases,
+      context,
+      input.root ? releaseContributors(input.root) : undefined
+    ),
     ...releases.map((entry, position) =>
       page(entry, String(position + 1).padStart(width, '0'))
     )
@@ -246,7 +276,7 @@ function flat(
   return {
     file: 'index.md',
     body: [
-      frontmatter({ title: context.label, release: newest }),
+      frontmatterBlock({ title: context.label, release: newest }),
       '',
       ...trim(withoutTitle(lines)),
       ''
@@ -424,20 +454,40 @@ function entries(lines: string[]): number {
 function index(
   preamble: string[],
   releases: Release[],
-  context: DuxtSectionContext
+  context: DuxtSectionContext,
+  contributors?: Map<string, DuxtContributor[]>
 ): DuxtSectionPage {
   const body = trim(withoutTitle(preamble));
 
   const props = {
-    releases: releases.map((entry) => ({
-      version: entry.version,
-      date: entry.date,
-      to: `${context.prefix}/${segment(entry.version)}`,
-      groups: groupsOf(trim(entry.body)).groups.map((group) => ({
-        name: group.name,
-        count: group.count
-      }))
-    }))
+    releases: releases.map((entry) => {
+      const people = contributorsForVersion(contributors, entry.version);
+
+      return {
+        version: entry.version,
+        date: entry.date,
+        to: `${context.prefix}/${segment(entry.version)}`,
+        groups: groupsOf(trim(entry.body)).groups.map((group) => ({
+          name: group.name,
+          count: group.count
+        })),
+        // A NAME AND, WHERE GIT CARRIES ONE, A HANDLE. Not the address the
+        // identity was computed from: these props are written into a page that
+        // is prerendered, crawled, indexed, put into `llms-full.txt` and handed
+        // to a model on request, and an email that reaches all of that is a
+        // different object from the same email inside a commit. Not the commit
+        // COUNT either — the order already carries it, and a per-release tally
+        // is a number nobody asked this page for.
+        ...(people?.length
+          ? {
+              contributors: people.map((person) => ({
+                name: person.name,
+                ...(person.username ? { username: person.username } : {})
+              }))
+            }
+          : {})
+      };
+    })
   };
 
   return {
@@ -447,7 +497,7 @@ function index(
       // props below. Keep the newest release beside the page title instead:
       // Content exposes frontmatter on the page query that `DuxtVersion` uses,
       // and parsing the file again there would make the two answers drift.
-      frontmatter({ title: context.label, release: releases[0]?.version }),
+      frontmatterBlock({ title: context.label, release: releases[0]?.version }),
       '',
       // NO `<h1>` OF ITS OWN. The page draws the docs header — breadcrumb,
       // title, description, the copy control beside it — for exactly the
@@ -479,7 +529,7 @@ function page(entry: Release, order: string): DuxtSectionPage {
   return {
     file: `${order}.${segment(entry.version)}.md`,
     body: [
-      frontmatter({
+      frontmatterBlock({
         title: entry.version,
         date: entry.date,
         compare: entry.compare
@@ -635,20 +685,3 @@ function component(
     fence
   ].join('\n');
 }
-
-/**
- * A frontmatter block YAML can read back.
- *
- * Every value is written as a JSON string, which is also a YAML double-quoted
- * scalar — so a release title carrying a colon cannot end the mapping early,
- * which is the exact failure `tests/frontmatter-yaml.test.ts` exists over.
- */
-function frontmatter(fields: Record<string, string | undefined>): string {
-  return [
-    '---',
-    ...Object.entries(fields)
-      .filter(([, value]) => value !== undefined)
-      .map(([key, value]) => `${key}: ${JSON.stringify(value)}`),
-    '---'
-  ].join('\n');
-}

package/sections-openapi.ts

@@ -4,7 +4,7 @@
  * The second type in the registry, and the first one that answers the questions
  * the registry was built to ask. A changelog is one global history in the
  * language it was written in; a reference is **per version** and **per locale**,
- * and it needs a **layout** the docs chrome does not give it. Those three
+ * and it needs a **layout** the docs shell does not give it. Those three
  * differences are policies on the type rather than branches in the scaffold,
  * which is exactly what #9 claimed they would be — so this file adds a parser
  * and three declarations, and nothing else.
@@ -24,6 +24,8 @@
  * responses, the try-it client — travels as props.
  */
 import { stringify as stringifyYaml } from 'yaml';
+import { frontmatterBlock } from './frontmatter';
+import { firstLine, pageOrder, urlSegment } from './section-markdown';
 import type {
   DuxtOpenApiOperation,
   DuxtOpenApiSecurity,
@@ -34,6 +36,7 @@ import type {
 import { compactOpenApi, parseOpenApiDocument } from './openapi-parse';
 import type {
   DuxtSectionContext,
+  DuxtSectionInput,
   DuxtSectionPage,
   DuxtSectionType
 } from './sections-resolve';
@@ -75,13 +78,13 @@ export const openapiSectionType: DuxtSectionType = {
 };
 
 function parseOpenApiSection(
-  artefact: string,
+  input: DuxtSectionInput,
   context: DuxtSectionContext
 ): DuxtSectionPage[] {
   let spec: DuxtOpenApiSpec;
 
   try {
-    spec = parseOpenApiDocument(artefact);
+    spec = parseOpenApiDocument(input.text());
   } catch (error) {
     // Rethrown rather than swallowed into an empty section: the scaffold turns
     // "no pages" into the right severity for local and remote alike, but a
@@ -103,8 +106,8 @@ function parseOpenApiSection(
 
   const groups = spec.tags.map((tag, index) => ({
     tag,
-    slug: segment(tag.name),
-    order: order(index, spec.tags!.length)
+    slug: urlSegment(tag.name),
+    order: pageOrder(index, spec.tags!.length)
   }));
 
   // A tag whose name slugifies to the same segment as another's would serve
@@ -228,7 +231,7 @@ function pagesFor(
         group,
         operation,
         slugs[position]!,
-        order(position, width)
+        pageOrder(position, width)
       )
     )
   ];
@@ -322,8 +325,8 @@ function operationSlugs(operations: DuxtOpenApiOperation[]): string[] {
 
   return operations.map((operation) => {
     const base =
-      segment(operation.operationId ?? '') ||
-      segment(`${operation.method}-${operation.path}`) ||
+      urlSegment(operation.operationId ?? '') ||
+      urlSegment(`${operation.method}-${operation.path}`) ||
       operation.method;
 
     let candidate = base;
@@ -335,62 +338,6 @@ function operationSlugs(operations: DuxtOpenApiOperation[]): string[] {
   });
 }
 
-/**
- * A URL segment: lowercase, no dots.
- *
- * The dots matter. Content reads a name made of digits and dots as a version
- * and stops refining it, which would leave the `NN.` ordering prefix in the
- * URL — the same trap `sections-changelog.ts` answers with a leading `v`. An
- * endpoint at `/v1.0/pets` walks straight into it, so the dot goes.
- */
-function segment(value: string): string {
-  return value
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
-
-/** Zero-padded so ten pages still sort the way they read. */
-function order(index: number, total: number): string {
-  return String(index + 1).padStart(String(total).length, '0');
-}
-
-/**
- * The first paragraph of a description, as one line of PLAIN text.
- *
- * Plain matters because of where this goes: a page's `description`
- * frontmatter, which becomes the meta description, the og tag and the card in
- * a search result, and the summary on a group card. A CommonMark description
- * carrying `*emphasis*` or a `[link](url)` renders as prose everywhere it is
- * rendered as prose — and as its own punctuation everywhere it is not.
- *
- * Deliberately small. It undoes the four inline constructs a one-line summary
- * actually meets — emphasis, code spans, links and images — and leaves
- * everything else alone rather than growing into a second Markdown parser
- * whose disagreements with the first would be invisible.
- */
-function firstLine(value?: string): string | undefined {
-  const line = plain(value?.split(/\n\s*\n/)[0] ?? '')
-    .replace(/\s+/g, ' ')
-    .trim();
-
-  return line || undefined;
-}
-
-/** Inline Markdown, as the text it renders to. */
-function plain(value: string): string {
-  return (
-    value
-      // An image before a link: `![alt](src)` is a link with a `!` in front, and
-      // taking the link first would leave the `!` behind.
-      .replaceAll(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
-      .replaceAll(/\[([^\]]*)\]\([^)]*\)/g, '$1')
-      .replaceAll(/`([^`]*)`/g, '$1')
-      .replaceAll(/(\*\*|__)(.+?)\1/g, '$2')
-      .replaceAll(/(\*|_)(.+?)\1/g, '$2')
-  );
-}
-
 /**
  * An MDC block component with YAML props and Markdown inside it.
  *
@@ -428,23 +375,5 @@ function page(
   fields: Record<string, string | undefined>,
   lines: string[]
 ): string {
-  return [frontmatter(fields), '', ...lines, ''].join('\n');
-}
-
-/**
- * A frontmatter block YAML can read back.
- *
- * Every value is a JSON string, which is also a YAML double-quoted scalar — so
- * a summary carrying a colon cannot end the mapping early. The rule
- * `tests/frontmatter-yaml.test.ts` exists over, and a title like
- * `GET /pets/{petId}: not found` is exactly the shape that breaks it.
- */
-function frontmatter(fields: Record<string, string | undefined>): string {
-  return [
-    '---',
-    ...Object.entries(fields)
-      .filter(([, value]) => value !== undefined && value !== '')
-      .map(([key, value]) => `${key}: ${JSON.stringify(value)}`),
-    '---'
-  ].join('\n');
+  return [frontmatterBlock(fields), '', ...lines, ''].join('\n');
 }

package/sections-resolve.ts

@@ -28,6 +28,7 @@ import {
   resolveSources,
   slugify
 } from './sources-resolve';
+import { brunoSectionType } from './sections-bruno';
 import { changelogSectionType } from './sections-changelog';
 import { openapiSectionType } from './sections-openapi';
 
@@ -167,10 +168,129 @@ export interface DuxtSectionPage {
   body: string;
 }
 
+/**
+ * The artefact a type reads, as the type reads it.
+ *
+ * A LAZY HANDLE rather than a string, and that is the whole of this seam's
+ * second version. `parse` took `artefact: string`, which said one thing the
+ * registry had never meant to promise: that an artefact is one file. A
+ * changelog is, an OpenAPI document is — a Bruno collection is `bruno.json`
+ * beside a directory of `.bru` files, `folder.bru` ordering and an
+ * `environments/` folder nobody should publish, and no single string carries
+ * it.
+ *
+ * So the type is handed WHERE its input is and is left to read it. The central
+ * resolver keeps the severity policy, the report and the prefix; what a tree
+ * means is the type's, which is the only place the knowledge belongs — a
+ * resolver that walked a Bruno collection would have to walk the next type's
+ * too.
+ *
+ * `text` throws rather than returning `''` for a directory: a type that asks a
+ * directory for its contents has a bug, and an empty string turns it into an
+ * empty section reported as a missing artefact three files away.
+ */
+export interface DuxtSectionInput {
+  /** The declared path, relative to the source's own root. */
+  path: string;
+  /**
+   * The checkout `path` resolves against, where the artefact was read out of a
+   * repository whose history this build is allowed to read.
+   *
+   * ABSENT IS THE DEFAULT, AND MEANS "DO NOT LOOK". It is filled in only for an
+   * artefact read out of the repository being built. A remote source is a
+   * `--depth 1` clone, where every commit looks as though one person wrote it
+   * — wrong data rather than missing data, which is the line
+   * `modules/git-meta.ts` already draws and for the same reason. The one
+   * exception is a remote source that IS the repository being built: the
+   * artefact still comes from the download, but this points at the local
+   * checkout, which carries the same tags with their whole history — see
+   * `localHistoryFor`. An in-memory
+   * input leaves it unset too, so a type under test never reaches a real
+   * repository and a fixture version that happens to match a real tag cannot
+   * quietly pick up real people.
+   *
+   * A type that only turns a file into pages never asks. The release history
+   * does: which people a release carries is a fact about the commits between
+   * two tags, and no changelog file holds it.
+   */
+  root?: string;
+  /** Whether the declared path is one file or a tree. */
+  kind: 'file' | 'directory';
+  /** The whole file. Throws when the input is a directory. */
+  text: () => string;
+  /**
+   * Every file under a directory input, as `/`-separated relative paths.
+   *
+   * Sorted, so a type that walks them produces the same pages on every machine
+   * — a directory listing is not ordered, and a section whose page order
+   * depended on the filesystem would reorder itself on a different one.
+   *
+   * Empty for a file input.
+   */
+  files: () => string[];
+  /** One file under a directory input, by its relative path. */
+  read: (file: string) => string;
+}
+
+/**
+ * An input over files already in memory.
+ *
+ * The pure half of what `sections.ts` builds out of `node:fs`, so a type's
+ * parser is testable without a fixture directory — and so a consumer's own type
+ * can be given one.
+ */
+export function duxtSectionInput(
+  path: string,
+  files: Record<string, string> | string
+): DuxtSectionInput {
+  if (typeof files === 'string') {
+    return {
+      path,
+      kind: 'file',
+      text: () => files,
+      files: () => [],
+      read: () => ''
+    };
+  }
+
+  const names = Object.keys(files).sort();
+
+  return {
+    path,
+    kind: 'directory',
+    text: () => {
+      throw new Error(
+        `duxt: "${path}" is a directory, and this type asked it for a file.`
+      );
+    },
+    files: () => [...names],
+    read: (file) => files[file] ?? ''
+  };
+}
+
 /** What the parser is told about the section it is filling. */
 export interface DuxtSectionContext {
   /** The declared label, which is also the index page's title. */
   label: string;
+  /**
+   * The Content collection these pages land in.
+   *
+   * The one identity that is unique per version AND per locale — a prefix is
+   * not, since two languages deliberately claim the same one. A type that has
+   * to name a build-time artefact of its own (the Bruno collection's ZIP) needs
+   * a name the module emitting it can compute the same way, and this is it.
+   */
+  collection: string;
+  /**
+   * Whether the artefact came out of a repository Content downloads.
+   *
+   * A type that only turns a file into pages never asks. One whose section
+   * offers something built BESIDE the pages does: `section-reports.ts` states
+   * the limit this reflects — a remote checkout lands wherever Content's
+   * hash-cache put it, which is a directory known only inside the collection
+   * that declared it, so nothing outside can read the artefact a second time.
+   */
+  remote: boolean;
   /** The URL prefix its pages are served at, e.g. `/releases`. */
   prefix: string;
   /** The declaration's own `options`, empty where it named none. */
@@ -223,15 +343,42 @@ export interface DuxtSectionReport {
  */
 export interface DuxtSectionType {
   /** The artefact, split into pages carrying their own frontmatter. */
-  parse: (artefact: string, context: DuxtSectionContext) => DuxtSectionPage[];
+  parse: (
+    input: DuxtSectionInput,
+    context: DuxtSectionContext
+  ) => DuxtSectionPage[];
+  /**
+   * Whether the declared path names a file or a directory.
+   *
+   * `file` is the default and what the first two types are: the path is opened
+   * and its contents handed over. `directory` hands the type the tree instead —
+   * `input.files()` and `input.read()` — and is what a client-side collection
+   * like Bruno's needs, since there is no one file to open.
+   *
+   * A POLICY rather than a guess at the path: a type knows what it reads, and a
+   * resolver that stat'ed the path would report a missing directory as a
+   * missing file and say the wrong thing about both.
+   */
+  input?: 'file' | 'directory';
   /**
    * How this type behaves against the one-collection-per-version mechanic.
    *
    * `global` is one history read from the default version and served at a
-   * version-neutral URL, with the switcher suppressed — what a changelog is.
-   * `per-version` is a section per version, like any other page.
+   * version-neutral URL, with the switcher suppressed. `per-version` is a
+   * section per version, like any other page — what the API reference and the
+   * changelog are.
    */
   versioning: 'global' | 'per-version';
+  /**
+   * Whether every published version has to have the artefact.
+   *
+   * `optional`, the default, is the rule `missingSectionArtefact` states for a
+   * source: a local path that does not exist fails the build, a remote one is
+   * recorded and its section simply not built. `required` fails the build for
+   * a remote version too — for a type whose missing file cannot be quietly
+   * skipped without publishing the wrong thing, as a changelog cannot.
+   */
+  artefact?: 'required' | 'optional';
   /**
    * What a localised site shows when the artefact has one language.
    *
@@ -251,11 +398,11 @@ export interface DuxtSectionType {
    * The layout its pages render in, through the shared slot.
    *
    * A layout name a type binds is PUBLIC SURFACE — renaming one later is a
-   * `feat!:`. Unset renders the section in the ordinary docs chrome.
+   * `feat!:`. Unset renders the section in the ordinary docs shell.
    *
    * A FUNCTION where the declaration's own options decide: the same type can
    * produce two different things, and a changelog is the case that proves it —
-   * split into a page per release it is a timeline with chrome of its own,
+   * split into a page per release it is a timeline with a layout of its own,
    * rendered as the one file it was written as it is an ordinary docs page and
    * wants the sidebar, the breadcrumb and the table of contents back.
    */
@@ -269,6 +416,7 @@ export type DuxtSectionTypes = Record<string, DuxtSectionType>;
 
 /** The types the layer ships. */
 export const duxtBuiltinSectionTypes: DuxtSectionTypes = {
+  bruno: brunoSectionType,
   changelog: changelogSectionType,
   openapi: openapiSectionType
 };
@@ -485,6 +633,10 @@ export function resolveGeneratedSections(
             }`,
             prefix,
             repo: base.entry.repo,
+            // The SOURCE's name, not the artefact's. A generated section is
+            // published by the project its source is, and the artefact has a
+            // label of its own that the search caption draws beside this.
+            name: base.entry.name,
             // `global` is version-NEUTRAL, so it carries no version at all: the
             // switcher lists what has a version, and a changelog must not be
             // offered as one of the versions of the documentation beside it.
@@ -639,12 +791,14 @@ export function generatedSectionRef(
 export function sectionPages(
   entry: DuxtResolvedSource,
   type: DuxtSectionType,
-  artefact: string
+  input: DuxtSectionInput
 ): DuxtSectionPage[] {
   const warnings: string[] = [];
 
-  const pages = type.parse(artefact, {
+  const pages = type.parse(input, {
     label: entry.generated!.label,
+    collection: entry.collection,
+    remote: entry.generated!.remote,
     prefix: entry.prefix,
     options: entry.generated!.options ?? {},
     warn: (message) => {
@@ -687,10 +841,22 @@ export function sectionPages(
  */
 export function missingSectionArtefact(
   entry: DuxtResolvedSource,
-  file: string
+  file: string,
+  type?: Pick<DuxtSectionType, 'artefact'>
 ): DuxtSectionPage[] {
   entry.generated!.report = { pages: 0, warnings: [], missing: true };
 
+  // A type that needs its artefact in EVERY published version fails the build
+  // for a remote version too — see `DuxtSectionType.artefact`.
+  if (entry.generated!.remote && type?.artefact === 'required') {
+    throw new Error(
+      `duxt: the generated section "${entry.generated!.label}" needs ` +
+        `${entry.path} in every published version, and ` +
+        `${entry.version ?? entry.ref ?? 'this version'} has none ` +
+        `(looked in ${file}).`
+    );
+  }
+
   // Remote: recorded, not printed. `validate-report.ts` reads the report and
   // says it once, in the same list as every other finding — see `sectionPages`.
   if (entry.generated!.remote) return [];