pulumi-package-docs 0.8.0 → 0.9.1

package/bin/static.js

@@ -0,0 +1,196 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { spawn } from 'node:child_process'
+import { dirname, isAbsolute, join, relative } from 'node:path'
+
+/**
+ * Written into every generated site. `--out` is wiped and rebuilt on each run,
+ * so this marks a directory as ours to overwrite: without it (and without
+ * `--force`), a non-empty output directory is left alone.
+ */
+export const SITE_MARKER = '.pulumi-package-docs-site'
+
+/** The intermediate Vite output directory (see `build.outDir` in vite.config.ts). */
+const STATIC_BUILD_DIR = 'dist-static'
+
+/**
+ * Normalizes a `--base` value to the form Vite and the router want: a path
+ * with both a leading and a trailing slash ("/repo" -> "/repo/"), or "/" for a
+ * site served from a domain root.
+ */
+export function normalizeBase(base) {
+  const trimmed = (base ?? '').trim()
+  if (trimmed === '' || trimmed === '/') return '/'
+  return `/${trimmed.replace(/^\/+/, '').replace(/\/+$/, '')}/`
+}
+
+/**
+ * Drops the leftovers of a client bundle the static pages never load.
+ *
+ * Static pages are rendered without the hydration script (see
+ * `src/lib/static-docs.ts`), but the framework still emits `modulepreload`
+ * hints for the client chunks and, after `</html>`, the serialized loader data
+ * hydration would have used. Nothing reads either one here, so removing them
+ * saves every page a round of pointless downloads and roughly halves its size.
+ * Both patterns are best-effort: if a future version emits something else, the
+ * pages are merely bigger, never broken.
+ */
+export function stripClientPayload(html) {
+  return html
+    .replace(/<link\s+rel="modulepreload"[^>]*>/g, '')
+    .replace(/<\/html>[\s\S]*$/, '</html>')
+}
+
+function walk(dir) {
+  const files = []
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) files.push(...walk(full))
+    else files.push(full)
+  }
+  return files
+}
+
+/** True when `child` is `parent` itself or sits inside it. */
+function contains(parent, child) {
+  const rel = relative(parent, child)
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))
+}
+
+function isReusableOutputDir(out) {
+  if (!existsSync(out)) return true
+  if (!statSync(out).isDirectory()) return false
+  const entries = readdirSync(out)
+  return entries.length === 0 || entries.includes(SITE_MARKER)
+}
+
+/**
+ * Copies a prerendered client build into the output directory, rewriting HTML
+ * on the way, and adds the files a Pages host expects.
+ */
+export function collectSite(clientDir, out) {
+  rmSync(out, { recursive: true, force: true })
+  mkdirSync(out, { recursive: true })
+
+  const files = walk(clientDir)
+  const htmlFiles = files.filter((file) => file.endsWith('.html'))
+  const assetFiles = files.filter((file) => !file.endsWith('.html'))
+
+  let rendered = ''
+  for (const file of htmlFiles) {
+    const html = stripClientPayload(readFileSync(file, 'utf-8'))
+    const target = join(out, relative(clientDir, file))
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, html)
+    rendered += html
+  }
+
+  for (const file of assetFiles) {
+    const path = relative(clientDir, file).split('\\').join('/')
+    // The client bundle is built but never loaded by a static page, so its
+    // chunks are dead weight in the published site. Scripts are the only
+    // asset a page can pull in without the HTML naming them (stylesheets are
+    // linked, and this app's CSS references no other files), so checking the
+    // rendered HTML is enough to know a chunk is unused.
+    if (/\.(js|mjs|map)$/.test(path) && !rendered.includes(path)) continue
+    const target = join(out, path)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, readFileSync(file))
+  }
+
+  const pages = htmlFiles.length
+
+  // GitHub Pages runs the output through Jekyll unless this file is present,
+  // which would drop anything starting with "_" or ".".
+  writeFileSync(join(out, '.nojekyll'), '')
+  writeFileSync(
+    join(out, SITE_MARKER),
+    'Generated by `pulumi-package-docs static`. This directory is rebuilt from scratch on every run.\n',
+  )
+
+  return pages
+}
+
+function runViteBuild({ packageRoot, viteBin, dir, base }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [viteBin, 'build'], {
+      cwd: packageRoot,
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        PULUMI_LOCAL_DOCS_DIR: dir,
+        VITE_STATIC_DOCS: 'true',
+        PULUMI_DOCS_BASE: base,
+      },
+    })
+    child.on('error', reject)
+    child.on('exit', (code) =>
+      code === 0
+        ? resolve()
+        : reject(new Error(`vite build exited with code ${code}`)),
+    )
+  })
+}
+
+/**
+ * Builds a self-contained static site for the Pulumi project in `dir`: every
+ * provider, resource and function page prerendered to HTML, ready to publish
+ * to GitHub Pages, GitLab Pages, or any other static host.
+ */
+export async function buildStaticSite({
+  packageRoot,
+  viteBin,
+  dir,
+  out,
+  base,
+  force,
+}) {
+  const normalizedBase = normalizeBase(base)
+
+  // The output directory is wiped and rebuilt on every run, so it must never
+  // be the Pulumi project itself (`--out .`) or anything above it — not even
+  // with --force.
+  if (contains(out, dir)) {
+    throw new Error(
+      `Refusing to generate into ${out}: it holds the Pulumi project being documented, and --out is erased on each run.`,
+    )
+  }
+
+  if (!force && !isReusableOutputDir(out)) {
+    throw new Error(
+      `Refusing to overwrite ${out}: it isn't empty and wasn't generated by pulumi-package-docs.\n` +
+        'Pass --out <path> to write somewhere else, or --force to overwrite it anyway.',
+    )
+  }
+
+  console.log(`Generating static docs for: ${dir}`)
+  if (normalizedBase !== '/') console.log(`Base path: ${normalizedBase}`)
+
+  await runViteBuild({ packageRoot, viteBin, dir, base: normalizedBase })
+
+  const clientDir = join(packageRoot, STATIC_BUILD_DIR, 'client')
+  if (!existsSync(clientDir)) {
+    throw new Error(
+      `The build produced no client output at ${clientDir}; cannot generate a static site.`,
+    )
+  }
+
+  const pages = collectSite(clientDir, out)
+  console.log(`\nWrote ${pages} pages to ${out}`)
+  if (normalizedBase === '/') {
+    console.log(
+      'Preview it locally with: npx serve <out>  (or any static file server)',
+    )
+  } else {
+    console.log(
+      `The site expects to be served from ${normalizedBase} — links and assets are prefixed with it.`,
+    )
+  }
+}

