Production update

.github/workflows/test-lp.yml

@@ -19,12 +19,13 @@ jobs:
       - name: Run hugo command to test site builds
         run: |
           hugo
-      - name: Get all changed markdown files
+      - name: Get changed Learning Path and install guide markdown files
         id: changed-markdown-files
         uses: tj-actions/changed-files@v46
         with:
           files: |
-             content/**/**.md
+             content/learning-paths/**/*.md
+             content/install-guides/**/*.md
       - name: Check for capital letters or spaces in content directory
         run: |
           echo "Checking for capital letters or spaces in content directory paths (excluding file extensions)..."
@@ -63,15 +64,15 @@ jobs:
         run: |
           echo "Checking YAML fields for changed learning paths..."
           python3 tools/verify_index_fields.py ${{ steps.changed-markdown-files.outputs.all_changed_files }}
-      - name: Run test suite for all changed .md files
+      - name: Run test suite for changed Learning Paths and install guides
         id: run-suite
         if: steps.changed-markdown-files.outputs.any_changed == 'true'
         # Run the test suite
         run: |
               set -o pipefail; ./tools/test_lp.sh ${{ steps.changed-markdown-files.outputs.all_changed_files }} 2>&1 | tee test-lp-output.txt
       - name: Parse test suite errors
         id: test-suite-state
-        if: success()
+        if: success() && steps.changed-markdown-files.outputs.any_changed == 'true'
         # Catch any missed errors if running multiple tests
         run: |
             cat test-lp-output.txt | grep -q 'Tests failed in test suite' && echo "TEST_SUITE_ERRORS=true" >> "$GITHUB_ENV" \
@@ -83,7 +84,7 @@ jobs:
           exit 1
       - name: Parse test maintenance off
         id: maintenance-state
-        if: success()
+        if: success() && steps.changed-markdown-files.outputs.any_changed == 'true'
         # Check if maintenance is turned off
         run: |
             cat test-lp-output.txt | grep -q 'maintenance is turned off' && echo "MAINTENANCE=off" >> "$GITHUB_ENV" \

.gitignore

@@ -6,6 +6,7 @@
 /tools/social_card_generation/.social-card-manifest.json*
 __pycache__/
 resources/
+reports/
 node_modules/
 package-lock.json
 .hugo_build.lock

.wordlist.txt

@@ -7655,3 +7655,33 @@ Andreas
 COFF
 disassemblers
 otool
+EventRecord
+EventRecorderConf
+ExifTool
+GLIBCXX
+GLib
+Kostiantyn
+Liam
+OpenSandbox
+Perehuda
+StartA
+StopA
+WASI
+Wasm
+WebAssembly
+arewefastyet
+bdec
+bffefbea
+contentauth
+dialogs
+efd
+exiftool
+labelled
+libjpeg
+libstdc
+opensandbox
+osb
+patool
+wasmCloud
+wasmcloud
+wg

assets/contributors.csv

@@ -188,3 +188,4 @@ Sammy Sahnine,,,,,
 Matthew Sloyan,Arm,matthewsloyanARM,,,
 Austin Hill,,,,,
 Andreas Mullen,Arm,,,,
+Liam Randall,,,,,

assets/search-lab/app.js

