@apleasantview/eleventy-plugin-baseline 0.1.0-next.39 → 0.1.0-next.40

package/core/logging.js

@@ -1,5 +1,36 @@
 import chalk from 'kleur';
 
+/**
+ * Logger (runtime substrate)
+ *
+ * Namespaced console logger used across the plugin. One factory, three
+ * levels: `info` (verbose-gated), `warn`, `error`. The composition root
+ * holds an unscoped logger; modules receive a scoped one through the
+ * module context.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Single output surface for plugin diagnostics. Every module writes
+ *   through it so prefixes, colours, and verbosity behave identically.
+ *
+ * Lifecycle:
+ *   build-time → loggers created at plugin init and per-module activation
+ *
+ * Why this exists:
+ *   Eleventy gives no opinionated logging primitive. A shared factory
+ *   keeps every prefix consistent and lets one `verbose` switch silence
+ *   info-level chatter without affecting warnings or errors.
+ *
+ * Scope:
+ *   Owns the prefix format, colour treatment, and verbosity gate. Does
+ *   not own message content or what each module chooses to log.
+ *
+ * Data flow:
+ *   namespace + verbose → logger triple → console
+ */
+
 /**
  * @typedef {Object} BaselineLogger
  * @property {(...args: unknown[]) => void} info   Verbose-only.

package/core/schema.js

@@ -1,5 +1,38 @@
 import * as z from 'zod';
 
+/**
+ * Schemas (runtime substrate)
+ *
+ * Zod schemas for the two user-facing inputs Baseline validates: the
+ * directory `config` export and the `settings` argument. Structural only.
+ * Value-level preferences stay permissive.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Validation seam at the public boundary. The composition root parses
+ *   `settings` non-fatally at init; the directory `config` is checked in
+ *   the test suite, not at runtime.
+ *
+ * Lifecycle:
+ *   build-time → composition root calls `settingsSchema.safeParse(settings)`
+ *                and logs structural mismatches under `info`
+ *
+ * Why this exists:
+ *   Eleventy accepts almost anything users pass through `addPlugin`. A
+ *   structural gate catches typos and shape drift early without forcing
+ *   a hard failure on imperfect input.
+ *
+ * Scope:
+ *   Owns the structural shape of `settings` and `config`. Does not own
+ *   defaults, value semantics, or required-field policy; those live in
+ *   the composition root and individual modules.
+ *
+ * Data flow:
+ *   user input → safeParse → issues logged or accepted
+ */
+
 export const configSchema = z.object({
 	dir: z.object({
 		input: z.string().min(1),

package/core/types.js

@@ -43,7 +43,7 @@
  * Head module options.
  *
  * @property {{ esbuild?: { minify?: boolean, target?: string } }} [assets]
- * Assets module options. The esbuild slice is permissive — any esbuild
+ * Assets module options. The esbuild slice is permissive: any esbuild
  * option is accepted; only `minify` and `target` are typed.
  */
 

package/core/wikilinks.js

@@ -1,7 +1,7 @@
 import { slugify } from './utils/helpers.js';
 
 /**
- * WIKILINKS (filter)
+ * Wikilinks (runtime substrate)
  *
  * MediaWiki-style inline link syntax for body markdown. Recognises
  * [[slug]], [[slug#anchor]], [[slug:lang]], [[slug|alias]], and any
@@ -24,8 +24,8 @@ import { slugify } from './utils/helpers.js';
  * Why this exists:
  *   Markdown-it has no wiki-link syntax. Eleventy resolves all
  *   eleventyComputed values before any body renders, so the slug index
- *   and translation map are complete by the time this rule fires —
- *   resolution is deterministic without a two-pass build.
+ *   and translation map are complete by the time this rule fires.
+ *   Resolution is deterministic without a two-pass build.
  *
  * Scope:
  *   Owns syntax parsing, slug-to-href resolution, the lang hop, and link

package/modules/assets/processors/esbuild-process.js

@@ -1,6 +1,39 @@
 import * as esbuild from 'esbuild';
 import { createLogger } from '../../../core/logging.js';
 
+/**
+ * esbuild processor (processor)
+ *
+ * Bundles a single JS entrypoint with esbuild and returns the text. Used
+ * both by the `js` template format compile guard and by the
+ * `inlineESbuild` filter in the assets module.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Stateless bundler called by `modules/assets/index.js`. The compile
+ *   guard decides which files reach this processor; this file owns the
+ *   esbuild call itself.
+ *
+ * Lifecycle:
+ *   build-time → invoked per matching entrypoint during template compile,
+ *                or per-call from the inline filter
+ *
+ * Why this exists:
+ *   Eleventy treats every `.js` file as a template. A dedicated processor
+ *   keeps esbuild configuration out of the template format wiring and lets
+ *   the inline filter reuse the same defaults.
+ *
+ * Scope:
+ *   Owns esbuild option defaults and the bundle call. Does not own the
+ *   compile guard, the watch target, or markup wrapping; the assets
+ *   module owns those.
+ *
+ * Data flow:
+ *   entrypoint path + options → esbuild.build → bundled JS text
+ */
+
 const log = createLogger('assets-esbuild');
 const defaultOptions = { minify: true, target: 'es2020' };
 

package/modules/assets/processors/postcss-process.js

@@ -4,6 +4,40 @@ import loadPostCSSConfig from 'postcss-load-config';
 import fallbackPostCSSConfig from '../configs/postcss.config.js';
 import { createLogger } from '../../../core/logging.js';
 
+/**
+ * PostCSS processor (processor)
+ *
+ * Processes a single CSS entrypoint through PostCSS and returns the text.
+ * Used both by the `css` template format compile guard and by the
+ * `inlinePostCSS` filter in the assets module.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Stateless processor called by `modules/assets/index.js`. Resolves the
+ *   user's PostCSS config from the project root, falling back to the
+ *   bundled Baseline config when none is found. Cached for the lifetime
+ *   of the process.
+ *
+ * Lifecycle:
+ *   build-time → invoked per matching entrypoint during template compile,
+ *                or per-call from the inline filter
+ *
+ * Why this exists:
+ *   Eleventy has no PostCSS hook of its own. A dedicated processor lets
+ *   user configs win when present and keeps the bundled fallback out of
+ *   the consumer's `node_modules` resolution path.
+ *
+ * Scope:
+ *   Owns config resolution, caching, and the PostCSS call. Does not own
+ *   the compile guard, the watch target, or markup wrapping; the assets
+ *   module owns those.
+ *
+ * Data flow:
+ *   entrypoint path → PostCSS pipeline → processed CSS text
+ */
+
 const log = createLogger('assets-postcss');
 
 // Resolve user PostCSS config from the project root (cwd), not the Eleventy input dir.

package/modules/head/drivers/capo-adapter.js

@@ -1,9 +1,31 @@
 /**
- * capo.js adapter for PostHTML AST nodes.
+ * Capo PostHTML adapter (driver)
  *
- * Implements the HTMLAdapter interface capo.js v2 uses to compute element
- * weights (src/adapters/adapter.js in @rviscomi/capo.js). Only getWeight is
- * consumed downstream; the rest are shimmed to satisfy the shape.
+ * Implements the `HTMLAdapter` interface capo.js v2 expects, against
+ * PostHTML's `{ tag, attrs, content }` node shape. Only `getWeight` is
+ * exercised downstream; the rest are shimmed to satisfy the contract.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Translation shim between the head driver's PostHTML tree and the
+ *   capo.js sort. Used by `posthtml-head-elements.js` when ordering the
+ *   composed `<head>` element list.
+ *
+ * Lifecycle:
+ *   transform-time → invoked per node while capo.js scores element weights
+ *
+ * Why this exists:
+ *   capo.js is DOM-shaped; PostHTML is not. Without an adapter the driver
+ *   would have to walk the tree twice or hand-roll element weighting.
+ *
+ * Scope:
+ *   Owns attribute lookup, tag name resolution, and text extraction over
+ *   PostHTML nodes. Does not own weighting logic; capo.js owns that.
+ *
+ * Data flow:
+ *   PostHTML node → adapter accessor → capo.js getWeight
  *
  * A PostHTML element node looks like `{ tag, attrs, content }` where attrs
  * is either undefined or a plain object. Boolean attributes appear with an

package/modules/head/drivers/posthtml-head-elements.js

@@ -10,7 +10,7 @@ import { dedupeMeta, dedupeLink } from '../utils/dedupe.js';
  * <baseline-head> placeholder with the result.
  *
  * Architecture layer:
- *   module (driver inside head)
+ *   module
  *
  * System role:
  *   The seam between head's pipeline and the renderer choice. Alternate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apleasantview/eleventy-plugin-baseline",
-  "version": "0.1.0-next.39",
+  "version": "0.1.0-next.40",
   "description": "An experimental Swiss army knife toolkit for Eleventy",
   "type": "module",
   "exports": {