kiss-ssg 2.0.0-beta.1 → 2.0.0

package/AIKB/controller-resolver.md

@@ -22,6 +22,7 @@ Resolves `options.controller` (a function, or a filename to load) and runs it ag
 
 - Controller files resolve against `process.cwd()` (via `path.resolve`), consistent with every other folder lookup in the codebase (models, partials, layouts, assets). v1 used `require.main.require` (resolved relative to the entry script) but gated the attempt on a cwd-relative `existsSync` check first — so in v1 a differing cwd already caused the existence check to fail before the entry-relative `require` ever ran, meaning v1's entry-relative resolution never actually worked either; this module's cwd-relative resolution is not a behavior change in practice.
 - `fresh: true` (passed by `lib/kiss.js` only while replaying a watch rebuild) busts _two_ caches, because Node keeps two: the ESM loader caches by resolved URL, so the file URL gets a `?v=<mtimeMs>` query appended; the CommonJS loader caches by _filename_ and never sees that query, so a `module.exports = fn` controller would keep returning the stale export unless `require.cache[require.resolve(path)]` is deleted as well. Both are needed — dropping either one leaves one of the two module systems stale. `require` here comes from `createRequire(import.meta.url)` (this module is ESM, so there is no ambient `require`).
+- A module-level `inFlightFreshLoads` map (`Map<resolvedPath, Promise>`) makes sure only **one** fresh load per controller path is ever in flight; a concurrent `fresh` call for the same path returns the pending promise instead of busting the caches a second time. Two `.page()` registrations naming the same **CommonJS** controller are replayed concurrently on every watch rebuild, and the second call's `delete require.cache[filename]` landed while the first `import()` was still translating the module — Node's translator asserts the entry it just populated is still present, so both pages died on `Error [ERR_INTERNAL_ASSERTION] … at loadCJSModuleWithModuleLoad`. Observed on a real site (two pages sharing `faculty-index.js`), never on a cold build (no `fresh`), and never for an ESM controller (the ESM loader keys on the busted URL, so a second `import()` joins the first job) — but ESM goes through the same map anyway, one code path with no type sniffing. Only _in-flight_ loads are shared: the entry is dropped in a `.finally`, so a `fresh` call made after the previous one settled still re-reads the file, which is the whole point of `fresh`. The non-`fresh` path never touches the map. `test/unit/controller-resolver.test.js` pins both halves, and — because vitest rewrites `import()` inside `lib/` to its own module runner, which never reaches the CJS translator — the reproduction case runs the two concurrent loads in a plain `node` child process, where the assertion was deterministic before the fix. The map is **module-level state shared by every `Kiss` instance in the process**, deliberately: it dedupes identical I/O keyed on an absolute path, so two instances loading the same controller file want the same answer, and Node's own module caches it fronts are process-global anyway. Two residuals are knowingly left open: a **non-`fresh`** `import()` racing a `fresh` one of the same CJS file is still unguarded (only `fresh` calls join the map, so the cache-delete can still land mid-translation of a plain load), and the map key is `path.resolve`, not a realpath — on NTFS a case-variant spelling of the same file (`Faculty-Index.js` vs `faculty-index.js`) takes a second slot and the two loads do not share.
 - Cache-busting keys on `mtimeMs`, so an _unchanged_ controller still hits the ESM cache on replay (no re-evaluation cost per rebuild); only edited files reload. Two rewrites within the same filesystem-timestamp tick would collapse to one URL — not a concern in watch mode, where chokidar's `awaitWriteFinish` already delays a rebuild ~100ms past the last write.
 - Without `fresh` (every non-watch build) behaviour is byte-for-byte unchanged: `import()` caches per resolved URL exactly as `require()` cached per path, so a controller changed mid-process is not re-read. `test/unit/controller-resolver.test.js` pins that cached-by-default behaviour alongside the `fresh` cases.
 - Accepts both `export default fn` and CommonJS-style `module.exports = fn` (`import()` surfaces the latter as `mod.default`), via `mod.default ?? mod`.

package/AIKB/dependency-graph.md

@@ -0,0 +1,31 @@
+# dependency-graph.js
+
+## Responsibility
+
+A pure, per-instance index of which pages rendered which partials, populated as a side effect of rendering and read by `Kiss._handleChange` to decide which pages an edited partial or layout can affect.
+
+## Public interface
+
+- `new DependencyGraph()`
+- `record(page, partial)` — adds the edge both ways; idempotent. `page` is the page's `buildTo`, `partial` its registered name.
+- `clearPage(page)` — removes every edge of that page. A partial it used stays known, possibly with no dependents.
+- `clear()` — forgets everything (a whole-site replay discards the stack, so the graph goes with it).
+- `dependentsOf(partial)` → `string[] | null` — sorted page keys, or **`null` if the partial was never recorded**. `null` and `[]` mean different things to the caller: `null` re-renders every page (the safe fallback), `[]` re-renders none.
+- `usesOf(page)` → `string[]` — sorted partial names that page recorded.
+- `size` — how many partials are known.
+- `toJSON()` → `{ [partial]: pages[] }`, keys and values sorted, so `dependency-graph.json` is stable across builds.
+
+## Depends on
+
+Nothing.
+
+## Depended on by
+
+`lib/kiss.js` (owns one per instance; dispatch and the verbose-dev dump), `lib/partials.js` (records), `lib/kiss-page.js` (clears before render; lists in the debug sibling).
+
+## Non-obvious behavior
+
+- **It is filled by rendering, never by parsing.** A partial is registered as a function that records the invoking page (`lib/partials.js`), so a `{{> (lookup this "name")}}` chosen at render time, a partial reached through another partial, and a layout reached through `{{#extend}}` are all recorded. An inline partial (`{{#*inline}}`) shadows the registered one and records nothing — correct, the page does not depend on the file at that call site.
+- **The page identity travels in Handlebars' data frame**, not in shared state: `KissPage.generate()` renders with `{ data: { kissPage: buildTo } }` and the recording wrapper reads `options.data.kissPage`. Handlebars copies the frame into every nested partial call and handlebars-layouts passes `{ data }` through `extend`/`embed`, so the attribution is correct however many pages render at once or in whatever order. There is no "current page" marker and no ordering invariant.
+- **`null` is the fallback signal.** A partial edited before any page has rendered it (a fresh dev session mid-first-build, a partial only a page that failed would reach) has no record; the dispatcher then re-renders every entry and logs a notice naming the file. A partial whose pages all stopped using it is known with `[]` dependents and re-renders nothing.
+- Keys are `buildTo`, which is stable under `dev: true` (`cleanBuild: 'atomic'` degrades to `true` there, so no staging paths).

