@vendure-io/docs-provider 0.7.0 → 0.8.0

package/docs/last-modified-dates.md

@@ -0,0 +1,326 @@
+# Last Modified Dates
+
+This guide explains how to include accurate "last modified" dates in your documentation package. These dates are extracted from git history at build time and displayed on documentation pages.
+
+## The Problem
+
+When documentation packages are installed from npm, file modification times (`mtime`) reflect the installation time, not when the content was actually written. This makes it impossible to show meaningful "last edited" information using standard file system stats.
+
+## The Solution
+
+The docs-provider library provides utilities to:
+
+1. Extract last-modified dates from git history at **build time**
+2. Generate a TypeScript file with hardcoded date mappings
+3. Apply these dates to your navigation nodes
+4. Include the dates in your published npm package
+
+This means dates are resolved once during build, then shipped as static data with no git access needed at runtime.
+
+## Quick Start
+
+### Step 1: Generate Dates File
+
+Create a script to generate dates during your build process:
+
+```typescript
+// scripts/generate-dates.ts
+import { generateDatesFile } from '@vendure-io/docs-provider'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+
+await generateDatesFile({
+  docsDir: join(packageRoot, 'docs'),
+  outputPath: join(packageRoot, 'src/dates.generated.ts'),
+  gitCwd: packageRoot,
+})
+
+console.log('Generated dates.generated.ts')
+```
+
+### Step 2: Add Prebuild Script
+
+Update your `package.json` to run the generation before building:
+
+```json
+{
+  "scripts": {
+    "generate-dates": "tsx scripts/generate-dates.ts",
+    "prebuild": "npm run generate-dates",
+    "build": "tsc"
+  }
+}
+```
+
+### Step 3: Apply Dates to Manifest
+
+Import the generated dates and apply them to your navigation:
+
+```typescript
+// src/manifest.ts
+import {
+  applyLastModifiedDates,
+  createNavigationFromFolder,
+  resolveManifest,
+  type DocsPackageManifestInput,
+} from '@vendure-io/docs-provider'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import { lastModifiedDates } from './dates.generated'
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+const file = (relativePath: string) => join(packageRoot, relativePath)
+
+const manifestInput: DocsPackageManifestInput = {
+  id: 'my-plugin',
+  name: 'My Plugin Documentation',
+  version: '1.0.0',
+  vendureVersion: 'v3',
+  basePath: packageRoot,
+  navigation: [
+    { file: file('docs/getting-started.mdx') },
+    {
+      title: 'Guides',
+      slug: 'guides',
+      children: createNavigationFromFolder(join(packageRoot, 'docs/guides')),
+    },
+  ],
+}
+
+// Resolve the manifest first (derives title/slug from files)
+const resolvedManifest = resolveManifest(manifestInput)
+
+// Apply dates from the generated file
+export const manifest = {
+  ...resolvedManifest,
+  navigation: applyLastModifiedDates(
+    resolvedManifest.navigation,
+    lastModifiedDates,
+    { basePath: 'docs' }
+  ),
+}
+```
+
+### Step 4: Include in Package Files
+
+Ensure the generated file is included when publishing:
+
+```json
+{
+  "files": ["src", "docs", "dist"]
+}
+```
+
+## API Reference
+
+### generateDatesFile
+
+Generates a TypeScript file containing last-modified dates for all MDX files in a directory.
+
+```typescript
+import { generateDatesFile } from '@vendure-io/docs-provider'
+
+const result = await generateDatesFile({
+  // Directory containing MDX files to scan
+  docsDir: '/path/to/docs',
+
+  // Where to write the generated TypeScript file
+  outputPath: '/path/to/src/dates.generated.ts',
+
+  // Git working directory (defaults to parent of docsDir)
+  gitCwd: '/path/to/repo',
+
+  // File extensions to include (defaults to ['.mdx', '.md'])
+  extensions: ['.mdx', '.md'],
+})
+
+console.log(`Extracted dates for ${result.filesWithDates} files`)
+console.log(`Skipped ${result.filesSkipped} files (untracked or new)`)
+```
+
+**Generated Output:**
+
+```typescript
+// dates.generated.ts (auto-generated, do not edit)
+// Generated at: 2024-01-22T10:30:00.000Z
+// Total files: 15
+
+export const lastModifiedDates: Record<string, string> = {
+  'docs/getting-started.mdx': '2024-01-15T10:30:00+01:00',
+  'docs/guides/installation.mdx': '2024-01-10T08:00:00+01:00',
+  'docs/guides/configuration.mdx': '2024-01-12T14:00:00+01:00',
+}
+```
+
+### applyLastModifiedDates
+
+Applies dates from a map to navigation nodes. This function is browser-safe and doesn't require Node.js.
+
+```typescript
+import { applyLastModifiedDates } from '@vendure-io/docs-provider'
+
+const navigationWithDates = applyLastModifiedDates(
+  navigation,           // NavigationNode[]
+  lastModifiedDates,    // Record<string, string>
+  {
+    // Optional: prefix to prepend to file paths when looking up dates
+    basePath: 'docs'
+  }
+)
+```
+
+**How it works:**
+
+1. Recursively walks the navigation tree
+2. For each node with a `file` property, looks up the date in the map
+3. Adds `lastModified` property with the ISO 8601 date string
+4. Returns a new tree (does not mutate the original)
+
+### Git Utility Functions
+
+Lower-level utilities for working with git dates directly:
+
+```typescript
+import {
+  isGitRepository,
+  getGitLastModified,
+  getGitLastModifiedBatch,
+} from '@vendure-io/docs-provider'
+
+// Check if a directory is a git repository
+const isGit = await isGitRepository('/path/to/dir')
+
+// Get date for a single file
+const date = await getGitLastModified('docs/intro.mdx', {
+  cwd: '/path/to/repo'
+})
+// Returns: '2024-01-15T10:30:00+01:00' or null
+
+// Get dates for multiple files efficiently
+const result = await getGitLastModifiedBatch(
+  ['docs/intro.mdx', 'docs/guide.mdx'],
+  { cwd: '/path/to/repo' }
+)
+// Returns: { dates: { 'docs/intro.mdx': '2024-...' }, skipped: [] }
+```
+
+## Date Format
+
+All dates use ISO 8601 format with timezone offset:
+
+```
+2024-01-15T10:30:00+01:00
+```
+
+This format is:
+- Human-readable
+- Machine-parseable
+- Timezone-aware
+- Compatible with JavaScript's `new Date()` constructor
+
+## Edge Cases
+
+### Untracked Files
+
+Files not yet committed to git will be skipped (no date assigned). This is intentional - new files don't have a meaningful "last modified" date until they're part of the git history.
+
+### Non-Git Directories
+
+If `generateDatesFile` is run outside a git repository:
+- A warning is logged
+- An empty dates file is generated
+- No errors are thrown
+
+This allows the build to succeed in CI environments that might do shallow clones or lack git history.
+
+### Frontmatter Override
+
+You can manually specify a `lastModified` date in frontmatter to override the git-derived date:
+
+```mdx
+---
+title: My Page
+lastModified: '2024-01-20T12:00:00Z'
+---
+
+# My Page
+
+Content here...
+```
+
+The frontmatter date takes precedence over the git date when both are present.
+
+## Complete Example
+
+See the full workflow in a docs package:
+
+**Project structure:**
+
+```
+@vendure/docs-my-plugin/
+├── scripts/
+│   └── generate-dates.ts
+├── src/
+│   ├── index.ts
+│   ├── manifest.ts
+│   └── dates.generated.ts  # Generated
+├── docs/
+│   ├── getting-started.mdx
+│   └── guides/
+│       └── installation.mdx
+├── package.json
+└── tsconfig.json
+```
+
+**package.json:**
+
+```json
+{
+  "name": "@vendure/docs-my-plugin",
+  "scripts": {
+    "generate-dates": "tsx scripts/generate-dates.ts",
+    "prebuild": "npm run generate-dates",
+    "build": "tsc"
+  },
+  "files": ["src", "docs", "dist"]
+}
+```
+
+**.gitignore:**
+
+```
+# Generated files (regenerated on each build)
+src/dates.generated.ts
+```
+
+## Best Practices
+
+1. **Run generation in prebuild**: This ensures dates are always fresh when publishing
+
+2. **Commit or ignore the generated file**: Either approach works:
+   - **Ignore**: Cleaner git history, regenerated on each build
+   - **Commit**: Visible history of date changes, works without git in CI
+
+3. **Use appropriate basePath**: Match the path structure between your dates map keys and navigation file paths
+
+4. **Handle missing dates gracefully**: The docs application shows nothing when `lastModified` is null, so missing dates won't break your site
+
+## Troubleshooting
+
+### Dates not appearing
+
+1. Check that `lastModifiedDates` is being imported correctly
+2. Verify the file paths in the dates map match your navigation's `file` properties
+3. Try different `basePath` values in `applyLastModifiedDates`
+
+### All files skipped
+
+1. Ensure you're running in a git repository
+2. Check that files are committed (not just staged)
+3. Verify the `gitCwd` option points to the repository root
+
+### Wrong dates
+
+Git uses the committer date, not the author date. If you've rebased or amended commits, dates may not reflect the original authoring time.