package/bin/static.test.js

@@ -0,0 +1,176 @@
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import {
+  SITE_MARKER,
+  buildStaticSite,
+  collectSite,
+  normalizeBase,
+  stripClientPayload,
+} from './static.js'
+
+const tmpDirs = []
+
+function makeTmpDir() {
+  const dir = mkdtempSync(join(tmpdir(), 'pulumi-package-docs-test-'))
+  tmpDirs.push(dir)
+  return dir
+}
+
+afterEach(() => {
+  while (tmpDirs.length) rmSync(tmpDirs.pop(), { recursive: true, force: true })
+})
+
+describe('normalizeBase', () => {
+  it('keeps a root base as a single slash', () => {
+    expect(normalizeBase('/')).toBe('/')
+    expect(normalizeBase('')).toBe('/')
+    expect(normalizeBase(undefined)).toBe('/')
+  })
+
+  it('adds the leading and trailing slashes a project path needs', () => {
+    expect(normalizeBase('my-repo')).toBe('/my-repo/')
+    expect(normalizeBase('/my-repo')).toBe('/my-repo/')
+    expect(normalizeBase('my-repo/')).toBe('/my-repo/')
+    expect(normalizeBase('  /my-repo/  ')).toBe('/my-repo/')
+  })
+
+  it('keeps nested path segments', () => {
+    expect(normalizeBase('group/project')).toBe('/group/project/')
+  })
+})
+
+describe('stripClientPayload', () => {
+  it('removes modulepreload hints for the unused client bundle', () => {
+    const html =
+      '<html><head><link rel="modulepreload" href="/assets/index-abc.js"/><link rel="stylesheet" href="/assets/app.css"/></head><body>hi</body></html>'
+    const stripped = stripClientPayload(html)
+    expect(stripped).not.toContain('modulepreload')
+    expect(stripped).toContain(
+      '<link rel="stylesheet" href="/assets/app.css"/>',
+    )
+  })
+
+  it('removes the hydration payload emitted after the document', () => {
+    const html = '<html><body>hi</body></html><script>$_TSR.router={}</script>'
+    expect(stripClientPayload(html)).toBe('<html><body>hi</body></html>')
+  })
+
+  it('leaves a page with neither untouched', () => {
+    const html = '<html><body>hi</body></html>'
+    expect(stripClientPayload(html)).toBe(html)
+  })
+})
+
+describe('collectSite', () => {
+  function seedClientDir() {
+    const clientDir = makeTmpDir()
+    mkdirSync(join(clientDir, 'assets'))
+    mkdirSync(join(clientDir, 'providers', 'random'), { recursive: true })
+    writeFileSync(
+      join(clientDir, 'index.html'),
+      '<html><head><link rel="modulepreload" href="/assets/entry.js"/><link rel="stylesheet" href="/assets/app.css"/></head><body>index</body></html><script>$_TSR.router={}</script>',
+    )
+    writeFileSync(
+      join(clientDir, 'providers', 'random', 'index.html'),
+      '<html><body>random</body></html>',
+    )
+    writeFileSync(join(clientDir, 'assets', 'app.css'), 'body{}')
+    writeFileSync(join(clientDir, 'assets', 'entry.js'), 'console.log(1)')
+    return clientDir
+  }
+
+  it('writes every page, stripped, alongside the assets they use', () => {
+    const clientDir = seedClientDir()
+    const out = join(makeTmpDir(), 'site')
+
+    expect(collectSite(clientDir, out)).toBe(2)
+
+    const index = readFileSync(join(out, 'index.html'), 'utf-8')
+    expect(index).not.toContain('modulepreload')
+    expect(index).not.toContain('$_TSR')
+    expect(
+      readFileSync(join(out, 'providers', 'random', 'index.html'), 'utf-8'),
+    ).toContain('random')
+    expect(readFileSync(join(out, 'assets', 'app.css'), 'utf-8')).toBe('body{}')
+  })
+
+  it('leaves out client chunks no page loads', () => {
+    const clientDir = seedClientDir()
+    const out = join(makeTmpDir(), 'site')
+
+    collectSite(clientDir, out)
+
+    expect(readdirSync(join(out, 'assets'))).toEqual(['app.css'])
+  })
+
+  it('keeps a chunk a page does reference', () => {
+    const clientDir = seedClientDir()
+    writeFileSync(
+      join(clientDir, 'index.html'),
+      '<html><body><script type="module" src="/assets/entry.js"></script></body></html>',
+    )
+    const out = join(makeTmpDir(), 'site')
+
+    collectSite(clientDir, out)
+
+    expect(readdirSync(join(out, 'assets')).sort()).toEqual([
+      'app.css',
+      'entry.js',
+    ])
+  })
+
+  it('adds the files a Pages host needs, and replaces a previous run', () => {
+    const clientDir = seedClientDir()
+    const out = join(makeTmpDir(), 'site')
+
+    collectSite(clientDir, out)
+    writeFileSync(join(out, 'stale.html'), 'from a previous run')
+    collectSite(clientDir, out)
+
+    const entries = readdirSync(out)
+    expect(entries).toContain('.nojekyll')
+    expect(entries).toContain(SITE_MARKER)
+    expect(entries).not.toContain('stale.html')
+  })
+})
+
+describe('buildStaticSite', () => {
+  it('refuses an output directory that holds the project being documented', async () => {
+    const dir = makeTmpDir()
+    await expect(
+      buildStaticSite({
+        packageRoot: dir,
+        viteBin: 'unused',
+        dir: join(dir, 'project'),
+        out: dir,
+        base: '/',
+        force: true,
+      }),
+    ).rejects.toThrow(/holds the Pulumi project/)
+  })
+
+  it("refuses an output directory it didn't generate", async () => {
+    const out = makeTmpDir()
+    writeFileSync(join(out, 'index.html'), 'someone else lives here')
+    await expect(
+      buildStaticSite({
+        packageRoot: makeTmpDir(),
+        viteBin: 'unused',
+        dir: makeTmpDir(),
+        out,
+        base: '/',
+        force: false,
+      }),
+    ).rejects.toThrow(/Refusing to overwrite/)
+  })
+})