package/AIKB/kiss-page.md

@@ -7,7 +7,7 @@ One page's render logic: resolving its title/slug/path/extension, compiling and
 ## Public interface
 
 - `class KissPage`
-  - `new KissPage(view, { hbs, logger } = {})` — `view` is a `.hbs` path (relative to `pagesDir`) or an inline template string.
+  - `new KissPage(view, { hbs, logger, graph } = {})` — `view` is a `.hbs` path (relative to `pagesDir`) or an inline template string. `graph` is an optional `DependencyGraph` (`./dependency-graph.js`); without one the render is unchanged.
   - `set path(path)` — sanitizes via `sanitizePath` (`./utils.js`); falsy values are ignored (default `''` kept).
   - `set slug(slug)` / `get slug()` — setter normalizes via `toSlug` (`./utils.js`); falsy values are ignored (default `'index'` kept).
   - `set ext(extension)` — strips a leading `.`, then slugifies via `toSlug` (`./utils.js`), like `path` and `slug`; falsy values are ignored (default `'html'` kept).
@@ -22,7 +22,7 @@ One page's render logic: resolving its title/slug/path/extension, compiling and
 
 ## Depends on
 
-`fs-extra`, `node:path`, `html-minifier-terser` (dynamic `import()`, never at module load); `./utils.js` (`toSlug`, `toTitleCase`, `sanitizePath`), `./logger.js` (fallback logger only), `./config.js` (`DEFAULT_CONFIG.livereloadPort`, the fallback for a `KissPage` built outside `Kiss`).
+`fs-extra`, `node:path`, `html-minifier-terser` (dynamic `import()`, never at module load); `./utils.js` (`toSlug`, `toTitleCase`, `sanitizePath`), `./logger.js` (fallback logger only), `./config.js` (`DEFAULT_CONFIG.livereloadPort`, the fallback for a `KissPage` built outside `Kiss`). The dependency graph arrives as `deps.graph` (`AIKB/dependency-graph.md`) and is referenced only by a type-only `import('./dependency-graph.js')` in the JSDoc — there is no runtime import of that module here.
 
 ## Depended on by
 
@@ -30,6 +30,8 @@ One page's render logic: resolving its title/slug/path/extension, compiling and
 
 ## Non-obvious behavior
 
+- **The render carries the page's identity in Handlebars' data frame**: `template(this.options, { data: { kissPage: this.buildTo } })`. Handlebars copies the frame into every nested partial invocation and handlebars-layouts passes `{ data }` through `extend`/`embed`, so a recording partial (`AIKB/partials.md`) reads `options.data.kissPage` and attributes itself to the right page whatever the render order — there is no "current page" variable and no assumption that pages render one at a time. Before rendering, the page calls `graph.clearPage(buildTo)` so its edge set is exactly what this render reached. `graph` is optional (`deps.graph`); without it the render is byte-identical to before — the extra `data` only adds a key to a frame Handlebars creates anyway.
+- In dev mode the `.json` sibling gains `partials`: the names this page recorded, from `graph.usesOf(buildTo)` — the per-page view of `dependency-graph.json`.
 - `_title` is computed from the _default_ slug (`'index'`) in the constructor, before any page-specific slug is set — so a page without an explicit title or model title falls back to `'Index'`, not a title derived from its own slug. This is a preserved v1 quirk, not a bug to fix.
 - `buildTo` is the value `Kiss._preparePage` uses to detect duplicate pages (same output path) — a duplicate is a build failure there, not a skip.
 - **Every part of `buildTo` is sanitised, `ext` included.** `ext` used to strip only the _first_ `.` (`replace('.', '')`) and never slugify, so unlike `path` (`sanitizePath`) and `slug` (`toSlug`) it carried `/` and `..` straight into the output path: `ext: './../../../escaped/pwned.html'` wrote three levels above the build folder, and the value is reachable from model data through the documented "controller derives the page's options" pattern (review finding C1). It now goes through `toSlug(extension.replace(/^\./, ''))` — `'.xml'` → `'xml'`, `'../x'` → `'x'`.