package/docs/mdx-testing.md

@@ -77,7 +77,7 @@ Tests all MDX files referenced in a manifest's navigation tree.
 ```typescript
 async function testManifestMdx(
   manifest: DocsPackageManifest,
-  options?: TestManifestOptions
+  options?: TestManifestOptions,
 ): Promise<MdxTestReport>
 ```
 
@@ -88,12 +88,12 @@ async function testManifestMdx(
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `failFast` | `boolean` | `false` | Stop on first failure |
+| Option          | Type            | Default         | Description           |
+| --------------- | --------------- | --------------- | --------------------- |
+| `failFast`      | `boolean`       | `false`         | Stop on first failure |
 | `remarkPlugins` | `PluggableList` | Default plugins | Custom remark plugins |
 | `rehypePlugins` | `PluggableList` | Default plugins | Custom rehype plugins |
-| `onProgress` | `Function` | `undefined` | Progress callback |
+| `onProgress`    | `Function`      | `undefined`     | Progress callback     |
 
 **Example with progress reporting:**
 
@@ -114,7 +114,7 @@ Compiles a single MDX string and returns the result.
 async function compileMdx(
   content: string,
   filePath: string,
-  options?: CompileMdxOptions
+  options?: CompileMdxOptions,
 ): Promise<MdxCompilationResult>
 ```
 
@@ -186,7 +186,7 @@ Creates a simple progress reporter for console output.
 function createProgressReporter(): (
   current: number,
   total: number,
-  result: MdxCompilationResult
+  result: MdxCompilationResult,
 ) => void
 ```
 
@@ -304,13 +304,15 @@ Supported types: `info`, `note`, `tip`, `warning`, `caution`, `danger`
 
 ### Code Fence Metadata
 
-```mdx
+````mdx
 ```typescript title="src/example.ts"
 export function example() {
   return 'Hello'
 }
 ```
-```
+````
+
+````
 
 ### GitHub Flavored Markdown
 
@@ -325,7 +327,7 @@ export function example() {
 <Callout type="info" title="Note">
   Custom JSX components work as expected.
 </Callout>
-```
+````
 
 ## Common Errors
 
@@ -339,13 +341,13 @@ Ensure all JSX tags are properly closed:
 
 ```mdx
 <!-- Wrong -->
+
 <div>
   Content here
 
 <!-- Correct -->
-<div>
-  Content here
-</div>
+
+<div>Content here</div>
 ```
 
 ### Invalid JSX Syntax
@@ -355,6 +357,7 @@ Error (line 8:5): Unexpected token
 ```
 
 Check for:
+
 - Missing quotes around attribute values
 - Unescaped special characters (`<`, `>`, `{`, `}`)
 - JavaScript expressions not wrapped in curly braces

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vendure-io/docs-provider",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Contract types and utilities for Vendure documentation packages",
   "private": false,
   "publishConfig": {

package/dist/manifest-D-EWZlSh.cjs

@@ -1 +0,0 @@
-"use strict";var D=Object.defineProperty;var j=(i,t,n)=>t in i?D(i,t,{enumerable:!0,configurable:!0,writable:!0,value:n}):i[t]=n;var f=(i,t,n)=>j(i,typeof t!="symbol"?t+"":t,n);const e=require("zod"),g=e.z.enum(["v1","v2","v3"]),d=e.z.object({indexFields:e.z.array(e.z.enum(["title","description","content","keywords"])),boosts:e.z.record(e.z.string(),e.z.number()).optional()}),u=e.z.object({repository:e.z.string().regex(/^[^/]+\/[^/]+$/,'Repository must be in format "owner/repo"'),branch:e.z.string().optional(),docsPath:e.z.string().optional()}),l=e.z.lazy(()=>e.z.object({title:e.z.string().min(1,"Navigation title is required"),slug:e.z.string().min(1,"Navigation slug is required"),file:e.z.string().optional(),children:e.z.array(l).optional(),badge:e.z.string().optional(),hidden:e.z.boolean().optional()})),h=e.z.object({id:e.z.string().min(1,"Package ID is required"),name:e.z.string().min(1,"Package name is required"),version:e.z.string().regex(/^\d+\.\d+\.\d+/,"Version must be valid semver"),vendureVersion:g,navigation:e.z.array(l),search:d.optional(),github:u.optional(),basePath:e.z.string().optional()}),p=e.z.object({title:e.z.string().min(1,"Page title is required"),description:e.z.string().optional(),keywords:e.z.array(e.z.string()).optional(),sidebarLabel:e.z.string().optional(),hidden:e.z.boolean().optional(),order:e.z.number().int().optional()}),k=e.z.object({meta:p,content:e.z.string(),filePath:e.z.string()}),I=e.z.object({manifest:h,basePath:e.z.string()}),M=e.z.object({title:e.z.string(),slug:e.z.string(),path:e.z.string()}),V=e.z.object({title:e.z.string(),slug:e.z.string(),file:e.z.string().optional(),children:e.z.array(e.z.lazy(()=>l)).optional(),badge:e.z.string().optional(),hidden:e.z.boolean().optional(),path:e.z.string(),depth:e.z.number().int().min(0),parentPath:e.z.string().optional()}),z=e.z.lazy(()=>e.z.object({title:e.z.string().min(1).optional(),slug:e.z.string().min(1).optional(),file:e.z.string().optional(),children:e.z.array(z).optional(),badge:e.z.string().optional(),hidden:e.z.boolean().optional()})),x=e.z.object({id:e.z.string().min(1,"Package ID is required"),name:e.z.string().min(1,"Package name is required"),version:e.z.string().regex(/^\d+\.\d+\.\d+/,"Version must be valid semver"),vendureVersion:g,navigation:e.z.array(z),search:d.optional(),github:u.optional(),basePath:e.z.string().optional()});class b extends Error{constructor(n,o){super(n);f(this,"issues");this.name="ManifestValidationError",this.issues=o}}function q(i){const t=h.safeParse(i);if(!t.success){const n=t.error.issues.map(o=>`${o.path.join(".")}: ${o.message}`);throw new b("Invalid manifest",n)}return t.data}function B(i,t){const n=t.split("/").filter(Boolean);return v(i.navigation,n)}function v(i,t){if(t.length===0)return;const[n,...o]=t,a=i.find(r=>r.slug===n);if(a){if(o.length===0)return a;if(a.children)return v(a.children,o)}}function m(i){const t=[];return N(i.navigation,"",0,void 0,t),t}function N(i,t,n,o,a){for(const r of i){const s=t?`${t}/${r.slug}`:r.slug;a.push({...r,path:s,depth:n,parentPath:o}),r.children&&r.children.length>0&&N(r.children,s,n+1,s,a)}}function $(i,t){const n=t.split("/").filter(Boolean),o=[];let a=i.navigation,r="";for(const s of n){const c=a.find(y=>y.slug===s);if(!c)break;r=r?`${r}/${s}`:s,o.push({title:c.title,slug:c.slug,path:r,file:c.file}),a=c.children??[]}return o}function S(i){return m(i).filter(t=>t.file!==void 0)}function w(i,t){const n=S(i),o=n.findIndex(a=>a.path===t);return o===-1?{}:{prev:o>0?n[o-1]:void 0,next:o<n.length-1?n[o+1]:void 0}}function P(i,t){const n=t.split("/").filter(Boolean);if(n.length===0)return!1;if(i.slug===n[0]){if(n.length===1)return!0;if(i.children){const o=n.slice(1).join("/");return i.children.some(a=>P(a,o))}}return!1}function L(i,t){return m(i).filter(n=>n.depth===t)}exports.BreadcrumbItemSchema=M;exports.DocPageMetaSchema=p;exports.DocPageSchema=k;exports.DocsPackageManifestInputSchema=x;exports.DocsPackageManifestSchema=h;exports.FlatNavigationNodeSchema=V;exports.GitHubConfigSchema=u;exports.LoadedDocsPackageSchema=I;exports.ManifestValidationError=b;exports.NavigationNodeInputSchema=z;exports.NavigationNodeSchema=l;exports.SearchConfigSchema=d;exports.VendureVersionSchema=g;exports.buildBreadcrumbs=$;exports.findNavigationNode=B;exports.flattenNavigation=m;exports.getLeafNodes=S;exports.getNodesAtDepth=L;exports.getPrevNextNodes=w;exports.isNodeActive=P;exports.validateManifest=q;

package/dist/manifest-ZCrzbFSf.js

@@ -1,182 +0,0 @@
-var P = Object.defineProperty;
-var S = (i, t, e) => t in i ? P(i, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : i[t] = e;
-var g = (i, t, e) => S(i, typeof t != "symbol" ? t + "" : t, e);
-import { z as n } from "zod";
-const d = n.enum(["v1", "v2", "v3"]), u = n.object({
-  indexFields: n.array(n.enum(["title", "description", "content", "keywords"])),
-  boosts: n.record(n.string(), n.number()).optional()
-}), f = n.object({
-  repository: n.string().regex(/^[^/]+\/[^/]+$/, 'Repository must be in format "owner/repo"'),
-  branch: n.string().optional(),
-  docsPath: n.string().optional()
-}), c = n.lazy(
-  () => n.object({
-    title: n.string().min(1, "Navigation title is required"),
-    slug: n.string().min(1, "Navigation slug is required"),
-    file: n.string().optional(),
-    children: n.array(c).optional(),
-    badge: n.string().optional(),
-    hidden: n.boolean().optional()
-  })
-), h = n.object({
-  id: n.string().min(1, "Package ID is required"),
-  name: n.string().min(1, "Package name is required"),
-  version: n.string().regex(/^\d+\.\d+\.\d+/, "Version must be valid semver"),
-  vendureVersion: d,
-  navigation: n.array(c),
-  search: u.optional(),
-  github: f.optional(),
-  basePath: n.string().optional()
-}), y = n.object({
-  title: n.string().min(1, "Page title is required"),
-  description: n.string().optional(),
-  keywords: n.array(n.string()).optional(),
-  sidebarLabel: n.string().optional(),
-  hidden: n.boolean().optional(),
-  order: n.number().int().optional()
-}), I = n.object({
-  meta: y,
-  content: n.string(),
-  filePath: n.string()
-}), q = n.object({
-  manifest: h,
-  basePath: n.string()
-}), B = n.object({
-  title: n.string(),
-  slug: n.string(),
-  path: n.string()
-}), M = n.object({
-  title: n.string(),
-  slug: n.string(),
-  file: n.string().optional(),
-  children: n.array(n.lazy(() => c)).optional(),
-  badge: n.string().optional(),
-  hidden: n.boolean().optional(),
-  path: n.string(),
-  depth: n.number().int().min(0),
-  parentPath: n.string().optional()
-}), m = n.lazy(
-  () => n.object({
-    title: n.string().min(1).optional(),
-    slug: n.string().min(1).optional(),
-    file: n.string().optional(),
-    children: n.array(m).optional(),
-    badge: n.string().optional(),
-    hidden: n.boolean().optional()
-  })
-), $ = n.object({
-  id: n.string().min(1, "Package ID is required"),
-  name: n.string().min(1, "Package name is required"),
-  version: n.string().regex(/^\d+\.\d+\.\d+/, "Version must be valid semver"),
-  vendureVersion: d,
-  navigation: n.array(m),
-  search: u.optional(),
-  github: f.optional(),
-  basePath: n.string().optional()
-});
-class j extends Error {
-  constructor(e, o) {
-    super(e);
-    g(this, "issues");
-    this.name = "ManifestValidationError", this.issues = o;
-  }
-}
-function w(i) {
-  const t = h.safeParse(i);
-  if (!t.success) {
-    const e = t.error.issues.map((o) => `${o.path.join(".")}: ${o.message}`);
-    throw new j("Invalid manifest", e);
-  }
-  return t.data;
-}
-function z(i, t) {
-  const e = t.split("/").filter(Boolean);
-  return p(i.navigation, e);
-}
-function p(i, t) {
-  if (t.length === 0) return;
-  const [e, ...o] = t, a = i.find((r) => r.slug === e);
-  if (a) {
-    if (o.length === 0) return a;
-    if (a.children)
-      return p(a.children, o);
-  }
-}
-function b(i) {
-  const t = [];
-  return v(i.navigation, "", 0, void 0, t), t;
-}
-function v(i, t, e, o, a) {
-  for (const r of i) {
-    const s = t ? `${t}/${r.slug}` : r.slug;
-    a.push({
-      ...r,
-      path: s,
-      depth: e,
-      parentPath: o
-    }), r.children && r.children.length > 0 && v(r.children, s, e + 1, s, a);
-  }
-}
-function L(i, t) {
-  const e = t.split("/").filter(Boolean), o = [];
-  let a = i.navigation, r = "";
-  for (const s of e) {
-    const l = a.find((N) => N.slug === s);
-    if (!l) break;
-    r = r ? `${r}/${s}` : s, o.push({
-      title: l.title,
-      slug: l.slug,
-      path: r,
-      file: l.file
-    }), a = l.children ?? [];
-  }
-  return o;
-}
-function k(i) {
-  return b(i).filter((t) => t.file !== void 0);
-}
-function E(i, t) {
-  const e = k(i), o = e.findIndex((a) => a.path === t);
-  return o === -1 ? {} : {
-    prev: o > 0 ? e[o - 1] : void 0,
-    next: o < e.length - 1 ? e[o + 1] : void 0
-  };
-}
-function x(i, t) {
-  const e = t.split("/").filter(Boolean);
-  if (e.length === 0) return !1;
-  if (i.slug === e[0]) {
-    if (e.length === 1) return !0;
-    if (i.children) {
-      const o = e.slice(1).join("/");
-      return i.children.some((a) => x(a, o));
-    }
-  }
-  return !1;
-}
-function F(i, t) {
-  return b(i).filter((e) => e.depth === t);
-}
-export {
-  B,
-  y as D,
-  M as F,
-  f as G,
-  q as L,
-  j as M,
-  m as N,
-  u as S,
-  d as V,
-  I as a,
-  $ as b,
-  h as c,
-  c as d,
-  L as e,
-  z as f,
-  b as g,
-  k as h,
-  F as i,
-  E as j,
-  x as k,
-  w as v
-};