package/dist/client/assets/MemberDetail-Du4HYTda.js

@@ -0,0 +1 @@
+import{o as e}from"./matchContext-BfDTxnb0.js";import{c as t}from"./index-g58gbZKl.js";import{a as n,n as r,r as i,t as a}from"./examples-zkHFEaMt.js";var o=e();function s({example:e}){return e?(0,o.jsxs)(`div`,{className:`code-example`,children:[(0,o.jsx)(`span`,{className:`code-example-lang`,children:e.language}),(0,o.jsx)(`pre`,{children:(0,o.jsx)(`code`,{children:e.code})})]}):(0,o.jsx)(`p`,{className:`empty-state`,children:`No examples in the schema.`})}function c(e){if(!e)return`any`;if(e.$ref){let t=e.$ref.split(`/`).pop()??e.$ref;return decodeURIComponent(t)}return e.type===`array`&&e.items?`${c(e.items)}[]`:e.type??`any`}function l(e){return e.replace(/([a-z0-9])([A-Z])/g,`$1_$2`).replace(/([A-Z]+)([A-Z][a-z])/g,`$1_$2`).toLowerCase()}function u(e){return e.length===0?e:e.charAt(0).toUpperCase()+e.slice(1)}function d(e,t){switch(t){case`python`:return l(e);case`go`:case`dotnet`:return u(e);default:return e}}function f({properties:e,required:t,runtime:r}){let i=Object.keys(e??{});if(i.length===0)return(0,o.jsx)(`p`,{className:`empty-state`,children:`None`});let a=new Set(t??[]);return(0,o.jsxs)(`table`,{className:`props-table`,children:[(0,o.jsx)(`thead`,{children:(0,o.jsxs)(`tr`,{children:[(0,o.jsx)(`th`,{children:`Name`}),(0,o.jsx)(`th`,{children:`Type`}),(0,o.jsx)(`th`,{children:`Required`}),(0,o.jsx)(`th`,{children:`Description`})]})}),(0,o.jsx)(`tbody`,{children:i.map(t=>{let i=e[t];return(0,o.jsxs)(`tr`,{children:[(0,o.jsx)(`td`,{children:(0,o.jsx)(`code`,{children:d(t,r)})}),(0,o.jsx)(`td`,{children:(0,o.jsx)(`code`,{children:c(i)})}),(0,o.jsx)(`td`,{children:a.has(t)?`yes`:`no`}),(0,o.jsx)(`td`,{children:n(i.description,r)??``})]},t)})})]})}function p({providerName:e,kind:c,displayName:l,token:u,description:d,deprecationMessage:p,runtime:m,inputProperties:h,requiredInputs:g,outputProperties:_,requiredOutputs:v}){let y=n(d,m),b=i(y),x=r(a(y),m);return(0,o.jsxs)(`main`,{className:`provider-detail`,children:[(0,o.jsxs)(t,{to:`/providers/$name`,params:{name:e},className:`back-link`,children:[`← Back to `,e]}),(0,o.jsx)(`h1`,{children:l}),(0,o.jsxs)(`p`,{className:`subtitle`,children:[(0,o.jsx)(`span`,{className:`badge ${c===`Resource`?`badge-resource`:`badge-function`}`,children:c}),` `,`· `,(0,o.jsx)(`code`,{children:u})]}),p&&(0,o.jsxs)(`p`,{className:`banner banner-warning`,children:[`Deprecated: `,p]}),b?.split(/\n{2,}/).map((e,t)=>(0,o.jsx)(`p`,{children:e},t)),(0,o.jsx)(`h2`,{children:`Example`}),(0,o.jsx)(s,{example:x}),(0,o.jsx)(`h2`,{children:`Inputs`}),(0,o.jsx)(f,{properties:h,required:g,runtime:m}),(0,o.jsx)(`h2`,{children:`Outputs`}),(0,o.jsx)(f,{properties:_,required:v,runtime:m})]})}export{p as t};

