@jacebenson/jsn 4.3.8-dev.57 → 4.3.8-dev.59

package/README.md

@@ -50,8 +50,11 @@ lifecycle commands and the untested Windows host phases. Docker remains availabl
 jsn customizations capture --label before-upgrade --customer-scope x_acme_app
 jsn customizations list
 jsn customizations show <run_id>
+jsn customizations html <run_id>                 # writes customizations-<run_id>.html
+jsn customizations html <run_id> --out review.html
 jsn customizations compare <baseline_id> <new_id> --json
 jsn customizations show <run_id> --get data.coverage
+jsn customizations show <run_id> --get data.triage
 ```
 
 Capture data access uses Table API GET requests only. Captures never run
@@ -88,6 +91,13 @@ review recommendation. Historical OOTB findings include the known skipped-upgrad
 impact and explicit unknown baseline, runtime impact and dependencies. No
 reversion is performed or recommended as safe without further investigation.
 
+`show` adds a computed `data.triage` view with evidence confidence, the reason for
+the classification and concrete review steps; it does not alter saved captures or
+pretend to score risk. `html` exports a self-contained offline report with search,
+classification filters, grouping, evidence, coverage and links back to records.
+The default output is `customizations-<run_id>.html`; existing files are never
+overwritten. The report does not change ServiceNow records.
+
 Defaults are 100 records per page and 10 pages per source. Adjust `--page-size`
 and `--max-pages` within the documented limits. Source coverage compares the rows
 fetched with the Stats API count for the same query and reports both. A page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.8-dev.57",
+  "version": "4.3.8-dev.59",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/skills/servicenow/SKILL.md

@@ -79,6 +79,8 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 jsn customizations capture --label review --customer-scope x_acme_app --json
 jsn customizations list --json
 jsn customizations show <run_id> --get data.categories
+jsn customizations show <run_id> --get data.triage
+jsn customizations html <run_id> [--out review.html]
 jsn customizations compare <baseline_id> <new_id> --json
 ```
 

package/src/commands/customizations.js

@@ -3,6 +3,7 @@ import { errUsageHint, errUsage } from '../errors.js';
 import { canUsePicker } from '../helpers.js';
 import { paginatedSearch } from '../paginated-search.js';
 import { captureReport, listReports, getReport, compareReports, formatReport, formatReportList, formatReportComparison } from '../customizations.js';
+import { buildActionableReport, writeCustomizationHtml } from '../customizations-report.js';
 
 // Only capture needs an instance. Saved reports never need network access.
 declareCapabilities('customizations', { noInstance: true, skipDailyChecks: true, mutationSubcommands: [] });
@@ -21,8 +22,10 @@ async function pickReport(app, argv, exclude = null, message = 'Select a customi
   const picked = await paginatedSearch({ message, totalCount: runs.length, pageSize: 10, source: async (term = '') => runs.filter(run => `${run.run_id} ${run.label} ${run.instance}`.toLowerCase().includes(term.toLowerCase())).map(run => ({ name: `${run.run_id} ${run.label || '(unlabeled)'} ${run.instance}`, value: run })) });
   return picked?.value ? requireReport(picked.value.run_id) : null;
 }
