jekyll-theme-zer0 1.31.2 → 1.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +183 -0
  3. data/_data/ai.yml +1 -1
  4. data/_data/backlog.yml +149 -28
  5. data/_data/features.yml +173 -17
  6. data/_data/navigation/admin.yml +26 -8
  7. data/_data/navigation/docs.yml +2 -8
  8. data/_data/site_builder.yml +1 -1
  9. data/_data/theme-manifest.yml +74 -58
  10. data/_data/ui-text.yml +9 -0
  11. data/_includes/README.md +2 -1
  12. data/_includes/analytics/google-analytics.html +46 -9
  13. data/_includes/analytics/posthog.html +101 -77
  14. data/_includes/components/ai-chat.html +3 -3
  15. data/_includes/components/author-bio.html +3 -1
  16. data/_includes/components/author-card.html +9 -9
  17. data/_includes/components/author-eeat.html +13 -3
  18. data/_includes/components/collection-manager.html +2 -2
  19. data/_includes/components/component-showcase.html +7 -7
  20. data/_includes/components/cookie-consent-needed.html +37 -0
  21. data/_includes/components/cookie-consent.html +44 -5
  22. data/_includes/components/page-feedback.html +10 -6
  23. data/_includes/components/post-card.html +2 -2
  24. data/_includes/components/theme-customizer.html +1 -1
  25. data/_includes/content/comments.html +46 -0
  26. data/_includes/content/giscus.html +22 -13
  27. data/_includes/content/intro.html +39 -3
  28. data/_includes/content/jsonld-software.html +4 -9
  29. data/_includes/content/sitemap.html +173 -17
  30. data/_includes/core/favicon.html +42 -6
  31. data/_includes/core/footer.html +38 -17
  32. data/_includes/core/header.html +11 -2
  33. data/_includes/navigation/admin-nav.html +110 -63
  34. data/_includes/navigation/section-sidebar.html +20 -20
  35. data/_includes/navigation/sidebar-config.html +17 -8
  36. data/_includes/navigation/sidebar-right.html +16 -2
  37. data/_includes/setup/wizard.html +2 -2
  38. data/_layouts/README.md +1 -1
  39. data/_layouts/admin.html +49 -20
  40. data/_layouts/article.html +10 -10
  41. data/_layouts/book-story.html +3 -7
  42. data/_layouts/default.html +63 -2
  43. data/_layouts/news.html +8 -7
  44. data/_layouts/note.html +2 -6
  45. data/_layouts/notebook.html +2 -6
  46. data/_layouts/recipe.html +3 -7
  47. data/_layouts/root.html +7 -4
  48. data/_layouts/section.html +43 -42
  49. data/_sass/components/_back-to-top.scss +9 -0
  50. data/_sass/components/_cookie-banner.scss +31 -0
  51. data/_sass/components/_page-feedback.scss +1 -1
  52. data/_sass/components/_ui-enhancements.scss +22 -0
  53. data/_sass/core/_nav-tree.scss +10 -2
  54. data/_sass/core/_navbar.scss +19 -5
  55. data/_sass/core/_obsidian.scss +19 -3
  56. data/_sass/core/_sidebar-categories.scss +4 -2
  57. data/_sass/core/_sidebar-extras.scss +3 -2
  58. data/_sass/layouts/_admin.scss +60 -0
  59. data/_sass/layouts/_navbar-extras.scss +7 -2
  60. data/_sass/theme/_skins.scss +124 -32
  61. data/_sass/tokens/_color.scss +3 -0
  62. data/_sass/tokens/_layers.scss +12 -5
  63. data/_sass/utilities/_focus.scss +12 -1
  64. data/assets/css/main.scss +1 -0
  65. data/assets/js/code-copy.js +30 -2
  66. data/assets/js/modules/navigation/index.js +94 -40
  67. data/assets/js/modules/navigation/scroll-spy.js +70 -7
  68. data/assets/js/setup-wizard.js +2 -2
  69. data/assets/js/ui-enhancements.js +46 -0
  70. data/scripts/ai/README.md +1 -1
  71. data/scripts/ai/api_call.rb +1 -1
  72. data/scripts/bin/audit-consumer +155 -8
  73. data/scripts/bin/manifest +27 -8
  74. data/scripts/bin/validate +3 -2
  75. data/scripts/ci/test_visual_evidence_autogen.py +53 -1
  76. data/scripts/ci/visual_evidence_autogen.py +26 -7
  77. data/scripts/install/ai/client.sh +1 -1
  78. data/scripts/lib/audit.sh +156 -0
  79. data/scripts/lib/preview_generator.py +1 -1
  80. data/scripts/translate.rb +1 -1
  81. data/scripts/validate-features.rb +20 -2
  82. metadata +5 -2
@@ -36,6 +36,50 @@ import { TocVisibility } from './toc-visibility.js';
36
36
  import { SidebarVisibility } from './sidebar-visibility.js';
37
37
  import { Navbar } from './navbar.js';
38
38
 