package/dist/client/assets/{token-oQmZfAP3.js → examples-zkHFEaMt.js}

@@ -1 +1 @@
-var e=/<span\s+((?:pulumi-lang-[a-z]+="[^"]*"\s*)+)>([\s\S]*?)<\/span>/g,t=/pulumi-lang-([a-z]+)="([^"]*)"/g;function n(n,r){return n.replace(e,(e,n,i)=>{if(!r)return i;t.lastIndex=0;let a;for(;a=t.exec(n);)if(a[1]===r)return a[2];return i})}function r(e,t){return e&&n(e,t)}var i=/```([a-zA-Z0-9+#-]+)\n([\s\S]*?)```/g;function a(e){return e?[...e.matchAll(i)].map(e=>({language:e[1].toLowerCase(),code:e[2].trimEnd()})):[]}function o(e){return e&&(e.replace(i,``).trim()||void 0)}function s(e){let t=o(e);if(t)return t.split(/\n{2,}/)[0]?.trim()||void 0}var c={nodejs:[`typescript`,`javascript`],python:[`python`],go:[`go`,`golang`],dotnet:[`csharp`],java:[`java`],yaml:[`yaml`]};function l(e,t){let n=t?c[t]:void 0;return(n?e.find(e=>n.includes(e.language)):void 0)??e[0]}function u(e){let t=e.split(`:`).pop();return t&&t.length>0?t:e}export{s as a,o as i,a as n,r as o,l as r,u as t};
+var e=/<span\s+((?:pulumi-lang-[a-z]+="[^"]*"\s*)+)>([\s\S]*?)<\/span>/g,t=/pulumi-lang-([a-z]+)="([^"]*)"/g;function n(n,r){return n.replace(e,(e,n,i)=>{if(!r)return i;t.lastIndex=0;let a;for(;a=t.exec(n);)if(a[1]===r)return a[2];return i})}function r(e,t){return e&&n(e,t)}var i=/```([a-zA-Z0-9+#-]+)\n([\s\S]*?)```/g;function a(e){return e?[...e.matchAll(i)].map(e=>({language:e[1].toLowerCase(),code:e[2].trimEnd()})):[]}function o(e){return e&&(e.replace(i,``).trim()||void 0)}function s(e){let t=o(e);if(t)return t.split(/\n{2,}/)[0]?.trim()||void 0}var c={nodejs:[`typescript`,`javascript`],python:[`python`],go:[`go`,`golang`],dotnet:[`csharp`],java:[`java`],yaml:[`yaml`]};function l(e,t){let n=t?c[t]:void 0;return(n?e.find(e=>n.includes(e.language)):void 0)??e[0]}export{r as a,s as i,l as n,o as r,a as t};