-function show(app, report) {
-  app.ok({ ...report, _formatted: formatReport(report) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
+function show(app, report, options = {}) {
+  const actionable = buildActionableReport(report);
+  const triage = actionable.artifacts.map(({ category, category_label, identity, triage: classification }) => ({ category, category_label, identity, ...classification }));
+  app.ok({ ...report, triage, _formatted: formatReport(report, options) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
 }
 export function customizationsCmd(wrap) {
   return {
@@ -50,9 +53,18 @@ export function customizationsCmd(wrap) {
           app.ok({ runs, count: runs.length, _formatted: formatReportList(runs) }, { summary: `${runs.length} customization capture(s)`, breadcrumbs: [listHint, ...(runs[0] ? [showHint(runs[0].run_id)] : [])] });
         }),
       })
-      .command({ command: 'show [run_id]', describe: 'Review a saved capture offline', handler: wrap(async (argv, app) => {
+      .command({ command: 'show [run_id]', describe: 'Review a saved capture offline', builder: b => b
+        .option('group-by', { type: 'string', choices: ['type', 'scope', 'updated-by'], default: 'type', describe: 'Group summary by file type, scope or last updater' })
+        .option('filter', { type: 'string', describe: 'Expand a group shown in the summary (friendly or table name for file types)' }), handler: wrap(async (argv, app) => {
         const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
-        if (report) show(app, report);
+        if (report) show(app, report, { groupBy: argv.groupBy, filter: argv.filter || '' });
+      }) })
+      .command({ command: 'html [run_id]', describe: 'Write a searchable, self-contained HTML review of a saved capture', builder: b => b
+        .option('out', { type: 'string', describe: 'Output HTML path (must not already exist)' }), handler: wrap(async (argv, app) => {
+        const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
+        if (!report) return;
+        const file = writeCustomizationHtml(report, { out: argv.out });
+        app.ok({ run_id: report.run_id, file, artifacts: Object.values(report.categories).reduce((total, items) => total + items.length, 0) }, { summary: `Wrote offline customization review: ${file}`, breadcrumbs: [listHint, showHint(report.run_id)] });
       }) })
       .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance', handler: wrap(async (argv, app) => {
         if (!!argv.baseline !== !!argv.new) throw errUsage('Compare requires exactly two report IDs');
@@ -65,6 +77,6 @@ export function customizationsCmd(wrap) {
         const result = compareReports(baseline, newer);
         app.ok({ ...result, _formatted: formatReportComparison(result) }, { summary: `Customization comparison: ${result.status}`, breadcrumbs: [listHint, showHint(baseline.run_id), showHint(newer.run_id)] });
       }) }),
-    handler: wrap(async (_argv, app) => app.ok({ command: 'customizations', subcommands: ['capture', 'list', 'show', 'compare'] }, { summary: 'Use `jsn customizations <subcommand> --help` for details.' })),
+    handler: wrap(async (_argv, app) => app.ok({ command: 'customizations', subcommands: ['capture', 'list', 'show', 'html', 'compare'] }, { summary: 'Use `jsn customizations <subcommand> --help` for details.' })),
   };
 }

package/src/customizations-report.js

@@ -0,0 +1,158 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CLASSIFICATIONS = {
+  ootb_modifications: {
+    label: 'Historical upgrade skip',
+    confidence: 'Historical evidence only',
+    summary: 'An upgrade record says the platform preserved this artifact. That does not prove it currently differs from the vendor version.',
+    next_steps: [
+      'Compare the current artifact with a trusted baseline for this exact release.',
+      'Review later update-set history for a merge, reversion, or further edit.',
+      'Check callers and add a regression test in non-production before considering a revert.',
+    ],
+  },
+  customer_app_artifacts: {
+    label: 'Caller-declared customer scope',
+    confidence: 'Declaration, not verified ownership',
+    summary: 'The scope record matched a scope declared by the person who captured this report. The instance does not verify customer or publisher ownership.',
+    next_steps: [
+      'Confirm the application owner and publisher with the responsible team.',
+      'Check whether the artifact is active or referenced, then review its tests and update-set history.',
+      'Treat it as customer-owned only after an owner confirms the declaration.',
+    ],
+  },
+  unclassified: {
+    label: 'Unclassified metadata',
+    confidence: 'Insufficient evidence',
+    summary: 'Visible metadata was found, but this capture could not establish whether it is customer-owned or differs from an out-of-box artifact.',
+    next_steps: [
+      'Identify the owner using application records, update-set history, and team knowledge.',
+      'Check current references and expected behavior before changing or deleting it.',
+      'Compare with a trusted vendor baseline only when evidence shows this is vendor-delivered.',
+    ],
+  },
+};
+
+const humanize = value => String(value || '').replace(/^sys_/, '').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replaceAll('_', ' ').replace(/\bui\b/gi, 'UI').replace(/\b[a-z]/g, letter => letter.toUpperCase());
+const categoryLabel = category => ({ ootb_modifications: 'Historical upgrade skips', customer_app_artifacts: 'Declared customer scopes', unclassified: 'Unclassified metadata' })[category] || humanize(category);
+const itemName = item => {
+  const { name = '', update_name: updateName = '', table = '', sys_id: sysId = '' } = item.identity || {};
+  if (name && name !== sysId && name !== updateName) return /[_]|[a-z][A-Z]/.test(name) ? humanize(name) : name;
+  if (updateName) {
+    const prefixes = [table, table.replace(/_[^_]+$/, ''), table.replace(/_[^_]+_[^_]+$/, '')].filter(Boolean);
+    const prefix = prefixes.find(candidate => updateName.startsWith(`${candidate}_`));
+    return humanize(prefix ? updateName.slice(prefix.length + 1) : updateName) || 'Name unavailable';
+  }
+  return sysId ? 'Name unavailable' : 'Unnamed artifact';
+};
+
+export function classifyCustomization(category) {
+  const classification = CLASSIFICATIONS[category] || CLASSIFICATIONS.unclassified;
+  return {
+    code: CLASSIFICATIONS[category] ? category : 'unclassified',
+    label: classification.label,
+    confidence: classification.confidence,
+    summary: classification.summary,
+    next_steps: [...classification.next_steps],
+    // There is no verified baseline or dependency graph to support safe automatic remediation.
+    automated_remediation: false,
+  };
+}
+
+function recordUrl(instance, table, sysId) {
+  if (!/^[a-z0-9_]+$/i.test(String(table || '')) || !sysId) return null;
+  try {
+    const url = new URL(`${encodeURIComponent(table)}.do`, `${String(instance).replace(/\/+$/, '')}/`);
+    if (!['http:', 'https:'].includes(url.protocol)) return null;
+    url.searchParams.set('sys_id', String(sysId));
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+export function buildActionableReport(report) {
+  const artifacts = Object.entries(report.categories || {}).flatMap(([category, items]) => items.map(item => ({
+    category,
+    category_label: categoryLabel(category),
+    identity: item.identity || {},
+    name: itemName(item),
+    table_label: humanize(item.identity?.table || 'unknown'),
+    scope: item.scope?.scope || item.scope?.sys_id || '(unknown scope)',
+    updated_by: item.identity?.updated_by || '(unknown updater)',
+    evidence: item.evidence || [],
+    risk: item.risk || { rating: 'unknown', rationale: 'Risk has not been established.' },
+    triage: classifyCustomization(category),
+    record_url: recordUrl(report.instance, item.identity?.table, item.identity?.sys_id),
+  })));
+  return {
+    run_id: report.run_id,
+    label: report.label || '',
+    instance: report.instance,
+    status: report.status,
+    start_time: report.start_time,
+    artifacts,
+    coverage: report.coverage,
+  };
+}
+
+const safeJson = value => JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, character => ({ '<': '\\u003c', '>': '\\u003e', '&': '\\u0026', '\u2028': '\\u2028', '\u2029': '\\u2029' })[character]);
+const escapeHtml = value => String(value ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;');
+
+export function renderCustomizationHtml(report) {
+  const view = buildActionableReport(report);
+  const categoryOptions = [...new Set(view.artifacts.map(item => item.category))].map(category => `<option value="${escapeHtml(category)}">${escapeHtml(categoryLabel(category))}</option>`).join('');
+  const data = safeJson(view);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Customization review${view.label ? `: ${escapeHtml(view.label)}` : ''}</title>
+<style>
+:root{color-scheme:light;--ink:#202833;--muted:#526173;--line:#d8dee7;--panel:#fff;--wash:#f3f6fa;--blue:#1358a5;--amber:#825300}*{box-sizing:border-box}body{margin:0;background:var(--wash);color:var(--ink);font:16px/1.5 system-ui,sans-serif}main{max-width:1180px;margin:auto;padding:32px 20px 60px}h1,h2,h3,p{margin-top:0}h1{font-size:1.8rem;margin-bottom:4px}h2{font-size:1.25rem;margin:0 0 14px}h3{font-size:1.1rem;margin:0}small,.muted{color:var(--muted)}.intro,.toolbar,.coverage,.group,.card{background:var(--panel);border:1px solid var(--line);border-radius:10px}.intro,.toolbar,.coverage{padding:18px 20px;margin-bottom:16px}.intro p:last-child{margin-bottom:0}.stats{display:flex;flex-wrap:wrap;gap:10px;margin-top:14px}.stat{background:var(--wash);border-radius:8px;padding:10px 14px}.toolbar{display:flex;flex-wrap:wrap;gap:12px;align-items:end;position:sticky;top:0;z-index:2}.control{display:grid;gap:4px}.control.grow{flex:1;min-width:220px}input,select{font:inherit;padding:8px 10px;border:1px solid #aeb9c7;border-radius:6px;background:white;color:var(--ink)}.group{padding:18px;margin:16px 0}.group>h2{border-bottom:1px solid var(--line);padding-bottom:10px}.card{padding:16px;margin:12px 0}.card-head{display:flex;gap:12px;align-items:flex-start;justify-content:space-between}.badge{display:inline-block;border-radius:100px;background:#e9f0fb;color:#183e71;padding:3px 9px;font-size:.83rem;font-weight:650}.confidence{color:var(--amber);font-size:.9rem;font-weight:650}.meta{display:flex;gap:8px 16px;flex-wrap:wrap;margin:10px 0;color:var(--muted);font-size:.92rem}.card h4{margin:12px 0 4px}.card ul{margin:4px 0 12px;padding-left:22px}.card a{color:var(--blue)}.coverage summary{cursor:pointer;font-weight:650}.coverage li{margin:6px 0}.empty{padding:20px;text-align:center;color:var(--muted)}.notice{border-left:4px solid #d39219;padding:8px 12px;background:#fff7e6;margin:12px 0}
+</style>
+</head>
+<body><main>
+<header class="intro"><h1>Customization review</h1><p>${escapeHtml(view.label || view.run_id)} · ${escapeHtml(view.instance)}</p><p class="muted">Status: ${escapeHtml(view.status)}. This report gives review steps, not automatic fixes. Confirm evidence before changing records.</p><div class="stats" id="stats"></div><p class="notice">A historical upgrade skip does not prove a current difference. A scope or updater name does not prove ownership. The broad metadata source is a bounded sample.</p></header>
+<section class="toolbar" aria-label="Report filters"><label class="control grow">Search artifacts<input id="search" type="search" placeholder="Name, table, scope, updater, evidence"></label><label class="control">Classification<select id="category"><option value="">All classifications</option>${categoryOptions}</select></label><label class="control">Group by<select id="group-by"><option value="type">File type</option><option value="scope">Scope</option><option value="updated_by">Updated by</option></select></label></section>
+<section id="results" aria-live="polite"></section>
+<details class="coverage"><summary>Capture coverage and limitations</summary><div id="coverage-content"></div></details>
+<script id="report-data" type="application/json">${data}</script>
+<script>
+'use strict';
+const report=JSON.parse(document.getElementById('report-data').textContent);
+const results=document.getElementById('results');
+const search=document.getElementById('search');
+const category=document.getElementById('category');
+const groupBy=document.getElementById('group-by');
+const el=(tag,text,className='')=>{const node=document.createElement(tag);if(text!==undefined)node.textContent=text;if(className)node.className=className;return node;};
+const groupName=item=>groupBy.value==='scope'?item.scope:groupBy.value==='updated_by'?item.updated_by:item.table_label;
+const addList=(parent,title,items)=>{parent.append(el('h4',title));const ul=el('ul');for(const text of items)ul.append(el('li',text));parent.append(ul);};
+function card(item){
+ const article=el('article',undefined,'card');const head=el('div',undefined,'card-head');const title=el('h3',item.name);head.append(title,el('span',item.triage.confidence,'confidence'));article.append(head);
+ article.append(el('p',item.triage.summary));const meta=el('div',undefined,'meta');meta.append(el('span',item.table_label+' · '+(item.identity.sys_id||'ID unavailable')),el('span','Scope: '+item.scope),el('span','Updated by: '+item.updated_by));article.append(meta,el('span',item.category_label,'badge'));
+ addList(article,'Evidence',item.evidence.length?item.evidence.map(e=>e.source+': '+e.sys_id+'. '+e.basis):['No artifact evidence was captured.']);addList(article,'Next steps',item.triage.next_steps);article.append(el('p','Risk: '+(item.risk.rating||'unknown')+'. '+(item.risk.rationale||'Not established.')));
+ if(item.record_url){const link=el('a','Open record in ServiceNow');link.href=item.record_url;link.rel='noopener noreferrer';link.target='_blank';article.append(link);}return article;
+}
+function render(){
+ const term=search.value.trim().toLowerCase();const selected=category.value;
+ const filtered=report.artifacts.filter(item=>(!selected||item.category===selected)&&(!term||JSON.stringify(item).toLowerCase().includes(term)));
+ results.replaceChildren();if(!filtered.length){results.append(el('p','No artifacts match these filters.','empty'));return;}
+ const groups=new Map();for(const item of filtered){const key=groupName(item);if(!groups.has(key))groups.set(key,[]);groups.get(key).push(item);}
+ for(const [name,items] of [...groups].sort(([a],[b])=>a.localeCompare(b))){const section=el('section',undefined,'group');section.append(el('h2',name+' ('+items.length+')'));for(const item of items)section.append(card(item));results.append(section);}
+}
+for(const [categoryName,items] of Object.entries(report.artifacts.reduce((groups,item)=>{groups[item.category]=(groups[item.category]||0)+1;return groups;},{})))document.getElementById('stats').append(el('span',categoryName.replaceAll('_',' ')+': '+items,'stat'));
+search.addEventListener('input',render);category.addEventListener('change',render);groupBy.addEventListener('change',render);render();
+const coverage=document.getElementById('coverage-content');const ul=el('ul');for(const [source,details] of Object.entries(report.coverage.sources||{})){ul.append(el('li',source+': '+details.status+', '+details.fetched+'/'+(details.available??'unknown')+' rows. '+details.reason));}coverage.append(ul);for(const note of report.coverage.limitations||[])coverage.append(el('p',note));
+</script>
+</main></body></html>\n`;
+}
+
+export function writeCustomizationHtml(report, { out } = {}) {
+  const runId = String(report.run_id || 'capture').replace(/[^a-zA-Z0-9_-]/g, '_');
+  const target = path.resolve(out || path.join(process.cwd(), `customizations-${runId}.html`));
+  fs.writeFileSync(target, renderCustomizationHtml(report), { mode: 0o600, flag: 'wx' });
+  return target;
+}

package/src/customizations.js

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { getVersion } from './commands/version.js';
+import { classifyCustomization } from './customizations-report.js';
 
 // Raw provider choices: 4 = Skipped, 104 = Skipped (second pass). Other skip
 // dispositions do not establish a preserved customization, so the upgrade
@@ -14,7 +15,7 @@ export const SKIP_DISPOSITIONS = ['4', '104'];
 const SKIP_QUERY = `dispositionIN${SKIP_DISPOSITIONS.join(',')}`;
 const SOURCES = {
   sys_scope: { fields: 'sys_id,name,scope,sys_class_name', query: 'ORDERBYsys_id', countQuery: '', kind: 'inventory read' },
-  sys_metadata: { fields: 'sys_id,sys_name,sys_class_name,sys_scope,sys_update_name,sys_updated_on', query: 'ORDERBYsys_id', countQuery: '', kind: 'bounded sample' },
+  sys_metadata: { fields: 'sys_id,sys_name,sys_class_name,sys_scope,sys_update_name,sys_updated_on,sys_updated_by', query: 'ORDERBYsys_id', countQuery: '', kind: 'bounded sample' },
   sys_upgrade_history_log: { fields: 'sys_id,file_name,disposition,resolution_status,sys_updated_on', query: `${SKIP_QUERY}^ORDERBYsys_id`, countQuery: SKIP_QUERY, kind: 'inventory read' },
 };
 // The broad sys_metadata read is an arbitrary sys_id-ordered slice of a table
@@ -27,6 +28,19 @@ export const RESOLUTION_CHUNK_SIZE = 25;
 const RESOLUTION_MAX_PAGES = 3;
 const value = v => v && typeof v === 'object' ? v.value ?? '' : v ?? '';
 const text = v => String(value(v));
+const humanize = value => String(value || '').replace(/^sys_/, '').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replaceAll('_', ' ').replace(/\bui\b/gi, 'UI').replace(/\b[a-z]/g, letter => letter.toUpperCase());
+const friendlyTable = table => humanize(table) || 'Unknown type';
+const friendlyArtifactName = (name, updateName, table, sysId) => {
+  if (name && name !== sysId && name !== updateName) return /[_]|[a-z][A-Z]/.test(name) ? humanize(name) : name;
+  if (updateName) {
+    const prefixes = [table, table.replace(/_[^_]+$/, ''), table.replace(/_[^_]+_[^_]+$/, '')].filter(Boolean);
+    const prefix = prefixes.find(candidate => updateName.startsWith(`${candidate}_`));
+    const fallback = prefix ? updateName.slice(prefix.length + 1) : updateName;
+    return humanize(fallback) || 'Name unavailable';
+  }
+  return sysId ? 'Name unavailable' : 'Unnamed artifact';
+};
+const displayArtifactName = identity => friendlyArtifactName(identity?.name || '', identity?.update_name || '', identity?.table || '', identity?.sys_id || '');
 
 // How many rows are available for the same query? The Stats API count is the
 // only evidence that lets a capture claim completeness; without it coverage
@@ -281,7 +295,7 @@ export function compareReports(baseline, newer) {
     unknowns };
 }
 
-export function formatReport(report) {
+function formatReportDetailed(report) {
   const lines = [`Customization capture ${report.run_id}${report.label ? ` (${report.label})` : ''}`, `Instance: ${report.instance}`, `Status: ${report.status}`, '', 'COVERAGE'];
   for (const [source, coverage] of Object.entries(report.coverage.sources)) lines.push(`${source}${coverage.kind ? ` [${coverage.kind}]` : ''}: ${coverage.status}, ${coverage.fetched} fetched of ${coverage.available === null || coverage.available === undefined ? 'unknown' : coverage.available} available. ${coverage.reason}`);
   for (const limitation of report.coverage.limitations) lines.push(`Unknown: ${limitation}`);
@@ -295,7 +309,7 @@ export function formatReport(report) {
   for (const [category, items] of Object.entries(report.categories)) {
     lines.push('', `${category.toUpperCase()} (${items.length})`);
     for (const item of items) {
-      lines.push(`${item.identity.table}:${item.identity.sys_id} ${item.identity.name}`, `  Scope: ${item.scope.scope || item.scope.sys_id || 'unknown'}`, `  Risk: ${item.risk.rating}. ${item.risk.rationale}`);
+      lines.push(`${friendlyTable(item.identity.table)}:${item.identity.sys_id} ${displayArtifactName(item.identity)}`, `  Scope: ${item.scope.scope || item.scope.sys_id || 'unknown'}`, `  Risk: ${item.risk.rating}. ${item.risk.rationale}`);
       for (const evidence of item.evidence) lines.push(`  Evidence: ${evidence.source}:${evidence.sys_id}. ${evidence.basis}`);
       if (item.reversion) {
         for (const impact of item.reversion.known_impact) lines.push(`  Known impact: ${impact}`);
@@ -303,11 +317,51 @@ export function formatReport(report) {
         for (const unknown of item.reversion.unknowns) lines.push(`  Reversion unknown: ${unknown}`);
       }
       for (const unknown of item.unknowns) lines.push(`  Unknown: ${unknown}`);
+      const triage = classifyCustomization(category);
+      lines.push(`  Triage: ${triage.label} (${triage.confidence})`, `  Why: ${triage.summary}`);
+      for (const step of triage.next_steps) lines.push(`  Next: ${step}`);
       lines.push(`  Recommendation: ${item.recommendation}`);
     }
   }
   return lines.join('\n') + '\n';
 }
+export const CUSTOMIZATION_GROUPS = ['type', 'scope', 'updated-by'];
+function groupKey(item, groupBy) {
+  if (groupBy === 'scope') return item.scope?.scope || item.scope?.sys_id || '(unknown scope)';
+  if (groupBy === 'updated-by') return item.identity?.updated_by || '(unknown updater)';
+  return item.identity?.table || 'unknown';
+}
+export function formatReport(report, { groupBy = 'type', filter = '' } = {}) {
+  if (!CUSTOMIZATION_GROUPS.includes(groupBy)) throw new Error(`group-by must be one of: ${CUSTOMIZATION_GROUPS.join(', ')}`);
+  if (filter) {
+    const filtered = structuredClone(report);
+    for (const [category, items] of Object.entries(filtered.categories)) filtered.categories[category] = items.filter(item => {
+      const key = groupKey(item, groupBy);
+      return key.toLowerCase() === String(filter).toLowerCase() || (groupBy === 'type' && friendlyTable(key).toLowerCase() === String(filter).toLowerCase());
+    });
+    const text = formatReportDetailed(filtered);
+    return `${text}\nFiltered by ${groupBy}: ${filter}\n`;
+  }
+  const items = Object.values(report.categories).flat();
+  const groups = new Map();
+  for (const item of items) {
+    const key = groupKey(item, groupBy);
+    groups.set(key, (groups.get(key) || 0) + 1);
+  }
+  const label = { type: 'file type', scope: 'scope', 'updated-by': 'updated by' }[groupBy];
+  const lines = [`Customization capture ${report.run_id}${report.label ? ` (${report.label})` : ''}`, `Instance: ${report.instance}`, `Status: ${report.status}`, `Artifacts: ${items.length}`, '', `GROUPED BY ${label.toUpperCase()}`];
+  if (!groups.size) lines.push('(no artifacts)');
+  for (const [key, count] of [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const byCategory = Object.entries(report.categories).map(([category, records]) => [category.replaceAll('_', ' '), records.filter(item => groupKey(item, groupBy) === key).length]).filter(([, total]) => total > 0).map(([category, total]) => `${category} ${total}`).join(', ');
+    lines.push(`${groupBy === 'type' ? friendlyTable(key) : key} (${count})  ${byCategory}`);
+  }
+  lines.push('', 'Expand a group with --filter <group-name>. File-type filters accept the friendly label or table name. Regroup with --group-by scope or --group-by updated-by.', 'Examples:', `  jsn customizations show ${report.run_id} --filter "Script Include"`, `  jsn customizations show ${report.run_id} --group-by scope`, `  jsn customizations show ${report.run_id} --group-by updated-by`);
+  lines.push('', 'Coverage and limitations are shared across these artifacts.');
+  for (const [source, coverage] of Object.entries(report.coverage.sources)) lines.push(`${source}: ${coverage.status}, ${coverage.fetched}/${coverage.available ?? 'unknown'} rows${coverage.kind ? ` (${coverage.kind})` : ''}`);
+  lines.push('Limits: metadata is a bounded sample; skipped-upgrade evidence is historical, not proof of a current OOTB difference. Scope and updater are clues, not proof of ownership.');
+  return lines.join('\n') + '\n';
+}
+
 export function formatReportList(runs) {
   return ['RUN ID  STATUS  LABEL  INSTANCE', ...runs.map(run => `${run.run_id}  ${run.status}  ${run.label || '(unlabeled)'}  ${run.instance}`), ...(runs.length ? [] : ['(no customization captures)'])].join('\n') + '\n';
 }
@@ -408,7 +462,7 @@ export async function captureCustomizations({ sdk, customerScopes = [], pageSize
     const scopeId = text(row.sys_scope);
     const scope = scopes.get(scopeId);
     const scopeName = text(scope?.scope);
-    const identity = { sys_id: text(row.sys_id), table: text(row.sys_class_name) || 'unknown', name: text(row.sys_name) || text(row.sys_update_name) || text(row.sys_id), update_name: text(row.sys_update_name) };
+    const identity = { sys_id: text(row.sys_id), table: text(row.sys_class_name) || 'unknown', name: text(row.sys_name) || text(row.sys_update_name) || text(row.sys_id), update_name: text(row.sys_update_name), updated_by: text(row.sys_updated_by) || null };
     const evidence = [{ source: 'sys_metadata', sys_id: identity.sys_id, basis: 'Visible application metadata record', updated_on: text(row.sys_updated_on) }];
     const item = {
       identity, scope: { sys_id: scopeId || null, name: text(scope?.name) || null, scope: scopeName || null }, evidence,