39
+ /** Marker in an init step list: give the main thread back before continuing. */
40
+ const YIELD = Symbol('yield');
41
+
42
+ /**
43
+ * Yield to the main thread so pending input and rendering can run.
44
+ * Uses scheduler.yield() where available (keeps our priority), otherwise a
45
+ * macrotask via MessageChannel (no 4ms setTimeout clamp).
46
+ * @returns {Promise<void>}
47
+ */
48
+ function yieldToMain() {
49
+ if (typeof window !== 'undefined' && window.scheduler && typeof window.scheduler.yield === 'function') {
50
+ return window.scheduler.yield();
51
+ }
52
+ return new Promise(resolve => {
53
+ if (typeof MessageChannel === 'function') {
54
+ const channel = new MessageChannel();
55
+ channel.port1.onmessage = () => resolve();
56
+ channel.port2.postMessage(null);
57
+ } else {
58
+ setTimeout(resolve, 0);
59
+ }
60
+ });
61
+ }
62
+
63
+ /**
64
+ * Run init steps in order, yielding at each YIELD marker. A step that throws
65
+ * is logged and does not stop the steps after it.
66
+ * @param {Array<Function|symbol>} steps
67
+ * @returns {Promise<void>}
68
+ */
69
+ async function runSteps(steps) {
70
+ for (const step of steps) {
71
+ if (step === YIELD) {
72
+ await yieldToMain();
73
+ continue;
74
+ }
75
+ try {
76
+ step();
77
+ } catch (error) {
78
+ console.error('Navigation: Initialization error', error);
79
+ }
80
+ }
81
+ }
82
+
39
83
  /**
40
84
  * Navigation Controller - Orchestrates all navigation modules
41
85
  */
@@ -54,59 +98,69 @@ export class Navigation {
54
98
  console.warn('Navigation: Already initialized');
55
99
  return this;
56
100
  }
101
+ this._initialized = true;
57
102
 
