@beforesemicolon/builder 1.6.2 → 1.6.4

package/README.md

@@ -1,3 +1,216 @@
 # @beforesemicolon/builder
 
-Before Semicolon utility to build npm packages and documentation website
+Utilities to build npm packages and a documentation website for Before Semicolon projects.
+
+This package provides small, focused helpers to:
+
+- Build server-friendly CommonJS and ESM module bundles (dist/cjs and dist/esm).
+- Produce a browser bundle (dist/client.js) for documentation or demos.
+- Render a static documentation website from Markdown files (output defaults to `website/`).
+
+Table of contents
+
+- Features
+- Requirements
+- Installation
+- Quick examples
+  - Library usage (Node)
+  - Building the browser bundle
+  - Generating the documentation website
+- API
+  - buildModules(options?)
+  - buildBrowser(options?)
+  - buildDocs(options?)
+- Documentation site layout and front-matter
+- Scripts (in package.json)
+- Development
+- Contributing
+- License
+
+
+Features
+
+- Builds all TypeScript sources into both ESM and CJS formats using esbuild.
+- Produces a single browser bundle for client-side documentation UI.
+- Static site generator for Markdown: supports layouts, assets, stylesheets, and scripts.
+- Uses marked + highlight.js for Markdown rendering, DOMPurify for sanitization and minifies output CSS/JS/HTML.
+- Simple, zero-config defaults plus options for common customization.
+
+Requirements
+
+- Node.js >= 18.16.0 (see `engines` in package.json)
+
+Installation
+
+Install from npm (package name: `@beforesemicolon/builder`) or use the repo directly.
+
+```
+# npm
+npm install @beforesemicolon/builder
+
+# or using the repository
+git clone https://github.com/beforesemicolon/builder.git
+cd builder
+npm install
+```
+
+Quick examples
+
+Library usage (Node / programmatic)
+
+```js
+// ESM
+import { buildModules, buildBrowser, buildDocs } from '@beforesemicolon/builder'
+
+// Build server-side modules (dist/esm and dist/cjs)
+await buildModules({ directoryPath: 'src' })
+
+// Build single browser bundle (defaults to src/client -> dist/client.js)
+await buildBrowser({ entry: 'src/client', out: 'dist/client.js' })
+
+// Generate static docs (defaults: docs -> website)
+await buildDocs({ srcDir: 'docs', publicDir: 'website' })
+```
+
+CommonJS
+
+```js
+const { buildModules, buildBrowser, buildDocs } = require('@beforesemicolon/builder')
+
+;(async () => {
+  await buildModules()
+  await buildBrowser()
+  await buildDocs()
+})()
+```
+
+CLI / npm scripts
+
+The repo ships with a `build` script that will emit types and run the TypeScript build entry (`build.ts`).
+
+```
+npm run build
+```
+
+This runs TypeScript declaration emission and then executes `build.ts` which calls `buildModules()` to produce the `dist/` outputs.
+
+API
+
+- buildModules(options?: { directoryPath?: string }) => Promise
+  - Scans the given directory (default: `process.cwd()/src`) recursively for files and builds them into:
+    - `dist/esm` (ESM format)
+    - `dist/cjs` (CommonJS format)
+  - Files ending with `.spec.ts` or `/client.ts` are ignored from the module build set.
+  - Uses `esbuild` with minification and keeps symbol names for better stack traces.
+
+- buildBrowser(options?: { entry?: string; out?: string }) => Promise
+  - Bundles a single browser file using `esbuild`.
+  - Defaults: `entry` -> `src/client`, `out` -> `dist/client.js`.
+  - Includes a small plugin to remove the `Doc` export from `@beforesemicolon/html-parser` during bundling (keeps bundle size smaller when that export isn't used).
+  - Generates sourcemaps and minifies the output.
+
+- buildDocs(options?: { srcDir?: string; publicDir?: string }) => Promise
+  - Generates a static documentation website from a Markdown `docs` directory.
+  - Defaults: `srcDir` -> `docs`, `publicDir` -> `website`.
+  - Supported docs structure (defaults used by the generator):
+    - `_layouts/` — custom templates (each module should default-export a function matching `PageProps`)
+    - `assets/` — copied to the site output
+    - `stylesheets/` — CSS files are minified and copied
+    - `scripts/` — JS files are minified and copied
+    - `*.md` — Markdown pages with front-matter to control metadata
+  - Pages use `marked` with a custom renderer (heading IDs, code blocks, links) and `highlight.js` for syntax highlighting.
+  - HTML is sanitized with DOMPurify and minified with `html-minifier`.
+
+Documentation site layout and front-matter
+
+Markdown pages should contain front-matter (YAML) with properties compatible with the site's `PageProps`:
+
+- title: string — page title (used in the HTML title)
+- description: string — meta description
+- order: number — numeric order used when building the site map and sorting pages
+- layout: string — layout name; corresponds to a template in `_layouts` (default: `default`)
+
+PageProps (shape used by layouts)
+
+- name: string
+- path: string (page path, e.g. `/guide/getting-started.html`)
+- order: number
+- title: string
+- description: string
+- content: string (HTML produced from Markdown)
+- siteMap: Map representing the site structure
+- tableOfContent: array of { path, label } entries generated from headings
+
+A minimal docs layout example (the package ships a simple `default` template):
+
+```ts
+export default ({ title, description, content }) => `
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="description" content="${description}" />
+    <title>${title}</title>
+  </head>
+  <body>
+    ${content}
+  </body>
+</html>`
+```
+
+Scripts (from package.json)
+
+- `build` — removes `dist`, emits TypeScript declarations, then runs `build.ts` (which calls `buildModules`).
+- `lint` — runs ESLint and Prettier check
+- `format` — runs ESLint autofix and Prettier write
+
+Development
+
+- Ensure you use Node >= 18.16.0
+- Install dependencies:
+
+```
+npm install
+```
+
+- Run the build pipeline locally:
+
+```
+npm run build
+```
+
+- Lint and format:
+
+```
+npm run lint
+npm run format
+```
+
+- The source entry points are in `src/`. `src/build-modules.ts`, `src/build-browser.ts` and `src/docs/run.ts` provide the public functionality.
+
+Testing and validation
+
+This repository does not include automated tests by default. If you add tests, consider using the existing devDependencies (TypeScript + ts-jest + tinybench if you want benchmarks).
+
+Contributing
+
+Contributions are welcome. A good workflow is:
+
+1. Fork the repository and create a feature branch.
+2. Add or modify code in `src/`.
+3. Run `npm run build` to check the build output.
+4. Run `npm run lint` or `npm run format` to keep code style consistent.
+5. Open a pull request describing the change.
+
+License
+
+BSD-3-Clause — see `package.json` for author and license metadata.
+
+Acknowledgements and internals
+
+- Uses `esbuild` for fast bundling and minification.
+- Markdown rendering powered by `marked` with a custom renderer and `marked-highlight` plugin using `highlight.js`.
+- Front-matter parsing via `front-matter`.
+- DOM sanitization by `isomorphic-dompurify` and HTML/CSS/JS minification using `html-minifier`, `clean-css`, and `@putout/minify` respectively.
+
+If you'd like any sections expanded (examples, advanced options, or a CONTRIBUTING.md), tell me which parts to elaborate and I'll add them.

package/dist/cjs/build-browser.js

@@ -1 +1 @@
-"use strict";var a=Object.create;var n=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var f=Object.getPrototypeOf,y=Object.prototype.hasOwnProperty;var i=(e,r)=>n(e,"name",{value:r,configurable:!0});var g=(e,r)=>{for(var t in r)n(e,t,{get:r[t],enumerable:!0})},c=(e,r,t,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(let o of d(r))!y.call(e,o)&&o!==t&&n(e,o,{get:()=>r[o],enumerable:!(s=m(r,o))||s.enumerable});return e};var p=(e,r,t)=>(t=e!=null?a(f(e)):{},c(r||!e||!e.__esModule?n(t,"default",{value:e,enumerable:!0}):t,e)),h=e=>c(n({},"__esModule",{value:!0}),e);var D={};g(D,{buildBrowser:()=>B});module.exports=h(D);var l=p(require("path"),1),u=p(require("esbuild"),1);const B=i(async({entry:e,out:r})=>{const t={name:"empty-parser-Doc-plugin",setup(s){s.onResolve({filter:/Doc$/},o=>{if(o.importer.includes("@beforesemicolon/html-parser"))return{path:o.path,namespace:"empty-Doc"}}),s.onLoad({filter:/.*/,namespace:"empty-Doc"},()=>({contents:""}))}};u.default.build({entryPoints:[e??l.default.resolve(process.cwd(),"src/client")],outfile:r??"dist/client.js",bundle:!0,keepNames:!0,sourcemap:!0,target:"esnext",minify:!0,plugins:[t]}).catch(console.error)},"buildBrowser");0&&(module.exports={buildBrowser});
+"use strict";var a=Object.create;var n=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var f=Object.getPrototypeOf,y=Object.prototype.hasOwnProperty;var i=(e,r)=>n(e,"name",{value:r,configurable:!0});var g=(e,r)=>{for(var t in r)n(e,t,{get:r[t],enumerable:!0})},c=(e,r,t,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(let o of d(r))!y.call(e,o)&&o!==t&&n(e,o,{get:()=>r[o],enumerable:!(s=m(r,o))||s.enumerable});return e};var p=(e,r,t)=>(t=e!=null?a(f(e)):{},c(r||!e||!e.__esModule?n(t,"default",{value:e,enumerable:!0}):t,e)),h=e=>c(n({},"__esModule",{value:!0}),e);var D={};g(D,{buildBrowser:()=>B});module.exports=h(D);var l=p(require("path"),1),u=p(require("esbuild"),1);const B=i(async({entry:e,out:r}={})=>{const t={name:"empty-parser-Doc-plugin",setup(s){s.onResolve({filter:/Doc$/},o=>{if(o.importer.includes("@beforesemicolon/html-parser"))return{path:o.path,namespace:"empty-Doc"}}),s.onLoad({filter:/.*/,namespace:"empty-Doc"},()=>({contents:""}))}};u.default.build({entryPoints:[e??l.default.resolve(process.cwd(),"src/client")],outfile:r??"dist/client.js",bundle:!0,keepNames:!0,sourcemap:!0,target:"esnext",minify:!0,plugins:[t]}).catch(console.error)},"buildBrowser");0&&(module.exports={buildBrowser});

package/dist/esm/build-browser.js

@@ -1 +1 @@
-var i=Object.defineProperty;var s=(e,r)=>i(e,"name",{value:r,configurable:!0});import c from"path";import p from"esbuild";const d=s(async({entry:e,out:r})=>{const n={name:"empty-parser-Doc-plugin",setup(t){t.onResolve({filter:/Doc$/},o=>{if(o.importer.includes("@beforesemicolon/html-parser"))return{path:o.path,namespace:"empty-Doc"}}),t.onLoad({filter:/.*/,namespace:"empty-Doc"},()=>({contents:""}))}};p.build({entryPoints:[e??c.resolve(process.cwd(),"src/client")],outfile:r??"dist/client.js",bundle:!0,keepNames:!0,sourcemap:!0,target:"esnext",minify:!0,plugins:[n]}).catch(console.error)},"buildBrowser");export{d as buildBrowser};
+var i=Object.defineProperty;var s=(e,r)=>i(e,"name",{value:r,configurable:!0});import c from"path";import p from"esbuild";const d=s(async({entry:e,out:r}={})=>{const n={name:"empty-parser-Doc-plugin",setup(t){t.onResolve({filter:/Doc$/},o=>{if(o.importer.includes("@beforesemicolon/html-parser"))return{path:o.path,namespace:"empty-Doc"}}),t.onLoad({filter:/.*/,namespace:"empty-Doc"},()=>({contents:""}))}};p.build({entryPoints:[e??c.resolve(process.cwd(),"src/client")],outfile:r??"dist/client.js",bundle:!0,keepNames:!0,sourcemap:!0,target:"esnext",minify:!0,plugins:[n]}).catch(console.error)},"buildBrowser");export{d as buildBrowser};

package/dist/types/build-browser.d.ts

@@ -2,5 +2,5 @@ interface BuildBrowserOptions {
     entry?: string;
     out?: string;
 }
-export declare const buildBrowser: ({ entry, out }: BuildBrowserOptions) => Promise<void>;
+export declare const buildBrowser: ({ entry, out }?: BuildBrowserOptions) => Promise<void>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@beforesemicolon/builder",
-    "version": "1.6.2",
+    "version": "1.6.4",
     "description": "Utilities to build npm packages and documentation website",
     "engines": {
         "node": ">=18.16.0"