@@ -0,0 +1,169 @@
+const $ = id => document.getElementById(id);
+const main = document.querySelector('main[data-index]');
+let worker, workerFailure;
+let allowBlankSearch = false;
+const searchStop = new Set('a an and are at be can do for from how i in is it me my of on or the to using what with'.split(' '));
+let nextId = 0, generation = 0, offset = 0;
+const pending = new Map();
+function failWorker() {
+  workerFailure = Error('Search is unavailable. Reload the page to retry.');
+  worker?.terminate();
+  ++generation;
+  for (const request of pending.values()) request.reject(workerFailure);
+  pending.clear();
+  $('more').hidden = true;
+  $('search-diagnostics').hidden = true;
+  $('status').textContent = workerFailure.message;
+}
+try {
+  worker = new Worker(main.dataset.worker, { type: 'module' });
+  worker.onmessage = ({ data }) => {
+    const request = pending.get(data.id);
+    if (!request) return;
+    pending.delete(data.id);
+    data.error ? request.reject(Error(data.error)) : request.resolve(data.result);
+  };
+  worker.onerror = failWorker;
+  worker.onmessageerror = failWorker;
+} catch { failWorker(); }
+function call(action, input) {
+  if (workerFailure) return Promise.reject(workerFailure);
+  return new Promise((resolve, reject) => {
+    const id = ++nextId;
+    pending.set(id, { resolve, reject });
+    try { worker.postMessage({ id, action, input, url: main.dataset.index }); }
+    catch { failWorker(); }
+  });
+}
+const ready = call('init');
+const tool = {
+  name: 'search_arm_content',
+  description: 'Find Arm Learning Paths and install guides by keyword or author name, with word prefixes and limited typo tolerance. Relevance defaults to complete query matches first. Returns source URLs and metadata excerpts; use these sources to read the full instructions. Scores indicate keyword relevance, not confidence.',
+  inputSchema: { type: 'object', properties: {
+    query: { type: 'string', maxLength: 300, description: 'Leave empty to browse all content matching the filters, newest first.' },
+    type: { type: 'string', enum: ['', 'learning-path', 'install-guide'], default: '' },
+    category: { type: 'string', description: 'Learning Path category slug, such as servers-and-cloud-computing. Ignored when type is install-guide.' },
+    sort: { type: 'string', enum: ['relevance', 'updated'], default: 'relevance' },
+    offset: { type: 'integer', minimum: 0, default: 0, description: 'Number of results to skip for pagination.' },
+    limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 }
+  }, required: ['query'], additionalProperties: false },
+  annotations: { readOnlyHint: true },
+  async execute(input, { signal } = {}) {
+    try {
+      signal?.throwIfAborted();
+      await ready;
+      signal?.throwIfAborted();
+      const result = await call('search', input);
+      signal?.throwIfAborted();
+      return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      return { isError: true, content: [{ type: 'text', text: error.message }] };
+    }
+  }
+};
+// The tester and the registered tool invoke precisely the same callback.
+$('run-tool').onclick = async () => {
+  try { $('tool-output').textContent = JSON.stringify(await tool.execute(JSON.parse($('tool-input').value)), null, 2); }
+  catch (error) { $('tool-output').textContent = error.message; }
+};
+async function register() {
+  const context = document.modelContext || navigator.modelContext;
+  if (!context?.registerTool) {
+    $('webmcp').textContent = 'Native WebMCP is unavailable in this browser. Use the tool tester below.';
+    return;
+  }
+  try {
+    await context.registerTool(tool);
+    $('webmcp').textContent = 'WebMCP registered: search_arm_content';
+  } catch (error) { $('webmcp').textContent = `WebMCP registration failed: ${error.message}. The tester still works.`; }
+}
+register();
+async function render() {
+  const current = ++generation;
+  const query = $('query').value.trim();
+  $('clear-blank-search').hidden = !allowBlankSearch || $('query').value !== '';
+  $('category').disabled = $('type').value === 'install-guide';
+  if ($('category').disabled) $('category').value = '';
+  const params = new URLSearchParams();
+  if (query) params.set('q', query);
+  if ($('type').value) params.set('type', $('type').value);
+  if ($('category').value) params.set('category', $('category').value);
+  params.set('sort', $('sort').value);
+  history.replaceState(null, '', `${location.pathname}${params.size ? '?' + params : ''}${location.hash}`);
+  if (!offset) $('results').replaceChildren();
+  $('more').hidden = true;
+  $('search-diagnostics').hidden = true;
+  if (workerFailure) { $('status').textContent = workerFailure.message; return; }
+  if (!query && !allowBlankSearch) {
+    $('status').textContent = 'Enter a search term, or click Search to browse all content matching your filters.';
+    return;
+  }
+  if (query && !(query.toLowerCase().match(/[a-z0-9]+/g) || []).some(w => !searchStop.has(w))) {
+    $('status').textContent = `"${query}" contains only common words that search ignores. Try adding a more specific term.`;
+    return;
+  }
+  $('status').textContent = 'Searching…';
+  const start = performance.now();
+  try {
+    await ready;
+    const result = await call('search', { query, type: $('type').value, category: $('category').value, sort: $('sort').value, limit: 10, offset });
+    if (current !== generation) return;
+    $('status').textContent = `${result.total} result${result.total === 1 ? '' : 's'}${query ? ` for “${query}”` : ' · newest first'}`;
+    $('performance').textContent = `Last search: ${result.searchMs.toFixed(1)} ms engine · ${(performance.now() - start).toFixed(1)} ms response`;
+    $('search-diagnostics').hidden = false;
+    if (!result.total) $('status').textContent += query ? '. Try fewer words or remove a filter.' : '. Try removing a filter.';
+    if (result.total) $('status').textContent += `. Showing ${offset + result.results.length} of ${result.total}.`;
+    for (const record of result.results) {
+      const li = document.createElement('li'); li.className = 'search-result-card';
+      const a = document.createElement('a'); a.href = record.url; a.textContent = record.title;
+      const h = document.createElement('h3'); h.className = 'result-title'; h.append(a);
+      const meta = document.createElement('p'); meta.className = 'result-meta';
+      const badge = document.createElement('span'); badge.className = 'result-type';
+      badge.textContent = record.type === 'learning-path' ? 'Learning Path' : 'Install guide'; meta.append(badge);
+      if (record.category) { const category = document.createElement('span'); category.textContent = categoryLabel(record.category); meta.append(category); }
+      const p = document.createElement('p'); p.className = 'result-description'; p.textContent = record.description || record.summary;
+      const footer = document.createElement('div'); footer.className = 'result-footer';
+      if (record.authors?.length) { const authors = document.createElement('p'); authors.textContent = 'By ' + record.authors.join(', '); footer.append(authors); }
+      const updated = document.createElement('p');
+      if (record.lastUpdated) {
+        const time = document.createElement('time'); time.dateTime = record.lastUpdated;
+        time.textContent = new Date(record.lastUpdated + 'T00:00:00Z').toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' });
+        updated.append('Last updated: ', time);
+      } else { updated.textContent = 'Last updated: unavailable'; }
+      footer.append(updated); li.append(meta, h, p, footer); $('results').append(li);
+    }
+    $('more').hidden = result.total <= offset + result.results.length;
+    if (offset && result.results.length) { const firstNew = $('results').children[offset]; firstNew?.querySelector('a')?.focus(); }
+  } catch (error) { if (current === generation) $('status').textContent = error.message; }
+}
+function categoryLabel(slug) {
+  return slug.split('-').map((word, index) => index && ['and'].includes(word) ? word : word[0].toUpperCase() + word.slice(1)).join(' ');
+}
+for (const button of main.querySelectorAll('[data-query]')) button.onclick = () => {
+  $('query').value = button.dataset.query; $('type').value = ''; $('category').value = ''; offset = 0; render();
+};
+let timer;
+$('query').oninput = () => { $('clear-blank-search').hidden = true; allowBlankSearch = false; ++generation; $('more').hidden = true; clearTimeout(timer); $('results').replaceChildren(); $('search-diagnostics').hidden = true; if (!$('query').value) { offset = 0; $('status').textContent = 'Enter a search term, or click Search to browse all content matching your filters.'; } else { $('status').textContent = ''; } };
+$('search-form').onsubmit = event => { event.preventDefault(); allowBlankSearch = true; clearTimeout(timer); offset = 0; render(); };
+$('clear-blank-search').onclick = () => {
+  clearTimeout(timer);
+  allowBlankSearch = false;
+  $('query').value = '';
+  offset = 0;
+  render();
+  $('query').focus();
+};
+for (const id of ['type', 'category', 'sort']) $(id).onchange = () => { if (!$('query').value.trim()) allowBlankSearch = true; offset = 0; render(); };
+$('more').onclick = () => { offset += 10; render(); };
+const params = new URLSearchParams(location.search);
+$('query').value = (params.get('q') || '').slice(0, 300);
+if (['updated', 'relevance'].includes(params.get('sort'))) $('sort').value = params.get('sort');
+if (['learning-path', 'install-guide'].includes(params.get('type'))) $('type').value = params.get('type');
+try {
+  const info = await ready;
+  for (const category of info.categories) { const option = document.createElement('option'); option.value = category; option.textContent = categoryLabel(category); $('category').append(option); }
+  if (info.categories.includes(params.get('category'))) $('category').value = params.get('category');
+  $('metrics').textContent = `${info.count} documents · ${(info.bytes / 1024).toFixed(0)} KB index (uncompressed) · ${info.loadMs.toFixed(0)} ms to download and prepare`;
+  render();
+} catch (error) { $('status').textContent = `Unable to load search: ${error.message} Reload to retry.`; }

