@rathnasgala2/template 2.0.0 → 2.1.0

package/src/core/internal/page-kinds.js

@@ -1,19 +1,18 @@
 /**
- * Page-kind assembly (task packet S2-T06): builds every generated page's
+ * Page-kind assembly: builds every generated page's
  * `<main>` content, breadcrumb trail and route from a validated
  * `build-input:2.0.0` instance, and the shared site chrome (header, primary
  * navigation, footer) every page kind is composed with through
  * `internal/skeleton.js`'s {@link import('./skeleton.js').renderPageBody}.
  *
- * Page kinds this module produces, matching brief S2 section 3's "Required
- * generated outputs" and task packet S2-T06's page-kind list:
+ * Page kinds this module produces:
  *
  * - `profile` — the publication's own optional profile page
  *   (`publication.profile`);
- * - `author` — one page per entry in `build-input.authors` (DEC-097 section 5:
- *   this array is already exactly the set of authors referenced by the
- *   selected content, publication contact or footer card — never an
- *   unreferenced author), at `/authors/<id>`;
+ * - `author` — one page per entry in `build-input.authors` (this array is
+ *   already exactly the set of authors referenced by the selected content,
+ *   publication contact or footer card — never an unreferenced author), at
+ *   `/authors/<id>`;
  * - `article` / `page` — one page per `content[]` record, at its own
  *   `contentFrontmatterNormalized` route;
  * - `index` — a paginated reverse-chronological listing of every
@@ -27,10 +26,10 @@
  *   plus one `/archive` root page linking to each year.
  *
  * The `error` page kind ({@link renderErrorPageBody}) is exported as a pure
- * function, not wired into any generated route here: brief S2 section 3
- * assigns the one generated `404.html` artifact to S2-T08, which this task
- * packet's own scope notes forbid touching. S2-T08 composes its `404.html`
- * from this same function.
+ * function, not wired into any generated route here: the one generated
+ * `404.html` artifact is assembled elsewhere, which this module's own scope
+ * notes forbid touching. That module composes its `404.html` from this same
+ * function.
  *
  * Every generated page's own `route` field (see {@link GeneratedPage}) is an
  * un-joined `canonicalRoute`, in the same convention `internal/index.js`
@@ -39,16 +38,18 @@
  * *link href* this module writes into a page's own body (breadcrumbs, tag and
  * series listings, pagination controls) is, by contrast, already joined with
  * `basePath` here, because it is read back only as literal HTML text, never
- * re-joined by a caller. This mirrors DEC-097 section 5's navigation
- * normalization rule: an *authored* navigation item's route is used exactly
- * as authored, never synthesized or rewritten (so `internal/skeleton.js`'s
- * navigation renderer never joins it), while every route this renderer itself
- * derives (every page kind here) is basePath-joined at the point it becomes
- * link text, exactly like S2-T03's own redirect/content route projection.
+ * re-joined by a caller. This mirrors the navigation normalization rule: an
+ * *authored* navigation item's route is used exactly as authored, never
+ * synthesized or rewritten (so `internal/skeleton.js`'s navigation renderer
+ * never joins it), while every route this renderer itself derives (every
+ * page kind here) is basePath-joined at the point it becomes link text,
+ * exactly like the redirect/content route projection elsewhere in this
+ * renderer.
  *
  * Every listing here is a deliberately scoped decision this module documents
  * rather than assumes: page size, sort tie-break and the tag/series/archive
- * root pages are not specified verbatim by the brief text this task read.
+ * root pages have no externally fixed specification this renderer conforms
+ * to verbatim.
  */
 
 import {
@@ -63,22 +64,20 @@ import { routeSegmentForLabel } from './route-labels.js';
 import { joinBasePathAndRoute } from './route.js';
 
 /** Listing page size (index and per-year archive pages). Scoped decision:
- * the brief does not fix a page size; 10 is a deterministic, documented
- * default with no author-facing configuration surface in S2.
+ * this renderer has no externally fixed page size; 10 is a deterministic,
+ * documented default with no author-facing configuration surface.
  * @type {number} */
 export const LISTING_PAGE_SIZE = 10;
 
 /**
- * The DEC-097-style semantic template-owned attribute this renderer sets on
- * every generated page's `<body>` (S2-T12: `contracts/theme-styling-contract.jcs`
- * exposes this as a public theme hook, one per {@link PAGE_KIND_VALUES}
- * entry, so a theme can vary presentation by page kind — e.g. a different
- * article vs. listing background — without the template ever promoting a
- * private/incidental selector). Scoped decision: this attribute did not
- * exist before S2-T12; it is this task packet's own addition, introduced
- * specifically because the published styling contract needs a
- * page-kind-targeting hook the brief's "every page-kind ... class/attribute"
- * language calls for.
+ * The semantic template-owned attribute this renderer sets on every
+ * generated page's `<body>`: `contracts/theme-styling-contract.jcs` exposes
+ * this as a public theme hook, one per {@link PAGE_KIND_VALUES} entry, so a
+ * theme can vary presentation by page kind — e.g. a different article vs.
+ * listing background — without the template ever promoting a
+ * private/incidental selector. This attribute is a deliberate addition,
+ * introduced specifically because the published styling contract needs a
+ * page-kind-targeting hook.
  *
  * @type {string}
  */
@@ -87,8 +86,8 @@ export const PAGE_KIND_ATTRIBUTE = 'data-gala-page-kind';
 /**
  * Every value {@link PAGE_KIND_ATTRIBUTE} may carry: every {@link GeneratedPage}
  * `kind` plus the synthetic `error` kind (`internal/index.js`'s always-present
- * generated `404.html`), sorted by UTF-8 bytes (DEC-097's own attribute-value
- * sort convention).
+ * generated `404.html`), sorted by UTF-8 bytes (this renderer's own
+ * attribute-value sort convention throughout).
  *
  * @type {readonly string[]}
  */
@@ -135,8 +134,8 @@ function paginate(items, pageSize) {
 
 /**
  * Resolve an author's display name by ID, failing closed on a dangling
- * reference (an adapter defect: `resolvedAuthorIds` is schema/DEC-097
- * guaranteed to resolve).
+ * reference (an adapter defect: `resolvedAuthorIds` is schema-guaranteed to
+ * resolve).
  *
  * @param {ReadonlyMap<string, import('../../../types/index.d.ts').AuthorNormalized>} authorsById
  * @param {string} authorId
@@ -161,30 +160,29 @@ function requireAuthor(authorsById, authorId) {
  * @property {string} bodyHtml the page's complete `<main>` inner HTML,
  *   starting with exactly one `<h1>`
  * @property {string} [breadcrumbHtml] an optional already-rendered breadcrumb
- * @property {string} [description] task packet S2-T08: an optional plain-text
+ * @property {string} [description] an optional plain-text
  *   description this page's SEO/Open-Graph/Twitter `<meta>` tags are built
  *   from (never HTML, never the sanitized body — a distinct authored or
  *   publication-level plain-text field)
- * @property {'website' | 'article' | 'profile'} [ogType] task packet S2-T08:
+ * @property {'website' | 'article' | 'profile'} [ogType]
  *   the Open Graph `og:type` this page kind maps to; defaults to `'website'`
  *   when omitted
  * @property {{path: string, sourceDigest: string} | undefined} [socialImageRef]
- *   task packet S2-T08: an optional `resolvedFile` reference this page's
+ *   an optional `resolvedFile` reference this page's
  *   social image is resolved from (the caller, `src/core/index.js`, is the
  *   one place that can turn this into an absolute derivative URL, because
- *   only it has run the S2-T05 media pipeline and knows the derivative
+ *   only it has run the media pipeline and knows the derivative
  *   output path a given `sourceDigest` produced)
- * @property {string} [robotsContent] task packet S2-T08: an optional
+ * @property {string} [robotsContent] an optional
  *   `<meta name="robots">` content value (e.g. `'noindex, follow'` for
  *   `status: "unlisted"` content); omitted entirely for ordinarily indexable
  *   pages, matching this renderer's "documented, not silently assumed" style
  *   elsewhere — every page kind's robots decision is made once, here, rather
  *   than re-derived by every later consumer (sitemap, search index)
- * @property {string} [lastModified] task packet S2-T08: an optional
+ * @property {string} [lastModified] an optional
  *   `rfc3339` timestamp the generated sitemap's `<lastmod>` for this page is
  *   drawn from — always derived from authored content timestamps
- *   (`publishedAt`/`updatedAt`), never build time (brief S2 section 3:
- *   "sitemap ... `lastmod` from content timestamps not build time"). Omitted
+ *   (`publishedAt`/`updatedAt`), never build time. Omitted
  *   for a page kind with no natural underlying timestamp (`profile`,
  *   `author`), which the generated sitemap then emits with no `<lastmod>`
  *   element at all (a sitemap's own `<lastmod>` is optional per the Sitemaps
@@ -194,7 +192,7 @@ function requireAuthor(authorsById, authorId) {
 /**
  * The reverse-chronological, deterministically tie-broken set of every
  * `status: "published"`, `kind: "article"` record — the exact selection and
- * ordering the `index` page kind paginates, and (task packet S2-T08) the
+ * ordering the `index` page kind paginates, and the
  * same selection the generated feeds draw from, so a feed's item order can
  * never drift from the index listing's own order. Extracted to its own
  * export rather than duplicated, since `internal/fs-walk.js`'s duplication
@@ -224,7 +222,7 @@ export function selectPublishedArticles(content) {
 /**
  * The most recent of a content record's own `updatedAt` (when authored) or
  * `publishedAt` — this renderer's one definition of "a content record's own
- * last-modified instant" (task packet S2-T08's sitemap `<lastmod>` and the
+ * last-modified instant" (the sitemap's `<lastmod>` and the
  * static search index both read this, rather than each re-deriving it).
  *
  * @param {import('../../../types/index.d.ts').ContentFrontmatterNormalized} frontmatter
@@ -237,7 +235,7 @@ export function contentLastModified(frontmatter) {
 /**
  * The latest {@link contentLastModified} across a non-empty set of records —
  * this renderer's definition of "a generated listing page's own
- * `<lastmod>`" (task packet S2-T08): the most recent authored timestamp
+ * `<lastmod>`": the most recent authored timestamp
  * among the content actually shown on that page, never build time.
  *
  * @param {readonly import('../../../types/index.d.ts').ContentBuildRecord[]} records
@@ -682,10 +680,10 @@ export function buildGeneratedPages(validatedInput) {
 }
 
 /**
- * Render the `error` page kind's `<main>` body (task packet S2-T06). This is
+ * Render the `error` page kind's `<main>` body. This is
  * a pure function with no route/build-input dependency, exported for a
- * future caller (S2-T08's generated `404.html`, out of this task packet's
- * scope) and for this repository's own structural/golden tests.
+ * caller elsewhere (the generated `404.html`, assembled outside this module)
+ * and for this repository's own structural/golden tests.
  *
  * @param {object} options rendering options
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages

package/src/core/internal/render-policy-content.js

@@ -1,7 +1,7 @@
 /**
- * The single source of truth for `contracts/render-policy.jcs`'s content
- * (brief S2 section 3 "Markdown, sanitizer, highlighter" and "Per-artifact
- * CSP baseline"; DEC-097 section 5 `renderPolicyIdentity`).
+ * The single source of truth for `contracts/render-policy.jcs`'s content:
+ * the markdown, sanitizer, highlighter and per-artifact CSP baseline, and
+ * the `renderPolicyIdentity` derived from them.
  *
  * `scripts/generate-contracts.mjs` emits this exact document as compact JCS
  * to `contracts/render-policy.jcs`; `src/core/internal/content-security.js`
@@ -17,9 +17,9 @@
 export const RENDER_POLICY_NAME = 'gala-render-policy';
 
 /**
- * Byte-equal to the template lock's `contractVersion` (DEC-097 section 5),
- * which every S2 `build-input:2.0.0` fixture carries as the literal string
- * `"2.0.0"` (matches `manifest.js`'s `buildInputContractVersion`).
+ * Byte-equal to the template lock's `contractVersion`, which every
+ * `build-input:2.0.0` fixture in this repository carries as the literal
+ * string `"2.0.0"` (matches `manifest.js`'s `buildInputContractVersion`).
  *
  * @type {string}
  */
@@ -31,7 +31,7 @@ export const MARKDOWN_IT_PACKAGE = 'markdown-it';
 export const MARKDOWN_IT_VERSION = '14.3.1';
 
 /**
- * The exact markdown-it construction options brief S2 section 3 requires.
+ * The exact markdown-it construction options this renderer requires.
  *
  * @type {{html: false, linkify: false, typographer: false}}
  */
@@ -56,7 +56,7 @@ export const ALLOWED_URL_SCHEMES = Object.freeze(['https', 'http', 'mailto']);
 
 /**
  * The closed allowlist of tags this renderer ever emits from author
- * markdown: "semantic text and content tags" only (brief S2 section 3).
+ * markdown: semantic text and content tags only.
  * No form, frame, SVG, MathML, script, style, object or template element is
  * ever admitted.
  *
@@ -110,8 +110,7 @@ export const ALLOWED_TAGS = Object.freeze([
 /**
  * The closed per-tag attribute allowlist. `id` is admitted only on headings
  * (this renderer's own generated heading IDs); `style`, every `on*` handler,
- * `srcdoc` and every other undeclared attribute is always stripped (brief S2
- * section 3).
+ * `srcdoc` and every other undeclared attribute is always stripped.
  *
  * @type {Readonly<Record<string, readonly string[]>>}
  */
@@ -138,7 +137,7 @@ export const HIGHLIGHTER_VERSION = '5.0.2';
 /**
  * The closed grammar-name catalog the owned highlighter accepts. A fence
  * language outside this list always falls back to escaped, unhighlighted
- * code (brief S2 section 3).
+ * code.
  *
  * @type {readonly string[]}
  */
@@ -167,8 +166,8 @@ export const HIGHLIGHT_GRAMMARS = Object.freeze(
  * can produce (Prism's documented generic token set plus this
  * repository's own empirical sample across every admitted grammar). `token`
  * itself is always the base class; every other admitted value is a
- * secondary token-class (brief S2 section 3: "`span` elements carrying
- * `token` and admitted token-class values").
+ * secondary token-class: `span` elements carry `token` plus admitted
+ * token-class values.
  *
  * @type {readonly string[]}
  */
@@ -241,15 +240,51 @@ export const ADMITTED_LANGUAGE_CLASSES = Object.freeze(
 );
 
 /**
- * The exact per-artifact CSP baseline (brief S2 section 3). Directive order
- * is byte-exact as written in the brief; every directive's value list is
- * already sorted bytewise and duplicate-free because S2 materializes no
- * module package, configuration, output or runtime, so this string is
+ * The CSP specification explicitly ignores `frame-ancestors`
+ * (and `report-uri`/`sandbox`, neither used here) when a policy is
+ * delivered via `<meta http-equiv>` — browsers drop the directive and log a
+ * console warning on every page load. `frame-ancestors` is therefore
+ * split out as the one header-only directive: clickjacking protection for a
+ * published artifact is a hosting-layer obligation (a response header, most
+ * commonly `Content-Security-Policy` or `X-Frame-Options`), recorded here so
+ * every consuming adapter/deployment knows to add it, rather than a directive
+ * that silently does nothing inside the `<meta>` tag every page already
+ * carries.
+ *
+ * @type {readonly string[]}
+ */
+export const CSP_HEADER_ONLY_DIRECTIVES = Object.freeze([
+  "frame-ancestors 'none'",
+]);
+
+/**
+ * The exact per-artifact CSP baseline actually deliverable inside a
+ * `<meta http-equiv="Content-Security-Policy">` tag: {@link CSP_HEADER_ONLY_DIRECTIVES}
+ * is excluded. Directive order is byte-exact, minus
+ * the excluded directive; every directive's value list is already sorted
+ * bytewise and duplicate-free because this renderer materializes no module
+ * package, configuration, output or runtime, so this string is
  * byte-identical on every route.
  *
  * @type {string}
  */
-export const CONTENT_SECURITY_POLICY_BASELINE =
+export const CONTENT_SECURITY_POLICY_META_BASELINE =
+  "default-src 'none'; base-uri 'none'; object-src 'none'; " +
+  "form-action 'none'; script-src 'self'; " +
+  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; " +
+  "media-src 'self'; manifest-src 'self'; worker-src 'none'";
+
+/**
+ * The complete CSP baseline this renderer originally specified as one
+ * string — the meta-safe directives plus the header-only directive, in
+ * this fixed byte-exact order — kept only as the render-policy identity's own
+ * digest input (`renderPolicyDocument`'s `contentSecurityPolicy` field): a
+ * hosting adapter that delivers this policy as a response header, rather
+ * than a `<meta>` tag, may deliver this complete string unmodified.
+ *
+ * @type {string}
+ */
+export const CONTENT_SECURITY_POLICY_COMPLETE =
   "default-src 'none'; base-uri 'none'; object-src 'none'; " +
   "frame-ancestors 'none'; form-action 'none'; script-src 'self'; " +
   "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; " +
@@ -258,8 +293,7 @@ export const CONTENT_SECURITY_POLICY_BASELINE =
 /**
  * Build the exact plain-object document `contracts/render-policy.jcs`
  * publishes: `name`, `version` byte-equal to the template lock's
- * `contractVersion`, a closed sanitizer/parser catalog, and no self-digest
- * (DEC-097 section 5).
+ * `contractVersion`, a closed sanitizer/parser catalog, and no self-digest.
  *
  * @returns {Record<string, unknown>} the render-policy document
  */
@@ -267,7 +301,9 @@ export function renderPolicyDocument() {
   return {
     name: RENDER_POLICY_NAME,
     version: RENDER_POLICY_VERSION,
-    contentSecurityPolicy: CONTENT_SECURITY_POLICY_BASELINE,
+    contentSecurityPolicy: CONTENT_SECURITY_POLICY_COMPLETE,
+    contentSecurityPolicyMeta: CONTENT_SECURITY_POLICY_META_BASELINE,
+    contentSecurityPolicyHeaderOnlyDirectives: [...CSP_HEADER_ONLY_DIRECTIVES],
     markdownIt: {
       package: MARKDOWN_IT_PACKAGE,
       version: MARKDOWN_IT_VERSION,

package/src/core/internal/route-labels.js

@@ -1,7 +1,6 @@
 /**
  * Deterministic route-segment derivation for generated listing pages (tag,
- * series, archive) from an authored `plainLabel` (task packet S2-T06:
- * navigation renderer/page kinds).
+ * series, archive) from an authored `plainLabel`.
  *
  * `contentFrontmatterNormalized.tags`/`.series` are `plainLabel` values:
  * normalized Unicode text, 1..80 graphemes, with no further route-safety
@@ -12,12 +11,12 @@
  * or series label can therefore contain spaces, uppercase letters, or any
  * non-Latin script.
  *
- * `route.js` already documents that this renderer's route projection is
- * deliberately not DEC-097 section 8's full Unicode-17 percent-encoding and
+ * `route.js` already documents that this renderer's route projection
+ * deliberately excludes a full Unicode percent-encoding and
  * collision-resolution engine (out of scope; it only ever projects
  * already-schema-validated `canonicalRoute` values, never derives a route
- * from an arbitrary label). This module makes the same scoped choice for the
- * one new case S2-T06 introduces — turning an arbitrary label into a route
+ * from an arbitrary label). This module makes the same scoped choice for
+ * the one new case it introduces — turning an arbitrary label into a route
  * segment — and closes the collision risk a lossy ASCII-only slug would
  * otherwise introduce (two distinct Unicode labels both losing all their
  * characters to filtering) by always appending a short, deterministic content

package/src/core/internal/route.js

@@ -1,16 +1,14 @@
 /**
  * Route-to-output-path projection and the byte-exact generated redirect
- * document (brief S2 section 3 "Required generated outputs"; DEC-097
- * section 6 artifact-manifest redirect subsection).
+ * document.
  *
  * This module implements the `directory-index` and `explicit-file` cases of
- * DEC-097 section 7's `gala-portable-v2` route projection only for routes
- * that are already valid `canonicalRoute` strings (schema-enforced before
- * this module ever runs). The full Unicode-17 percent-encoding/collision
- * engine DEC-097 section 8 describes is out of S2-T03's scope: it governs
- * arbitrary repository-relative source paths, which this renderer never
- * derives routes from (every route it projects comes from an
- * already-schema-validated `canonicalRoute` field in `build-input`).
+ * route projection only for routes that are already valid `canonicalRoute`
+ * strings (schema-enforced before this module ever runs). A full Unicode
+ * percent-encoding/collision engine for arbitrary repository-relative
+ * source paths is out of scope here: this renderer never derives routes
+ * from source paths — every route it projects comes from an
+ * already-schema-validated `canonicalRoute` field in `build-input`.
  */
 
 /**
@@ -75,16 +73,14 @@ export function projectFilePathToRoute(filePath, profile) {
 }
 
 /**
- * Project a `basePath` to the one fixed generated error-document output path
- * DEC-097's Spaces website-configuration subsection defines: `errorDocumentKey`
- * is exactly `404.html` when `basePath` is `/`; otherwise the base path with
- * its one leading and terminal slash removed, followed by `/404.html`. This
- * is deliberately independent of the selected `RouteNormalizationProfile`
- * (`directory-index` vs `explicit-file`): the generated error document is
- * always this one literal filename, never route-normalized like an ordinary
- * content route (brief S2 section 3: "one ordinary generated `404.html` at
- * the selected base path"; DEC-097's Spaces/Pages/local-directory adapters
- * all bind their provider error-document configuration to this exact key).
+ * Project a `basePath` to the one fixed generated error-document output
+ * path: exactly `404.html` when `basePath` is `/`; otherwise the base path
+ * with its one leading and terminal slash removed, followed by
+ * `/404.html`. This is deliberately independent of the selected
+ * `RouteNormalizationProfile` (`directory-index` vs `explicit-file`): the
+ * generated error document is always this one literal filename, never
+ * route-normalized like an ordinary content route — this fixed key is what
+ * each hosting adapter's provider error-document configuration binds to.
  *
  * @param {string} basePath the build input's `basePath` (`canonicalRoute`,
  *   always starts with `/`)
@@ -143,7 +139,7 @@ export function escapeRedirectTarget(targetRoute) {
 
 /**
  * Render the exact UTF-8, no-BOM, LF-terminated generated redirect document
- * DEC-097 section 6 and brief S2 section 3 specify byte-for-byte.
+ * this renderer must produce byte-for-byte.
  *
  * @param {string} targetRoute the route this redirect document points to
  * @returns {string} the complete document text

package/src/core/internal/search-index.js

@@ -1,12 +1,10 @@
 /**
- * Static search index generation (task packet S2-T08; brief S2 section 3
- * "Required generated outputs": "static search index").
+ * Static search index generation.
  *
- * Scope note (documented, not silently assumed): neither the brief text this
- * task read nor DEC-097 fixes an exact search-index document shape (checked
- * with a full-text grep of both for "search" — no hit beyond this brief
- * phrase). This module therefore documents its own deterministic shape here,
- * matching this renderer's established style for an unfixed structural
+ * Scope note (documented, not silently assumed): this renderer has no
+ * externally fixed search-index document shape to conform to. This module
+ * therefore documents its own deterministic shape here, matching this
+ * renderer's established style for an unfixed structural
  * decision (see `internal/route-labels.js`'s route-segment grammar and the
  * media pipeline scope decisions in the package README): one JSON document,
  * `{schemaVersion, generatedAt, publication, documents[]}`, sorted by each
@@ -15,17 +13,17 @@
  * `internal/source-inventory.js#compareUtf8Bytes`).
  *
  * `generatedAt` is `buildInput.buildEpoch` — a build-input *field*, sourced
- * deterministically from the selected Git commit's own committer timestamp
- * (DEC-097 section 5), not read from the wall clock at build time — matching
+ * deterministically from the selected Git commit's own committer timestamp,
+ * not read from the wall clock at build time — matching
  * `src/core/manifest.js`'s own `manifest.generatedAt` convention, so two
  * clean builds of the same `build-input` still produce byte-identical index
  * bytes.
  *
- * No runtime search JavaScript accompanies this document (brief S2 section
- * 1: "reads completely with JavaScript disabled"; acceptance test C: "the
- * appearance controller is the only browser bootstrap" — this renderer's one
- * admitted client-side script in all of S2). This module's only output is
- * the index document's bytes; nothing wires a `<script>` to it.
+ * No runtime search JavaScript accompanies this document: this renderer
+ * must read completely with JavaScript disabled, and the appearance
+ * controller is the only client-side script it ever admits. This module's
+ * only output is the index document's bytes; nothing wires a `<script>` to
+ * it.
  *
  * Only actual authored content (`article`/`page` records, `status:
  * "published"`) is indexed — never a synthetic listing page

package/src/core/internal/semver-range.js

@@ -0,0 +1,84 @@
+/**
+ * A closed subset of npm-compatible SemVer range satisfaction (TPL-H1), used
+ * only to check a theme package's own declared `theme.json.templateRange`
+ * against this renderer's published version. This is deliberately not a
+ * general-purpose SemVer range engine: `@rathnasgala2/schemas`'
+ * `theme-contract.schema.json` `templateRange` field (`$defs/semverRange`)
+ * admits an open-ended npm range grammar, but every legitimate value this
+ * closed-contract ecosystem actually emits is either an exact version or a
+ * caret range — the same two forms `package.json` dependency pins in this
+ * very repository use — so this module supports exactly those two forms and
+ * fails closed (rejects) on anything else, exactly like every other closed
+ * catalog in this repository (`nthExpressionProfile`, the pseudo-class
+ * catalog, `functionalSelectorArguments`, ...).
+ */
+
+const EXACT_VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
+const CARET_RANGE_PATTERN = /^\^(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * @param {string} version a canonical `major.minor.patch` SemVer string
+ * @returns {[number, number, number]} the parsed components
+ */
+function parseExactVersion(version) {
+  const match = EXACT_VERSION_PATTERN.exec(version);
+  if (!match) {
+    throw new Error(`not a canonical major.minor.patch version: ${version}`);
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/**
+ * @param {[number, number, number]} a
+ * @param {[number, number, number]} b
+ * @returns {number} negative, zero or positive per standard comparator
+ *   contract
+ */
+function compareVersions(a, b) {
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return 0;
+}
+
+/**
+ * Whether `version` satisfies `range`, supporting only an exact
+ * `major.minor.patch` range (equality) or a caret range `^major.minor.patch`
+ * (matches `>=major.minor.patch <(major+1).0.0`, or, for a `0.x.y` caret
+ * range, npm's own tightened `0.x` semantics: `>=0.minor.patch <0.(minor+1).0`).
+ *
+ * @param {string} version this renderer's own exact published version
+ * @param {string} range the theme's declared `templateRange`
+ * @returns {boolean} whether `version` satisfies `range`
+ * @throws {Error} when `range` is not one of the two closed forms this
+ *   module admits
+ */
+export function satisfiesTemplateRange(version, range) {
+  const parsedVersion = parseExactVersion(version);
+  const exactMatch = EXACT_VERSION_PATTERN.exec(range);
+  if (exactMatch) {
+    return compareVersions(parsedVersion, parseExactVersion(range)) === 0;
+  }
+  const caretMatch = CARET_RANGE_PATTERN.exec(range);
+  if (caretMatch) {
+    const lower = /** @type {[number, number, number]} */ ([
+      Number(caretMatch[1]),
+      Number(caretMatch[2]),
+      Number(caretMatch[3]),
+    ]);
+    if (compareVersions(parsedVersion, lower) < 0) return false;
+    const [major, minor] = lower;
+    if (major > 0) {
+      return parsedVersion[0] === major;
+    }
+    if (minor > 0) {
+      return parsedVersion[0] === 0 && parsedVersion[1] === minor;
+    }
+    // ^0.0.z: npm pins this to the exact patch version.
+    return compareVersions(parsedVersion, lower) === 0;
+  }
+  throw new Error(
+    `templateRange must be an exact "major.minor.patch" version or a ` +
+      `"^major.minor.patch" caret range, got ${JSON.stringify(range)}`,
+  );
+}