@birdapi/velinstyle 1.1.0 → 1.2.1

package/core/transparency/registry.js

@@ -0,0 +1,104 @@
+/** In-memory disclosure registry. */
+
+/**
+ * @typedef {object} Provenance
+ * @property {string} [createdBy]
+ * @property {string} [createdAt]
+ * @property {string} [reviewedAt]
+ * @property {string} [approvedBy]
+ * @property {string} [source]
+ * @property {string} [license]
+ * @property {string} [version]
+ * @property {string} [publishedAt]
+ */
+
+/**
+ * @typedef {object} DisclosureRecord
+ * @property {string} id
+ * @property {string} [type]
+ * @property {string} [status]
+ * @property {string} [review]
+ * @property {string} provider
+ * @property {string[]} claims
+ * @property {Provenance} provenance
+ * @property {string} [updated]
+ * @property {string} [label]
+ * @property {string} [description]
+ * @property {string} [renderer]
+ * @property {string} [tone]
+ * @property {string} [position]
+ * @property {{ selector?: string, tag?: string, src?: string, file?: string }} [target]
+ * @property {Record<string, unknown>} [meta]
+ */
+
+export function createRegistry() {
+  /** @type {Map<string, DisclosureRecord>} */
+  const map = new Map();
+
+  return {
+    register(record) {
+      if (!record?.id) throw new Error('DisclosureRecord requires id');
+      map.set(record.id, structuredCloneSafe(record));
+      return map.get(record.id);
+    },
+    get(id) {
+      return map.get(id) || null;
+    },
+    has(id) {
+      return map.has(id);
+    },
+    remove(id) {
+      return map.delete(id);
+    },
+    list() {
+      return [...map.values()].map((r) => structuredCloneSafe(r));
+    },
+    query(predicate) {
+      return this.list().filter(predicate);
+    },
+    clear() {
+      map.clear();
+    },
+    size() {
+      return map.size;
+    },
+    export() {
+      return { schema: 'velinstyle.transparency.registry', version: 1, items: this.list() };
+    },
+    diff(otherList = []) {
+      const other = new Map(otherList.map((r) => [r.id, r]));
+      const added = [];
+      const removed = [];
+      const changed = [];
+      for (const r of map.values()) {
+        if (!other.has(r.id)) added.push(r.id);
+        else if (JSON.stringify(r) !== JSON.stringify(other.get(r.id))) changed.push(r.id);
+      }
+      for (const id of other.keys()) {
+        if (!map.has(id)) removed.push(id);
+      }
+      return { added, removed, changed };
+    },
+  };
+}
+
+function structuredCloneSafe(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * Stable id from target hints.
+ * @param {{ id?: string, selector?: string, src?: string, tag?: string, type?: string, file?: string }} parts
+ */
+export function stableDisclosureId(parts = {}) {
+  if (parts.id) return String(parts.id).trim();
+  const raw = [parts.file || '', parts.selector || '', parts.src || '', parts.tag || '', parts.type || '']
+    .join('|')
+    .toLowerCase();
+  let h = 2166136261;
+  for (let i = 0; i < raw.length; i += 1) {
+    h ^= raw.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return `tx-${(h >>> 0).toString(16)}`;
+}

package/core/transparency/renderer.js

@@ -0,0 +1,111 @@
+/** @type {Map<string, (el: HTMLElement, record: object) => void>} */
+const renderers = new Map();
+
+export function registerTransparencyRenderer(name, fn) {
+  renderers.set(name, fn);
+}
+
+export function listTransparencyRenderers() {
+  return [...renderers.keys()];
+}
+
+/**
+ * Render a disclosure mark onto an element.
+ * @param {HTMLElement} el
+ * @param {import('./registry.js').DisclosureRecord} record
+ */
+export function renderDisclosure(el, record) {
+  if (typeof document === 'undefined' || !el) return null;
+  const name = record.renderer || 'badge';
+  const custom = renderers.get(name);
+  if (custom) {
+    custom(el, record);
+    return el.querySelector('.velin-transparency');
+  }
+  return defaultRender(el, record);
+}
+
+function defaultRender(el, record) {
+  const cs = getComputedStyle(el);
+  if (cs.position === 'static') el.style.position = 'relative';
+
+  let mark = el.querySelector(':scope > .velin-transparency');
+  if (!mark) {
+    mark = document.createElement('div');
+    el.prepend(mark);
+  }
+
+  const renderer = record.renderer || 'badge';
+  const tone = record.tone || 'neutral';
+  const position = record.position || 'top-right';
+  mark.className = [
+    'velin-transparency',
+    `velin-transparency--${renderer}`,
+    `velin-transparency--tone-${tone}`,
+    `velin-transparency--pos-${position}`,
+  ].join(' ');
+  mark.setAttribute('data-velin-transparency-id', record.id);
+  mark.setAttribute('role', 'note');
+
+  const claimsText = (record.claims || []).join(', ');
+  const prov = record.provenance || {};
+  const sr = document.createElement('span');
+  sr.className = 'velin-sr-only';
+  const lang = (el.closest('[lang]')?.getAttribute('lang') || document.documentElement.lang || 'en').startsWith('de')
+    ? 'de'
+    : 'en';
+  sr.textContent = lang === 'de'
+    ? `Transparenzhinweis: ${record.label}. ${claimsText}. ${provenanceSr(prov, 'de')}`
+    : `Transparency notice: ${record.label}. ${claimsText}. ${provenanceSr(prov, 'en')}`;
+
+  const visible = document.createElement('span');
+  visible.className = 'velin-transparency__label';
+  visible.textContent = record.label || 'Transparency';
+
+  const details = document.createElement('span');
+  details.className = 'velin-transparency__details';
+  details.hidden = renderer === 'badge' || renderer === 'icon';
+  details.textContent = formatDetails(record, lang);
+
+  mark.replaceChildren(sr, visible, details);
+
+  if (record.description) mark.title = record.description;
+  else if (details.textContent) mark.title = details.textContent;
+
+  el.setAttribute('data-velin-transparency', record.id);
+  return mark;
+}
+
+function provenanceSr(p, lang) {
+  const parts = [];
+  if (p.createdBy) parts.push(lang === 'de' ? `Erstellt von ${p.createdBy}` : `Created by ${p.createdBy}`);
+  if (p.createdAt) parts.push(lang === 'de' ? `am ${p.createdAt}` : `on ${p.createdAt}`);
+  if (p.approvedBy) parts.push(lang === 'de' ? `Freigegeben von ${p.approvedBy}` : `Approved by ${p.approvedBy}`);
+  if (p.license) parts.push(p.license);
+  if (p.version) parts.push(`v${p.version}`);
+  return parts.join('. ');
+}
+
+function formatDetails(record, lang) {
+  const p = record.provenance || {};
+  const bits = [];
+  if (p.approvedBy) bits.push(lang === 'de' ? `Freigabe: ${p.approvedBy}` : `Approved: ${p.approvedBy}`);
+  if (p.license) bits.push(p.license);
+  if (p.version) bits.push(`v${p.version}`);
+  if (p.updated || record.updated) bits.push(record.updated || p.publishedAt || '');
+  return bits.filter(Boolean).join(' · ');
+}
+
+// Register alias names to default path
+for (const name of ['overlay', 'badge', 'inline', 'tooltip', 'footer', 'ribbon', 'panel', 'icon', 'corner-badge', 'stamp', 'sidebar', 'floating-card', 'banner']) {
+  registerTransparencyRenderer(name, (el, record) => {
+    defaultRender(el, { ...record, renderer: normalizeRendererName(name) });
+  });
+}
+
+function normalizeRendererName(name) {
+  if (name === 'corner-badge' || name === 'stamp') return 'badge';
+  if (name === 'floating-card' || name === 'sidebar') return 'panel';
+  if (name === 'banner') return 'footer';
+  return name;
+}

package/core/transparency/reporter.js

@@ -0,0 +1,113 @@
+/**
+ * Build report artifacts from a doctor result.
+ * @param {Awaited<ReturnType<import('./doctor.js').transparencyDoctor>>} report
+ * @param {{ title?: string }} [opts]
+ */
+export function buildTransparencyReports(report, opts = {}) {
+  const title = opts.title || 'Velin Transparency Report';
+  const json = {
+    schema: 'velinstyle.transparency.report',
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    title,
+    ...report,
+  };
+  const sarif = toSarif(report, title);
+  const html = toHtml(report, title);
+  return { json, sarif, html };
+}
+
+function toSarif(report, title) {
+  const results = (report.findings || []).map((f) => ({
+    ruleId: f.code,
+    level: f.severity === 'error' ? 'error' : f.severity === 'warning' ? 'warning' : 'note',
+    message: { text: f.message },
+    locations: f.id || f.target
+      ? [{
+        physicalLocation: {
+          artifactLocation: { uri: report.file || 'document.html' },
+          region: { snippet: { text: f.id || f.target?.src || '' } },
+        },
+      }]
+      : [],
+  }));
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'velinstyle-transparency',
+          informationUri: 'https://velinstyle.info',
+          rules: [],
+        },
+      },
+      results,
+      properties: { title, scores: report.scores },
+    }],
+  };
+}
+
+function toHtml(report, title) {
+  const scores = report.scores || {};
+  const rows = (report.findings || []).map((f) => `
+    <tr>
+      <td>${esc(f.severity)}</td>
+      <td><code>${esc(f.code)}</code></td>
+      <td>${esc(f.message)}</td>
+      <td>${esc(f.id || '')}</td>
+    </tr>`).join('');
+  const items = (report.registry?.items || []).map((r) => `
+    <tr>
+      <td><code>${esc(r.id)}</code></td>
+      <td>${esc(r.type)}</td>
+      <td>${esc(r.label)}</td>
+      <td>${esc((r.claims || []).join(', '))}</td>
+      <td>${esc(JSON.stringify(r.provenance || {}))}</td>
+    </tr>`).join('');
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>${esc(title)}</title>
+  <style>
+    body{font-family:system-ui,sans-serif;margin:2rem;background:#0c0b0a;color:#f5f2eb}
+    table{border-collapse:collapse;width:100%;margin-block:1rem}
+    th,td{border:1px solid #333;padding:.5rem;text-align:left;vertical-align:top}
+    th{background:#1a1917}
+    .scores{display:flex;flex-wrap:wrap;gap:.75rem}
+    .score{padding:.75rem 1rem;background:#1a1917;border-radius:8px;min-width:7rem}
+    .ok{color:#7ddea0}.bad{color:#f5a5a5}
+  </style>
+</head>
+<body>
+  <h1>${esc(title)}</h1>
+  <p class="${report.ok ? 'ok' : 'bad'}">${report.ok ? 'PASS' : 'FAIL'} — ${report.summary?.errors || 0} errors, ${report.summary?.warnings || 0} warnings</p>
+  <div class="scores">
+    ${scoreCard('Transparency', scores.transparency)}
+    ${scoreCard('AI', scores.ai)}
+    ${scoreCard('Trust', scores.trust)}
+    ${scoreCard('Metadata', scores.metadata)}
+    ${scoreCard('Compliance', scores.compliance)}
+    ${scoreCard('Provenance', scores.provenance)}
+  </div>
+  <h2>Findings</h2>
+  <table><thead><tr><th>Severity</th><th>Code</th><th>Message</th><th>Id</th></tr></thead><tbody>${rows || '<tr><td colspan="4">None</td></tr>'}</tbody></table>
+  <h2>Registry</h2>
+  <table><thead><tr><th>Id</th><th>Type</th><th>Label</th><th>Claims</th><th>Provenance</th></tr></thead><tbody>${items || '<tr><td colspan="5">Empty</td></tr>'}</tbody></table>
+</body>
+</html>`;
+}
+
+function scoreCard(name, value) {
+  const v = value == null ? '—' : `${value}%`;
+  return `<div class="score"><strong>${esc(name)}</strong><div>${v}</div></div>`;
+}
+
+function esc(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/core/transparency/validator.js

@@ -0,0 +1,112 @@
+import { CLAIM_CATALOG } from './claims.js';
+import { requiredProvenanceFields } from './policy.js';
+
+const VALID_STATUS = new Set([
+  'generated', 'assisted', 'ai-assisted', 'human-reviewed', 'human-edited', 'verified', 'edited', 'draft',
+]);
+const VALID_REVIEW = new Set(['human', 'human-reviewed', 'verified', 'none']);
+const VALID_TYPES = new Set([
+  'ai', 'trust', 'compliance', 'metadata', 'review', 'verification', 'license',
+  'accessibility', 'security', 'custom', 'image', 'video', 'audio', 'text', 'pdf', 'document',
+]);
+
+/**
+ * @param {import('./registry.js').DisclosureRecord} record
+ * @param {object} policy
+ */
+export function validateRecord(record, policy) {
+  const findings = [];
+  if (!record?.id) {
+    findings.push(finding('error', 'invalid.id', 'Disclosure missing id'));
+  }
+  if (record.type && !VALID_TYPES.has(String(record.type).toLowerCase())) {
+    findings.push(finding('warning', 'invalid.type', `Unknown type "${record.type}"`, record.id));
+  }
+  if (record.status && !VALID_STATUS.has(String(record.status).toLowerCase())) {
+    findings.push(finding('error', 'invalid.status', `Invalid status "${record.status}"`, record.id));
+  }
+  if (record.review && !VALID_REVIEW.has(String(record.review).toLowerCase())) {
+    findings.push(finding('error', 'invalid.review', `Invalid review "${record.review}"`, record.id));
+  }
+  if (!record.label) {
+    findings.push(finding('warning', 'missing.label', 'Missing label', record.id));
+  }
+  if (policy.rules?.requireReview && !record.review && !record.claims?.includes('review.human')) {
+    findings.push(finding('error', 'policy.requireReview', 'Policy requires review', record.id));
+  }
+  if (policy.rules?.allowGenerated === false && record.claims?.includes('ai.generated')) {
+    findings.push(finding('error', 'policy.allowGenerated', 'Generated content not allowed by policy', record.id));
+  }
+  if (policy.rules?.minimumStatus === 'human-reviewed') {
+    const ok = record.claims?.includes('review.human') || record.claims?.includes('review.verified')
+      || record.review === 'human' || record.review === 'human-reviewed' || record.review === 'verified';
+    if (!ok && (record.claims?.includes('ai.generated') || record.claims?.includes('ai.assisted'))) {
+      findings.push(finding('error', 'policy.minimumStatus', 'minimumStatus human-reviewed not met', record.id));
+    }
+  }
+  for (const claim of record.claims || []) {
+    if (!CLAIM_CATALOG[claim] && !String(claim).startsWith('custom.')) {
+      findings.push(finding('warning', 'unknown.claim', `Unknown claim "${claim}"`, record.id));
+    }
+  }
+  const mediaKind = inferMediaKind(record);
+  const required = requiredProvenanceFields(mediaKind, policy);
+  for (const field of required) {
+    if (!record.provenance?.[field]) {
+      findings.push(finding('error', `missing-provenance.${field}`, `Missing provenance.${field}`, record.id));
+    }
+  }
+  for (const field of policy.provenance?.recommended || []) {
+    if (!record.provenance?.[field]) {
+      findings.push(finding('info', `recommended-provenance.${field}`, `Recommended provenance.${field}`, record.id));
+    }
+  }
+  if (record.updated || record.provenance?.reviewedAt) {
+    const staleDays = policy.rules?.staleDays ?? 365;
+    const dateStr = record.provenance?.reviewedAt || record.updated;
+    const age = ageDays(dateStr);
+    if (age != null && age > staleDays) {
+      findings.push(finding('warning', 'stale-reviewedAt', `Review/update is ${age} days old (limit ${staleDays})`, record.id));
+    }
+  }
+  return findings;
+}
+
+/**
+ * @param {import('./registry.js').DisclosureRecord[]} records
+ * @param {object} policy
+ */
+export function validateRecords(records, policy) {
+  const findings = [];
+  const seen = new Map();
+  for (const r of records) {
+    if (seen.has(r.id)) {
+      findings.push(finding('error', 'duplicate.id', `Duplicate disclosure id "${r.id}"`, r.id));
+    }
+    seen.set(r.id, true);
+    findings.push(...validateRecord(r, policy));
+  }
+  return findings;
+}
+
+export function inferMediaKind(record) {
+  const tag = String(record.target?.tag || '').toUpperCase();
+  const type = String(record.type || '').toLowerCase();
+  const src = String(record.target?.src || '');
+  if (tag === 'IMG' || type === 'image' || /\.(png|jpe?g|webp|gif|svg)(\?|$)/i.test(src)) return 'images';
+  if (tag === 'VIDEO' || type === 'video' || /\.(mp4|webm|mov)(\?|$)/i.test(src)) return 'videos';
+  if (tag === 'AUDIO' || type === 'audio' || /\.(mp3|wav|ogg)(\?|$)/i.test(src)) return 'audio';
+  if (type === 'pdf' || /\.pdf(\?|$)/i.test(src)) return 'pdf';
+  return 'text';
+}
+
+function ageDays(dateStr) {
+  if (!dateStr) return null;
+  const t = Date.parse(dateStr);
+  if (Number.isNaN(t)) return null;
+  return Math.floor((Date.now() - t) / 86400000);
+}
+
+function finding(severity, code, message, id) {
+  return { severity, code, message, id: id || null };
+}