assets/search-lab/engine.mjs

@@ -0,0 +1,102 @@
+// Dependency-free BM25 baseline. Exact identifiers stay searchable alongside words.
+const stop = new Set('a an and are at be can do for from how i in is it me my of on or the to using what with'.split(' '));
+const aliases = new Map([['cpp', 'c++'], ['csharp', 'c#']]);
+export function tokenize(text) {
+  const tokens = String(text).toLowerCase().match(/[\p{L}\p{N}]+(?:[.+#-][\p{L}\p{N}+#]+)*#?/gu) || [];
+  return tokens.map(token => aliases.get(token) || token);
+}
+// One insertion, deletion, substitution, or adjacent transposition.
+function oneEditAway(a, b) {
+  if (Math.abs(a.length - b.length) > 1) return false;
+  let i = 0;
+  while (i < a.length && a[i] === b[i]) i++;
+  if (i === a.length) return b.length === a.length + 1;
+  if (a.length === b.length) {
+    return a.slice(i + 1) === b.slice(i + 1)
+      || (a[i] === b[i + 1] && a[i + 1] === b[i] && a.slice(i + 2) === b.slice(i + 2));
+  }
+  return a.length > b.length ? a.slice(i + 1) === b.slice(i) : a.slice(i) === b.slice(i + 1);
+}
+export function createEngine(records) {
+  const fields = [['title', 5], ['description', 3], ['authors', 3], ['metadata', 2], ['prerequisites', 2], ['summary', 1], ['faq', 1]];
+  const docs = records.map(record => ({ record, fields: fields.map(([key, boost]) => {
+    const value = record[key] || '';
+    const tokens = tokenize(Array.isArray(value) ? value.join(' ') : value);
+    const counts = new Map();
+    for (const token of tokens) counts.set(token, (counts.get(token) || 0) + 1);
+    return { counts, length: tokens.length, boost };
+  }) }));
+  const averages = fields.map((_, i) => docs.reduce((n, d) => n + d.fields[i].length, 0) / (docs.length || 1) || 1);
+  const df = new Map();
+  for (const doc of docs) {
+    const terms = new Set(doc.fields.flatMap(f => [...f.counts.keys()]));
+    for (const term of terms) df.set(term, (df.get(term) || 0) + 1);
+  }
+  const vocabulary = [...df.keys()];
+  return function search(input = {}) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw Error('Arguments must be an object.');
+    if (Object.keys(input).some(key => !['query', 'type', 'category', 'limit', 'offset', 'sort'].includes(key))) throw Error('Unknown search argument.');
+    const { query, type = '', category = '', limit = 10, offset = 0, sort = 'relevance' } = input;
+    if (typeof query !== 'string' || query.length > 300) throw Error('Query must be a string of at most 300 characters.');
+    if (!['', 'learning-path', 'install-guide'].includes(type)) throw Error('Unknown content type.');
+    if (typeof category !== 'string' || (category && !records.some(r => r.category === category))) throw Error('Unknown category.');
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw Error('Limit must be an integer from 1 to 100.');
+    if (!Number.isInteger(offset) || offset < 0) throw Error('Offset must be a non-negative integer.');
+    if (!['updated', 'relevance'].includes(sort)) throw Error('Unknown sort order.');
+    const terms = [...new Set(tokenize(query).filter(t => !stop.has(t)))];
+    const browsing = !query.trim();
+    if (!browsing && !terms.length) return { total: 0, results: [] };
+    const expansions = terms.map(term => {
+      const candidates = [{ token: term, weight: 1 }];
+      if (/^\p{L}{3,}$/u.test(term)) {
+        for (const token of vocabulary) {
+          if (token !== term && token.startsWith(term)) candidates.push({ token, weight: 0.65 });
+        }
+        // Correct a typo only when there is no exact token or prefix completion.
+        if (!df.has(term) && candidates.length === 1 && /^\p{L}{5,}$/u.test(term)) {
+          for (const token of vocabulary) {
+            if (/^\p{L}{5,}$/u.test(token) && oneEditAway(term, token)) candidates.push({ token, weight: 0.4 });
+          }
+        }
+      }
+      return candidates.map(candidate => ({ ...candidate,
+        idf: Math.log(1 + (docs.length - (df.get(candidate.token) || 0) + 0.5) / ((df.get(candidate.token) || 0) + 0.5))
+      }));
+    });
+    const ranked = [];
+    for (const doc of docs) {
+      if ((type && doc.record.type !== type) || (type !== 'install-guide' && category && doc.record.category !== category)) continue;
+      if (browsing) {
+        ranked.push({ record: { ...doc.record, score: 0 }, tier: 0 });
+        continue;
+      }
+      let score = 0, matched = 0, exact = 0;
+      for (const candidates of expansions) {
+        let termScore = 0;
+        let exactMatch = false;
+        doc.fields.forEach((field, i) => {
+          let best = 0;
+          for (const { token, weight, idf } of candidates) {
+            const tf = field.counts.get(token) || 0;
+            if (weight === 1 && tf) exactMatch = true;
+            best = Math.max(best, weight * field.boost * idf * tf * 2.2 / (tf + 1.2 * (0.25 + 0.75 * field.length / averages[i])));
+          }
+          termScore += best;
+        });
+        if (termScore) matched++;
+        if (exactMatch) exact++;
+        score += termScore;
+      }
+      // Reward coverage so long natural-language queries can still find partial matches.
+      if (matched) ranked.push({ record: { ...doc.record, score: score * (matched / terms.length) ** 2 },
+        tier: exact === terms.length ? 2 : matched === terms.length ? 1 : 0 });
+    }
+    ranked.sort((a, b) => {
+      // ISO date strings sort chronologically; missing dates follow dated results.
+      const dateOrder = (browsing || sort === 'updated') ? (b.record.lastUpdated || '').localeCompare(a.record.lastUpdated || '') : 0;
+      const coverageOrder = sort === 'relevance' ? b.tier - a.tier : 0;
+      return dateOrder || coverageOrder || b.record.score - a.record.score || a.record.id.localeCompare(b.record.id);
+    });
+    return { total: ranked.length, results: ranked.slice(offset, offset + limit).map(item => item.record) };
+  };
+}