58
- try {
103
+ // Start-up is split across tasks so it never becomes one long task.
104
+ // Phase 1 (this task) wires the controls a user can reach right away:
105
+ // sidebar state, keyboard shortcuts, focus management and the navbar.
106
+ // None of them read layout. Each later step reads styles or layout
107
+ // (breakpoints, TOC/sidebar visibility, scroll spy), so each one runs
108
+ // in its own task after yielding to the main thread, letting the
109
+ // browser paint and handle input in between. `navigation:ready` is
110
+ // still dispatched once every module exists.
111
+ const steps = [
112
+ () => { this.modules.state = new SidebarState(); },
113
+ () => { this.modules.keyboard = new KeyboardShortcuts(); },
114
+ () => { this.modules.focus = new FocusManager(); },
115
+ () => {
116
+ // Initialize navbar (hover dropdowns, mobile menu, tooltips,
117
+ // focus trap) — formerly the standalone assets/js/navigation.js IIFE.
118
+ this.modules.navbar = new Navbar(config);
119
+ this.modules.navbar.init();
120
+ },
121
+ YIELD,
59
122
  // Sync breakpoints from --zer0-bp-* CSS custom properties so a fork
60
123
  // overriding tokens in SCSS automatically propagates to JS checks.
61
- syncBreakpointsFromCss();
62
-
63
- // Initialize sidebar state first (other modules may depend on it)
64
- this.modules.state = new SidebarState();
65
-
66
- const leftSidebar = document.querySelector(config.selectors.leftSidebar);
67
- const docsLayout = document.querySelector(config.selectors.docsLayout);
68
- if (leftSidebar && docsLayout && !docsLayout.classList.contains('bd-layout--no-sidebar')) {
69
- this.modules.sidebarVisibility = new SidebarVisibility();
70
- }
71
-
72
- // Initialize TOC-related modules only if TOC exists
73
- const toc = document.querySelector(config.selectors.toc);
74
- if (toc) {
124
+ // getComputedStyle forces a full style recalc, so it runs after the
125
+ // first yield, before the modules that use breakpoints.
126
+ () => { syncBreakpointsFromCss(); },
127
+ () => { this.modules.gestures = new SwipeGestures(); },
128
+ YIELD,
129
+ () => {
130
+ const leftSidebar = document.querySelector(config.selectors.leftSidebar);
131
+ const docsLayout = document.querySelector(config.selectors.docsLayout);
132
+ if (leftSidebar && docsLayout && !docsLayout.classList.contains('bd-layout--no-sidebar')) {
133
+ this.modules.sidebarVisibility = new SidebarVisibility();
134
+ }
135
+ },
136
+ YIELD,
137
+ () => {
138
+ // Initialize TOC-related modules only if TOC exists
139
+ if (!document.querySelector(config.selectors.toc)) {
140
+ console.log('Navigation: No TOC found, skipping scroll spy and smooth scroll');
141
+ return;
142
+ }
75
143
  this.modules.tocVisibility = new TocVisibility();
76
- this.modules.scrollSpy = new ScrollSpy();
77
144
  this.modules.smoothScroll = new SmoothScroll();
78
- } else {
79
- console.log('Navigation: No TOC found, skipping scroll spy and smooth scroll');
145
+ },
146
+ YIELD,
147
+ () => {
148
+ if (!this.modules.tocVisibility) return;
149
+ // ScrollSpy defers its own first measurement to idle time.
150
+ this.modules.scrollSpy = new ScrollSpy();
80
151
  }
81
-
82
- // Initialize keyboard shortcuts
83
- this.modules.keyboard = new KeyboardShortcuts();
84
-
85
- // Initialize gesture support
86
- this.modules.gestures = new SwipeGestures();
87
-
88
- // Initialize focus management
89
- this.modules.focus = new FocusManager();
90
-
91
- // Initialize navbar (hover dropdowns, mobile menu, tooltips,
92
- // focus trap) — formerly the standalone assets/js/navigation.js IIFE.
93
- this.modules.navbar = new Navbar(config);
94
- this.modules.navbar.init();
95
-
96
- this._initialized = true;
97
-
152
+ ];
153
+
154
+ runSteps(steps).then(() => {
98
155
  // Dispatch ready event
99
156
  document.dispatchEvent(new CustomEvent('navigation:ready', {
100
- detail: {
157
+ detail: {
101
158
  modules: Object.keys(this.modules)
102
159
  }
103
160
  }));
104
161
 
105
162
  console.log('Navigation: Successfully initialized modules:', Object.keys(this.modules));
106
-
107
- } catch (error) {
108
- console.error('Navigation: Initialization error', error);
109
- }
163
+ });
110
164
 
111
165
  return this;
112
166
  }
@@ -28,6 +28,8 @@
28
28
  * - Deterministic, position-based active section (no ratio guessing)
29
29
  * - rAF-throttled passive scroll listener; heading offsets are cached and
30
30
  * re-measured on resize / content reflow
31
+ * - First measurement deferred to idle time so start-up doesn't force a
32
+ * synchronous layout of the whole page
31
33
  * - Holds the clicked link active while a smooth scroll animates, so
32
34
  * intermediate headings don't flash
33
35
  * - Keeps the active link visible inside the TOC without ever scrolling
@@ -83,6 +85,24 @@ function scrollTop() {
83
85
  return window.scrollY !== undefined ? window.scrollY : window.pageYOffset;
84
86
  }
85
87
 
88
+ /** Latest moment (ms) the first measurement may be put off while the page is busy. */
89
+ const IDLE_TIMEOUT_MS = 1500;
90
+
91
+ /**
92
+ * Run `fn` when the main thread is idle (requestIdleCallback with a
93
+ * timeout), or after a short delay where that API is missing (Safari).
94
+ * @param {Function} fn
95
+ * @returns {{cancel: Function}}
96
+ */
97
+ function scheduleIdle(fn) {
98
+ if (typeof window.requestIdleCallback === 'function') {
99
+ const id = window.requestIdleCallback(fn, { timeout: IDLE_TIMEOUT_MS });
100
+ return { cancel: () => window.cancelIdleCallback(id) };
101
+ }
102
+ const id = window.setTimeout(fn, 200);
103
+ return { cancel: () => window.clearTimeout(id) };
104
+ }
105
+
86
106
  export class ScrollSpy {
87
107
  constructor() {
88
108
  this.tocLinks = getElements(config.selectors.tocLinks);
@@ -100,6 +120,7 @@ export class ScrollSpy {
100
120
  this._pendingExpires = 0;
101
121
 
102
122
  this._resizeObserver = null;
123
+ this._idleHandle = null;
103
124
 
104
125
  if (this.headings.length === 0 || this.tocLinks.length === 0) {
105
126
  console.log('ScrollSpy: No TOC or headings found, skipping initialization');
@@ -160,6 +181,27 @@ export class ScrollSpy {
160
181
  window.addEventListener('wheel', this._onUserScroll, { passive: true });
161
182
  window.addEventListener('touchstart', this._onUserScroll, { passive: true });
162
183
 
184
+ // The first measurement reads every heading's position, which forces
185
+ // a full synchronous layout if it runs while the page is still
186
+ // loading. On a long quest page that was one of the biggest long
187
+ // tasks at start-up. The TOC highlight isn't needed for first paint,
188
+ // so measure once the browser is idle (or after IDLE_TIMEOUT_MS at
189
+ // the latest), when layout is already done and the reads are cheap.
190
+ // A scroll before then still updates through the rAF path above.
191
+ this._idleHandle = scheduleIdle(() => {
192
+ this._idleHandle = null;
193
+ this._startMeasuring();
194
+ });
195
+
196
+ console.log(`ScrollSpy: Tracking ${this.headings.length} headings`);
197
+ }
198
+
199
+ /**
200
+ * Observe content reflow and paint the initial active link.
201
+ * Runs from idle time (see _init).
202
+ * @private
203
+ */
204
+ _startMeasuring() {
163
205
  // Images, embeds, mermaid diagrams and collapsibles change heading
164
206
  // offsets after load - re-measure when the content box resizes.
165
207
  if (typeof ResizeObserver !== 'undefined') {
@@ -169,8 +211,6 @@ export class ScrollSpy {
169
211
  }
170
212
 
171
213
  this._update();
172
-
173
- console.log(`ScrollSpy: Tracking ${this.headings.length} headings`);
174
214
  }
175
215
 
176
216
  /**
@@ -325,6 +365,11 @@ export class ScrollSpy {
325
365
  // heals itself rather than silently disappearing.
326
366
  if (this.currentActive === link && link.classList.contains(ACTIVE_CLASS)) return;
327
367
 
368
+ // Read layout for the TOC scroll adjustment BEFORE touching classes:
369
+ // reading after the class change below would force a synchronous
370
+ // style + layout pass on every highlight change.
371
+ const tocScroll = this._measureTocScroll(link);
372
+
328
373
  // Remove previous active state
329
374
  this.tocLinks.forEach(l => {
330
375
  if (l === link) return;
@@ -338,7 +383,7 @@ export class ScrollSpy {
338
383
  this.currentActive = link;
339
384
 
340
385
  // Scroll TOC to show active link (if needed)
341
- this._scrollTocToActiveLink(link);
386
+ if (tocScroll) tocScroll.container.scrollTop += tocScroll.delta;
342
387
 
343
388
  // Dispatch custom event for other modules
344
389
  document.dispatchEvent(new CustomEvent('navigation:sectionChange', {
@@ -381,18 +426,32 @@ export class ScrollSpy {
381
426
  * @param {Element} link
382
427
  */
383
428
  _scrollTocToActiveLink(link) {
429
+ const tocScroll = this._measureTocScroll(link);
430
+ if (tocScroll) tocScroll.container.scrollTop += tocScroll.delta;
431
+ }
432
+
433
+ /**
434
+ * How far the TOC's scroll container must move to show `link`.
435
+ * Read-only, so callers can measure before they write.
436
+ * @private
437
+ * @param {Element} link
438
+ * @returns {{container: Element, delta: number}|null}
439
+ */
440
+ _measureTocScroll(link) {
384
441
  const container = this._getTocScrollContainer(link);
385
- if (!container) return;
442
+ if (!container) return null;
386
443
 
387
444
  const linkRect = link.getBoundingClientRect();
388
445
  const containerRect = container.getBoundingClientRect();
389
446
  const margin = 8;
390
447
 
391
448
  if (linkRect.top < containerRect.top + margin) {
392
- container.scrollTop -= (containerRect.top + margin) - linkRect.top;
393
- } else if (linkRect.bottom > containerRect.bottom - margin) {
394
- container.scrollTop += linkRect.bottom - (containerRect.bottom - margin);
449
+ return { container, delta: -((containerRect.top + margin) - linkRect.top) };
395
450
  }
451
+ if (linkRect.bottom > containerRect.bottom - margin) {
452
+ return { container, delta: linkRect.bottom - (containerRect.bottom - margin) };
453
+ }
454
+ return null;
396
455
  }
397
456
 
398
457
  /**
@@ -434,6 +493,10 @@ export class ScrollSpy {
434
493
  window.removeEventListener('wheel', this._onUserScroll);
435
494
  window.removeEventListener('touchstart', this._onUserScroll);
436
495
  }
496
+ if (this._idleHandle) {
497
+ this._idleHandle.cancel();
498
+ this._idleHandle = null;
499
+ }
437
500
  if (this._resizeObserver) {
438
501
  this._resizeObserver.disconnect();
439
502
  this._resizeObserver = null;
@@ -930,7 +930,7 @@
930
930
  L.push(' enabled: ' + (c.on('posthog') && f['posthog.api_key'] ? 'true' : 'false'));
931
931
  L.push(' api_key: ' + y(f['posthog.api_key'] || ''));
932
932
  L.push('cookie_consent:');
933
- L.push(' enabled: true');
933
+ L.push(' # enabled unset = the banner shows only when an analytics key above is set');
934
934
  L.push(' expiry_days: 365');
935
935
  L.push('giscus:');
936
936
  L.push(' enabled: ' + (c.on('giscus') && f['giscus.repo_id'] && f['giscus.category_id'] ? 'true' : 'false'));
@@ -1250,7 +1250,7 @@
1250
1250
  ' {%- when "cta" -%}',
1251
1251
  ' <div class="text-center">{% if s.cta %}{% include components/cta-button.html label=s.cta.label url=s.cta.url variant="light" size="lg" %}{% endif %}</div>',
1252
1252
  ' {%- when "latest_posts" -%}',
1253
- ' <div class="row g-4">{% for post in site.posts limit: s.limit | default: 3 %}<div class="col-md-4"><a class="card h-100 text-decoration-none" href="{{ post.url | relative_url }}"><div class="card-body"><p class="small text-body-secondary mb-1">{{ post.date | date: "%B %-d, %Y" }}</p><h3 class="h5 card-title">{{ post.title }}</h3><p class="card-text text-body-secondary mb-0">{{ post.description | default: post.excerpt | strip_html | truncate: 140 }}</p></div></a></div>{% endfor %}</div>',
1253
+ ' <div class="row g-4">{% assign post_limit = s.limit | default: 3 %}{% for post in site.posts limit: post_limit %}<div class="col-md-4"><a class="card h-100 text-decoration-none" href="{{ post.url | relative_url }}"><div class="card-body"><p class="small text-body-secondary mb-1">{{ post.date | date: "%B %-d, %Y" }}</p><h3 class="h5 card-title">{{ post.title }}</h3><p class="card-text text-body-secondary mb-0">{{ post.description | default: post.excerpt | strip_html | truncate: 140 }}</p></div></a></div>{% endfor %}</div>',
1254
1254
  ' {%- when "quote" -%}',
1255
1255
  ' {% assign q = s.items | first %}<figure class="text-center mb-0"><blockquote class="blockquote fs-3"><p>“{{ q.quote }}”</p></blockquote>{% if q.author %}<figcaption class="blockquote-footer mt-2">{{ q.author }}</figcaption>{% endif %}</figure>',
1256
1256
  ' {%- else -%}',
@@ -139,6 +139,51 @@
139
139
  sections.forEach(section => observer.observe(section));
140
140
  }
141
141
 
142
+ /**
143
+ * Give every GFM task-list checkbox an accessible name (#573).
144
+ *
145
+ * kramdown emits `<li class="task-list-item"><input class="task-list-item-checkbox">Text`
146
+ * with no `<label>`, so axe `label` fires on every box (WCAG 1.3.1 / 4.1.2).
147
+ * The item's own text — the nodes after the box, stopping at a nested list —
148
+ * is wrapped in a `<span id>` and the box points at it with `aria-labelledby`.
149
+ * A `<label>` wrapper is deliberately not used: it would make the text a click
150
+ * target, which changes behaviour for sites that make the boxes interactive.
151
+ * Boxes that already carry `aria-label` / `aria-labelledby` are left alone.
152
+ */
153
+ let taskLabelSeq = 0;
154
+
155
+ function labelTaskListCheckboxes(root) {
156
+ const scope = root || document;
157
+ scope.querySelectorAll('.task-list-item-checkbox').forEach(box => {
158
+ if (box.hasAttribute('aria-label') || box.hasAttribute('aria-labelledby')) return;
159
+ const container = box.parentNode;
160
+ if (!container) return;
161
+
162
+ const own = [];
163
+ for (let node = box.nextSibling; node; node = node.nextSibling) {
164
+ if (node.nodeType === Node.ELEMENT_NODE && /^(UL|OL)$/.test(node.nodeName)) break;
165
+ own.push(node);
166
+ }
167
+ const text = own.map(node => node.textContent).join('').trim();
168
+ if (!text) return;
169
+
170
+ let id;
171
+ do {
172
+ taskLabelSeq += 1;
173
+ id = 'task-list-label-' + taskLabelSeq;
174
+ } while (document.getElementById(id));
175
+
176
+ const span = document.createElement('span');
177
+ span.id = id;
178
+ container.insertBefore(span, own[0]);
179
+ own.forEach(node => span.appendChild(node));
180
+ box.setAttribute('aria-labelledby', id);
181
+ });
182
+ }
183
+
184
+ // Exposed so content rendered after load (and tests) can label new lists.
185
+ window.zer0LabelTaskLists = labelTaskListCheckboxes;
186
+
142
187
  /**
143
188
  * Initialize all enhancements
144
189
  */
@@ -155,6 +200,7 @@
155
200
  initImageLoading();
156
201
  initButtonRipples();
157
202
  initScrollSpy();
203
+ labelTaskListCheckboxes();
158
204
  }
159
205
 
160
206
  // Start initialization
data/scripts/ai/README.md CHANGED
@@ -31,7 +31,7 @@ Auth from the job env, OAuth first (`CLAUDE_CODE_OAUTH_TOKEN`, then `ANTHROPIC_A
31
31
  tools: "Read,Grep,Glob,Bash(gh:*)"
32
32
  ```
33
33
 
34
- Inputs: `prompt`, `agent`, `tools`, `mcp`, `system`, `out`, `model`, `max-turns`. Callers in this repo: `issue-autopilot.yml` (triage, verify, resolve) and `visual-evidence-autogen.yml`. Where a lane is the standard shape (gate on a `*_ENABLED` variable, run one agent, open one PR), the hub also offers the reusable `bamr87/bamr87/.github/workflows/ai-lane.yml@main`; the matrix-fed autopilot is deliberately not that shape.
34
+ Inputs: `prompt`, `agent`, `tools`, `mcp`, `system`, `out`, `model`, `max-turns`, `max-budget-usd` (default 10). Callers in this repo: `issue-autopilot.yml` (triage, verify, resolve), `visual-evidence-autogen.yml`, `ai-content-review.yml`, `ci-self-repair.yml` and `ui-audit.yml`; each passes `AI_AUTH_ORDER: ${{ vars.CLAUDE_AUTH_ORDER }}` so the runner tries the credentials in this repo's order. Where a lane is the standard shape (gate on a `*_ENABLED` variable, run one agent, open one PR), the hub also offers the reusable `bamr87/bamr87/.github/workflows/ai-lane.yml@main`; the matrix-fed autopilot is deliberately not that shape.
35
35
 
36
36
  ## Metering companions are kit files too
37
37
 
@@ -35,7 +35,7 @@ cfg = begin
35
35
  rescue StandardError
36
36
  {}
37
37
  end
38
- MODEL = ENV['AI_MODEL'] || cfg['fallback_model'] || cfg['model'] || 'claude-opus-4-8'
38
+ MODEL = ENV['AI_MODEL'] || cfg['fallback_model'] || cfg['model'] || 'claude-opus-5-5'
39
39
  MAXTOK = (ENV['AI_MAX_TOKENS'] || cfg['max_tokens'] || 8000).to_i
40
40
  VERSION = cfg['api_version'] || '2023-06-01'
41
41
  BASE = cfg['api_base'] || 'https://api.anthropic.com'
@@ -6,6 +6,7 @@
6
6
  # --theme-path <dir> Explicit theme path (auto-resolved if omitted)
7
7
  # --mode {gem|remote_theme} Deployment mode (auto-detected if omitted)
8
8
  # --fix Delete IDENTICAL files + copy MISSING/STALE plugins
9
+ # + refresh STALE/MISSING vendored _data
9
10
  # --overwrite-plugins Combined with --fix: replace STALE plugins too
10
11
  # --strict Exit non-zero on any unjustified drift (for CI)
11
12
  # --format {text|json|github} Output format (default: text)
@@ -52,17 +53,44 @@ DESCRIPTION:
52
53
  OK Plugin matches current theme version
53
54
  NOT_REQUIRED Gem mode — theme loads plugins itself
54
55
 
56
+ Vendored data classifications (both modes):
57
+ Jekyll 3.10 (GitHub Pages) never loads a theme's _data/, so a site
58
+ reads the theme's data only from its own copy, and that copy does NOT
59
+ float with remote_theme. Re-run the audit after every theme update.
60
+
61
+ Theme-owned registries you copy verbatim (manifest vendored_data_paths:
62
+ _data/theme_skins.yml, _data/theme_backgrounds.yml):
63
+ IDENTICAL Your copy matches the theme → current, keep it
64
+ STALE Your copy differs and is NOT listed in
65
+ .theme-overrides.yml → --fix refreshes it from the
66
+ theme; counts toward --strict
67
+ DIFFERS_JUSTIFIED Your copy differs and is listed → intentional
68
+ MISSING No copy → informational (the theme's includes fall
69
+ back to built-in defaults); --fix copies it
70
+
71
+ Data you customise (YAML files in manifest theme_data_paths, i.e.
72
+ _data/ui-text.yml): only keys are compared, never values.
73
+ MISSING_KEYS Keys the theme's en: block has that yours lacks
74
+ → warn-only, never fails --strict; add them by hand
75
+ (--fix never edits a file you customise)
76
+ OK Every key is present
77
+ MISSING No copy → informational
78
+
55
79
  OPTIONS:
56
80
  --consumer-path <dir> Consumer repo root (default: current directory)
57
81
  --theme-path <dir> Explicit theme path (auto-resolved if omitted)
58
82
  --mode {gem|remote_theme} Force deployment mode (auto-detected if omitted)
59
83
  --fix Fix issues: delete IDENTICAL files; copy
60
- MISSING_PLUGIN files from theme
84
+ MISSING_PLUGIN files from theme; refresh
85
+ STALE and MISSING vendored data from theme
61
86
  --overwrite-plugins With --fix: also replace STALE_PLUGIN files
62
- --strict Exit 1 if any DIFFERS_UNJUSTIFIED or
63
- MISSING_PLUGIN issues found (use in CI)
87
+ --strict Exit 1 if any DIFFERS_UNJUSTIFIED,
88
+ MISSING_PLUGIN or STALE vendored data
89
+ issues found (use in CI)
64
90
  --format {text|json|github} Output format
65
- github emits ::warning annotations for CI
91
+ github emits ::warning annotations for CI;
92
+ json reports vendored data in its own
93
+ "vendored_data" array beside "results"
66
94
  --verbose Show debug output
67
95
  --dry-run Show what --fix would do without changing files
68
96
  --help, -h Show this help
@@ -83,6 +111,9 @@ EXAMPLES:
83
111
 
84
112
  # Fix including stale plugins
85
113
  ./scripts/bin/audit-consumer --fix --overwrite-plugins
114
+
115
+ # After a theme update: refresh vendored _data that fell behind
116
+ ./scripts/bin/audit-consumer --consumer-path ~/github/lifehacker.dev --fix --dry-run
86
117
  EOF
87
118
  }
88
119
 
@@ -175,7 +206,8 @@ fi
175
206
  OVERRIDES_FILE="$CONSUMER_ROOT/.theme-overrides.yml"
176
207
  [[ -f "$OVERRIDES_FILE" ]] || OVERRIDES_FILE="$CONSUMER_PATH/.theme-overrides.yml"
177
208
  OVERRIDE_PATHS_TMP=$(mktemp)
178
- trap 'rm -f "$OVERRIDE_PATHS_TMP"' EXIT
209
+ KEYS_ERR_TMP=$(mktemp)
210
+ trap 'rm -f "$OVERRIDE_PATHS_TMP" "$KEYS_ERR_TMP"' EXIT
179
211
 
180
212
  if [[ -f "$OVERRIDES_FILE" ]]; then
181
213
  info "Override manifest: $OVERRIDES_FILE"
@@ -224,6 +256,26 @@ if [[ ${#REQUIRED_PLUGIN_FILES[@]} -eq 0 && ${#OPTIONAL_PLUGIN_FILES[@]} -eq 0 ]
224
256
  )
225
257
  fi
226
258
 
259
+ # Data the theme ships but cannot deliver (see "Scan vendored theme data").
260
+ # A manifest snapshot cut before `vendored_data_paths` existed (1.31.x and
261
+ # older) lacks the key, so fall back to the list scripts/lib/audit.sh keeps.
262
+ VENDORED_DATA_FILES=()
263
+ THEME_DATA_FILES=()
264
+ if [[ -n "$MANIFEST" ]] && manifest_has_key "$MANIFEST" "vendored_data_paths"; then
265
+ while IFS= read -r line; do
266
+ [[ -n "$line" ]] && VENDORED_DATA_FILES+=("$line")
267
+ done < <(manifest_list "$MANIFEST" "vendored_data_paths")
268
+ else
269
+ VENDORED_DATA_FILES=("${THEME_VENDORED_DATA_PATHS[@]}")
270
+ fi
271
+ if [[ -n "$MANIFEST" ]] && manifest_has_key "$MANIFEST" "theme_data_paths"; then
272
+ while IFS= read -r line; do
273
+ [[ -n "$line" ]] && THEME_DATA_FILES+=("$line")
274
+ done < <(manifest_list "$MANIFEST" "theme_data_paths")
275
+ else
276
+ THEME_DATA_FILES=("_data/ui-text.yml")
277
+ fi
278
+
227
279
  # ---------------------------------------------------------------------------
228
280
  # Scan themable directories
229
281
  # ---------------------------------------------------------------------------
@@ -301,6 +353,73 @@ if [[ ${#ALL_PLUGIN_FILES[@]} -gt 0 ]]; then
301
353
  done
302
354
  fi
303
355
 
356
+ # ---------------------------------------------------------------------------
357
+ # Scan vendored theme data
358
+ # ---------------------------------------------------------------------------
359
+ # Jekyll 3.10, which GitHub Pages and the github-pages gem run, never loads a
360
+ # theme's _data/ in either mode, so every consumer keeps its own copy of the
361
+ # theme's data, and the floating remote_theme never updates it: a copy freezes
362
+ # on the day it was made (#556). The pass runs in both modes.
363
+ STALE_DATA_FILES=()
364
+ MISSING_DATA_FILES=()
365
+ DATA_JSON_ENTRIES=()
366
+ DATA_STALE_COUNT=0
367
+ DATA_MISSING_COUNT=0
368
+ DATA_MISSING_KEYS_COUNT=0
369
+
370
+ # report_data <classification> <relpath> [missing_keys]
371
+ report_data() {
372
+ if [[ "$FORMAT" == "json" ]]; then
373
+ DATA_JSON_ENTRIES+=("$(data_json_entry "$1" "$2" "${3:-}")")
374
+ else
375
+ print_data_classification "$1" "$2" "$FORMAT" "${3:-}"
376
+ fi
377
+ }
378
+
379
+ [[ "$FORMAT" == "text" ]] && echo ""
380
+ [[ "$FORMAT" == "text" ]] && info "--- Vendored theme data (does not float with remote_theme) ---"
381
+
382
+ for data_rel in ${VENDORED_DATA_FILES[@]+"${VENDORED_DATA_FILES[@]}"}; do
383
+ classification=$(classify_vendored_data "$RESOLVED_THEME" "$CONSUMER_PATH" "$data_rel" "$OVERRIDE_PATHS_TMP")
384
+ [[ -n "$classification" ]] || continue # this theme checkout does not ship it
385
+ report_data "$classification" "$data_rel"
386
+ case "$classification" in
387
+ STALE)
388
+ STALE_DATA_FILES+=("$data_rel")
389
+ DATA_STALE_COUNT=$((DATA_STALE_COUNT + 1)) ;;
390
+ MISSING)
391
+ MISSING_DATA_FILES+=("$data_rel")
392
+ DATA_MISSING_COUNT=$((DATA_MISSING_COUNT + 1)) ;;
393
+ esac
394
+ done
395
+
396
+ for data_rel in ${THEME_DATA_FILES[@]+"${THEME_DATA_FILES[@]}"}; do
397
+ # Only a YAML file has keys to compare. A directory such as _data/navigation
398
+ # is the consumer's own content end to end.
399
+ [[ -f "$RESOLVED_THEME/$data_rel" ]] || continue
400
+ case "$data_rel" in
401
+ *.yml|*.yaml) ;;
402
+ *) continue ;;
403
+ esac
404
+ if [[ ! -f "$CONSUMER_PATH/$data_rel" ]]; then
405
+ report_data "MISSING" "$data_rel"
406
+ continue
407
+ fi
408
+
409
+ keys_status=0
410
+ missing_keys=$(missing_data_keys "$RESOLVED_THEME/$data_rel" "$CONSUMER_PATH/$data_rel" 2>"$KEYS_ERR_TMP") || keys_status=$?
411
+ if [[ "$keys_status" -eq 2 ]]; then
412
+ warn "ruby not found: skipped the key check of $data_rel"
413
+ elif [[ "$keys_status" -ne 0 ]]; then
414
+ warn "Could not compare the keys of $data_rel: $(head -n 1 "$KEYS_ERR_TMP")"
415
+ elif [[ -n "$missing_keys" ]]; then
416
+ DATA_MISSING_KEYS_COUNT=$((DATA_MISSING_KEYS_COUNT + $(printf '%s\n' "$missing_keys" | wc -l)))
417
+ report_data "MISSING_KEYS" "$data_rel" "$missing_keys"
418
+ else
419
+ report_data "OK" "$data_rel"
420
+ fi
421
+ done
422
+
304
423
  # ---------------------------------------------------------------------------
305
424
  # Apply fixes
306
425
  # ---------------------------------------------------------------------------
@@ -341,14 +460,36 @@ if [[ "$FIX" == "true" ]]; then
341
460
  fi
342
461
  fi
343
462
  done
463
+
464
+ # Vendored data is the theme's to own: take its copy. A file declared in
465
+ # .theme-overrides.yml is DIFFERS_JUSTIFIED and never listed here, and a
466
+ # file the consumer customises (ui-text.yml) is never written.
467
+ for data_rel in ${STALE_DATA_FILES[@]+"${STALE_DATA_FILES[@]}"} ${MISSING_DATA_FILES[@]+"${MISSING_DATA_FILES[@]}"}; do
468
+ if [[ "$DRY_RUN" == "true" ]]; then
469
+ info "[DRY RUN] Would refresh vendored data from the theme: $data_rel"
470
+ else
471
+ mkdir -p "$(dirname "$CONSUMER_PATH/$data_rel")"
472
+ cp "$RESOLVED_THEME/$data_rel" "$CONSUMER_PATH/$data_rel"
473
+ success "Refreshed vendored data from the theme: $data_rel"
474
+ fi
475
+ done
344
476
  fi
345
477
 
346
478
  # ---------------------------------------------------------------------------
347
479
  # Summary
348
480
  # ---------------------------------------------------------------------------
349
481
  # Entries are printed without a trailing newline (see print_classification),
350
- # so close the array on its own line.
351
- [[ "$FORMAT" == "json" ]] && printf '\n]}\n'
482
+ # so close each array on its own line. Vendored data gets its own array: for
483
+ # data, IDENTICAL means "current, keep it", not the themable "safe to delete".
484
+ if [[ "$FORMAT" == "json" ]]; then
485
+ printf '\n],"vendored_data":['
486
+ data_sep=""
487
+ for data_entry in ${DATA_JSON_ENTRIES[@]+"${DATA_JSON_ENTRIES[@]}"}; do
488
+ printf '%s\n %s' "$data_sep" "$data_entry"
489
+ data_sep=","
490
+ done
491
+ printf '\n]}\n'
492
+ fi
352
493
 
353
494
  if [[ "$FORMAT" == "text" ]]; then
354
495
  echo ""
@@ -357,9 +498,15 @@ if [[ "$FORMAT" == "text" ]]; then
357
498
  info "DIFFERS_UNJUSTIFIED files: ${#DIFFERS_UNJUSTIFIED_FILES[@]}"
358
499
  info "Required plugin issues: $PLUGIN_ISSUES"
359
500
  [[ "$OPTIONAL_PLUGIN_ISSUES" -gt 0 ]] && info "Optional plugins not vendored: $OPTIONAL_PLUGIN_ISSUES (informational)"
501
+ info "STALE vendored data files: $DATA_STALE_COUNT (refresh with --fix)"
502
+ [[ "$DATA_MISSING_COUNT" -gt 0 ]] && info "MISSING vendored data files: $DATA_MISSING_COUNT (informational; --fix copies them)"
503
+ [[ "$DATA_MISSING_KEYS_COUNT" -gt 0 ]] && info "Data keys missing (warn-only): $DATA_MISSING_KEYS_COUNT"
360
504
  fi
361
505
 
362
- TOTAL_ISSUES=$((DRIFT_COUNT + PLUGIN_ISSUES))
506
+ # STALE vendored data is unjustified drift like DIFFERS_UNJUSTIFIED. MISSING
507
+ # data and MISSING_KEYS are warn-only: the theme's includes degrade to
508
+ # built-in defaults, so neither fails --strict.
509
+ TOTAL_ISSUES=$((DRIFT_COUNT + PLUGIN_ISSUES + DATA_STALE_COUNT))
363
510
 
364
511
  if [[ "$STRICT" == "true" && "$TOTAL_ISSUES" -gt 0 ]]; then
365
512
  error "Strict mode: $TOTAL_ISSUES unjustified drift issue(s) found."