@birdapi/velinstyle 1.1.0 → 1.2.1

package/core/transparency/index.js

@@ -0,0 +1,30 @@
+export { CLAIM_CATALOG, deriveClaims, claimLabel, primaryLabel, pillarForClaim } from './claims.js';
+export {
+  DEFAULT_POLICY,
+  STRICT_MEDIA_POLICY,
+  normalizePolicy,
+  mediaRequirement,
+  requiredProvenanceFields,
+  providerRank,
+} from './policy.js';
+export { createRegistry, stableDisclosureId } from './registry.js';
+export { normalizeDisclosure, mergeDisclosures } from './normalize.js';
+export {
+  registerTransparencyProvider,
+  listTransparencyProviders,
+  getTransparencyProvider,
+  collectAllDisclosures,
+  collectFromHtmlString,
+} from './providers.js';
+export { validateRecord, validateRecords, inferMediaKind } from './validator.js';
+export { transparencyDoctor } from './doctor.js';
+export { buildTransparencyReports } from './reporter.js';
+export { exportDisclosures } from './export.js';
+export { transparencyMigrate } from './migrate.js';
+export { createTransparencyEngine, TransparencyMIME } from './engine.js';
+export {
+  registerTransparencyRenderer,
+  listTransparencyRenderers,
+  renderDisclosure,
+} from './renderer.js';
+export { attach, enhanceAll, getDefaultRegistry, VelinTransparency } from './attach.js';

package/core/transparency/migrate.js

@@ -0,0 +1,130 @@
+import { transparencyDoctor } from './doctor.js';
+import { stableDisclosureId } from './registry.js';
+
+/**
+ * Analyze HTML and suggest disclosures + optional apply.
+ * @param {string} html
+ * @param {{ policy: object, file?: string, apply?: boolean, dryRun?: boolean }} opts
+ */
+export async function transparencyMigrate(html, opts) {
+  const doctor = await transparencyDoctor(html, opts);
+  const suggestions = [];
+
+  for (const f of doctor.findings) {
+    if (!String(f.code).startsWith('missing-disclosure.')) continue;
+    const target = f.target || {};
+    const kind = f.code.replace('missing-disclosure.', '');
+    const type = kind === 'images' || kind === 'videos' || kind === 'audio' ? 'ai' : kind === 'pdf' ? 'license' : 'ai';
+    const id = stableDisclosureId({
+      id: target.id,
+      src: target.src,
+      tag: target.tag,
+      type,
+      file: opts.file,
+    });
+    const attrs = {
+      'velin-transparency': '',
+      'velin-transparency-id': id,
+      'velin-type': type,
+      'velin-status': type === 'ai' ? 'generated' : 'verified',
+      'velin-review': 'human-reviewed',
+    };
+    if (kind === 'images' || kind === 'pdf') {
+      attrs['velin-created-at'] = new Date().toISOString().slice(0, 10);
+      attrs['velin-license'] = 'CC BY 4.0';
+    }
+    if (kind === 'images') attrs['velin-source'] = target.src || '';
+    suggestions.push({
+      id,
+      kind,
+      target,
+      attrs,
+      reason: f.message,
+    });
+  }
+
+  // Provenance gaps on existing disclosures
+  for (const f of doctor.findings) {
+    if (!String(f.code).startsWith('missing-provenance.')) continue;
+    const field = f.code.replace('missing-provenance.', '');
+    suggestions.push({
+      id: f.id,
+      kind: 'provenance',
+      field,
+      attrs: { [`velin-${kebab(field)}`]: field === 'license' ? 'CC BY 4.0' : field.includes('At') ? new Date().toISOString().slice(0, 10) : 'unknown' },
+      reason: f.message,
+    });
+  }
+
+  let nextHtml = html;
+  let applied = 0;
+  if (opts.apply && opts.dryRun !== true) {
+    const result = applySuggestions(html, suggestions.filter((s) => s.kind !== 'provenance' || s.target));
+    nextHtml = result.html;
+    applied = result.applied;
+    // provenance-only patches on existing tags
+    for (const s of suggestions.filter((x) => x.kind === 'provenance' && x.id)) {
+      const patched = patchAttrsById(nextHtml, s.id, s.attrs);
+      if (patched.changed) {
+        nextHtml = patched.html;
+        applied += 1;
+      }
+    }
+  }
+
+  return {
+    doctor,
+    suggestions,
+    applied,
+    html: nextHtml,
+    dryRun: opts.dryRun !== false && !opts.apply,
+  };
+}
+
+function kebab(s) {
+  return String(s).replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+
+function applySuggestions(html, suggestions) {
+  let out = html;
+  let applied = 0;
+  for (const s of suggestions) {
+    if (!s.target?.tag) continue;
+    const tag = s.target.tag.toLowerCase();
+    const src = s.target.src;
+    const id = s.target.id;
+    let re;
+    if (id) {
+      re = new RegExp(`<${tag}\\b([^>]*\\bid=["']${escapeRe(id)}["'][^>]*)>`, 'i');
+    } else if (src) {
+      re = new RegExp(`<${tag}\\b([^>]*\\b(?:src|href)=["']${escapeRe(src)}["'][^>]*)>`, 'i');
+    } else continue;
+    const m = out.match(re);
+    if (!m) continue;
+    if (/\bvelin-transparency\b/i.test(m[0])) continue;
+    const attrStr = Object.entries(s.attrs)
+      .map(([k, v]) => (v === '' ? k : `${k}="${String(v).replace(/"/g, '&quot;')}"`))
+      .join(' ');
+    const next = m[0].replace(/>$/, ` ${attrStr}>`);
+    out = out.replace(m[0], next);
+    applied += 1;
+  }
+  return { html: out, applied };
+}
+
+function patchAttrsById(html, id, attrs) {
+  const re = new RegExp(`<([a-z0-9-]+)\\b([^>]*\\b(?:velin-transparency-id|id)=["']${escapeRe(id)}["'][^>]*)>`, 'i');
+  const m = html.match(re);
+  if (!m) return { html, changed: false };
+  let open = m[0];
+  for (const [k, v] of Object.entries(attrs)) {
+    if (new RegExp(`\\b${k}=`, 'i').test(open)) continue;
+    open = open.replace(/>$/, ` ${k}="${String(v).replace(/"/g, '&quot;')}">`);
+  }
+  if (open === m[0]) return { html, changed: false };
+  return { html: html.replace(m[0], open), changed: true };
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/core/transparency/normalize.js

@@ -0,0 +1,125 @@
+import { deriveClaims, primaryLabel } from './claims.js';
+import { stableDisclosureId } from './registry.js';
+
+const PROVENANCE_KEYS = [
+  'createdBy', 'createdAt', 'reviewedAt', 'approvedBy', 'source', 'license', 'version', 'publishedAt',
+];
+
+/**
+ * Normalize a draft disclosure into a registry record.
+ * @param {Record<string, unknown>} draft
+ * @param {{ provider?: string, file?: string, lang?: 'en'|'de' }} [ctx]
+ */
+export function normalizeDisclosure(draft = {}, ctx = {}) {
+  const provider = String(draft.provider || ctx.provider || 'api');
+  const type = String(draft.type || 'ai').toLowerCase();
+  const status = draft.status != null ? String(draft.status).toLowerCase() : undefined;
+  const review = draft.review != null ? String(draft.review).toLowerCase() : undefined;
+  const provenance = normalizeProvenance(draft.provenance || draft);
+  if (draft.license && !provenance.license) provenance.license = String(draft.license);
+  if (draft.model && !provenance.source) provenance.source = `model:${draft.model}`;
+  if (draft.generated === true && !status) {
+    // generated flag without status
+  }
+  const resolvedStatus = status || (draft.generated === true ? 'generated' : undefined);
+  const claims = deriveClaims({
+    status: resolvedStatus,
+    review,
+    license: provenance.license,
+    claims: draft.claims,
+  });
+  const target = {
+    selector: draft.target?.selector || draft.selector || undefined,
+    tag: draft.target?.tag || draft.tag || undefined,
+    src: draft.target?.src || draft.src || undefined,
+    file: draft.target?.file || ctx.file || draft.file || undefined,
+  };
+  const id = stableDisclosureId({
+    id: draft.id || draft.velinTransparencyId,
+    selector: target.selector,
+    src: target.src,
+    tag: target.tag,
+    type,
+    file: target.file,
+  });
+  const lang = ctx.lang === 'de' ? 'de' : 'en';
+  const label = draft.label ? String(draft.label) : primaryLabel(claims, lang);
+  const updated = draft.updated || provenance.publishedAt || provenance.reviewedAt || provenance.createdAt || undefined;
+
+  return {
+    id,
+    type,
+    status: resolvedStatus,
+    review,
+    provider,
+    claims,
+    provenance,
+    updated,
+    label,
+    description: draft.description ? String(draft.description) : undefined,
+    renderer: draft.renderer || draft.overlay || 'badge',
+    tone: draft.tone || toneFromClaims(claims),
+    position: draft.position || 'top-right',
+    target,
+    meta: draft.meta && typeof draft.meta === 'object' ? draft.meta : undefined,
+  };
+}
+
+function normalizeProvenance(src = {}) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const key of PROVENANCE_KEYS) {
+    const v = src[key] ?? src[key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)];
+    if (v != null && String(v).trim()) out[key] = String(v).trim();
+  }
+  // attribute-style aliases
+  if (src['created-by']) out.createdBy = String(src['created-by']);
+  if (src['created-at']) out.createdAt = String(src['created-at']);
+  if (src['reviewed-at']) out.reviewedAt = String(src['reviewed-at']);
+  if (src['approved-by']) out.approvedBy = String(src['approved-by']);
+  if (src['published-at']) out.publishedAt = String(src['published-at']);
+  return out;
+}
+
+function toneFromClaims(claims) {
+  if (claims.includes('ai.generated')) return 'generated';
+  if (claims.includes('review.verified') || claims.includes('trust.official')) return 'verified';
+  if (claims.includes('review.human')) return 'human';
+  if (claims.includes('ai.assisted')) return 'mixed';
+  return 'neutral';
+}
+
+/**
+ * Merge two records; higher priority (lower rank number) wins field-by-field.
+ * @param {import('./registry.js').DisclosureRecord} a
+ * @param {import('./registry.js').DisclosureRecord} b
+ * @param {(id: string) => number} rankFn
+ */
+export function mergeDisclosures(a, b, rankFn) {
+  const aRank = rankFn(a.provider);
+  const bRank = rankFn(b.provider);
+  const primary = aRank <= bRank ? a : b;
+  const secondary = aRank <= bRank ? b : a;
+  const conflictKeys = [];
+  for (const key of ['type', 'status', 'review']) {
+    if (secondary[key] && primary[key] && secondary[key] !== primary[key]) conflictKeys.push(key);
+  }
+  const claims = [...new Set([...(primary.claims || []), ...(secondary.claims || [])])];
+  const provenance = { ...secondary.provenance, ...primary.provenance };
+  return {
+    record: {
+      ...secondary,
+      ...primary,
+      claims,
+      provenance,
+      provider: primary.provider,
+      meta: {
+        ...(secondary.meta || {}),
+        ...(primary.meta || {}),
+        mergedFrom: [secondary.provider, primary.provider],
+        conflicts: conflictKeys,
+      },
+    },
+    conflicts: conflictKeys,
+  };
+}

package/core/transparency/policy.js

@@ -0,0 +1,105 @@
+/** Default and merge helpers for transparency policy. */
+
+/**
+ * Soft framework defaults so existing sites are not hard-failed by `velinstyle check`.
+ * Projects opt into strict media/provenance rules via velin.transparency.policy.json.
+ */
+export const DEFAULT_POLICY = {
+  media: {
+    images: 'optional',
+    videos: 'optional',
+    audio: 'optional',
+    text: 'optional',
+    pdf: 'optional',
+  },
+  rules: {
+    requireReview: false,
+    allowGenerated: true,
+    minimumStatus: null,
+    staleDays: 365,
+  },
+  provenance: {
+    required: [],
+    recommended: ['approvedBy', 'source', 'version', 'createdAt', 'license'],
+    images: { required: [] },
+    videos: { required: [] },
+    audio: { required: [] },
+    pdf: { required: [] },
+  },
+  providers: {
+    priority: ['api', 'json', 'meta', 'html'],
+  },
+};
+
+/** Strict example policy for teams that require disclosure on media. */
+export const STRICT_MEDIA_POLICY = {
+  media: {
+    images: 'required',
+    videos: 'required',
+    audio: 'required',
+    text: 'optional',
+    pdf: 'required',
+  },
+  provenance: {
+    required: [],
+    recommended: ['approvedBy', 'source', 'version'],
+    images: { required: ['createdAt', 'license', 'source'] },
+    videos: { required: ['createdAt'] },
+    audio: { required: ['createdAt'] },
+    pdf: { required: ['license'] },
+  },
+};
+
+/**
+ * @param {unknown} raw
+ */
+export function normalizePolicy(raw) {
+  const input = raw && typeof raw === 'object' ? raw : {};
+  const nested = input.policy && typeof input.policy === 'object' ? input.policy : input;
+  return {
+    media: { ...DEFAULT_POLICY.media, ...(nested.media || {}) },
+    rules: { ...DEFAULT_POLICY.rules, ...(nested.rules || {}) },
+    provenance: {
+      ...DEFAULT_POLICY.provenance,
+      ...(nested.provenance || {}),
+      images: { ...DEFAULT_POLICY.provenance.images, ...(nested.provenance?.images || {}) },
+      videos: { ...DEFAULT_POLICY.provenance.videos, ...(nested.provenance?.videos || {}) },
+      audio: { ...DEFAULT_POLICY.provenance.audio, ...(nested.provenance?.audio || {}) },
+      pdf: { ...DEFAULT_POLICY.provenance.pdf, ...(nested.provenance?.pdf || {}) },
+    },
+    providers: {
+      ...DEFAULT_POLICY.providers,
+      ...(nested.providers || {}),
+      priority: nested.providers?.priority || DEFAULT_POLICY.providers.priority,
+    },
+  };
+}
+
+/**
+ * @param {string} mediaKind images|videos|audio|text|pdf
+ * @param {ReturnType<typeof normalizePolicy>} policy
+ */
+export function mediaRequirement(mediaKind, policy) {
+  return policy.media[mediaKind] || 'optional';
+}
+
+/**
+ * @param {string} mediaKind
+ * @param {ReturnType<typeof normalizePolicy>} policy
+ */
+export function requiredProvenanceFields(mediaKind, policy) {
+  const base = policy.provenance.required || [];
+  const specific = policy.provenance[mediaKind]?.required || [];
+  return [...new Set([...base, ...specific])];
+}
+
+/**
+ * Provider priority index (lower = higher priority).
+ * @param {string} providerId
+ * @param {ReturnType<typeof normalizePolicy>} policy
+ */
+export function providerRank(providerId, policy) {
+  const list = policy.providers.priority || DEFAULT_POLICY.providers.priority;
+  const idx = list.indexOf(providerId);
+  return idx === -1 ? 999 : idx;
+}

package/core/transparency/providers.js

@@ -0,0 +1,235 @@
+import { normalizeDisclosure, mergeDisclosures } from './normalize.js';
+import { providerRank } from './policy.js';
+
+/** @type {Map<string, { collect: Function, apply?: Function }>} */
+const providers = new Map();
+
+export function registerTransparencyProvider(id, handler) {
+  if (!id || typeof handler?.collect !== 'function') {
+    throw new Error('registerTransparencyProvider requires id and collect()');
+  }
+  providers.set(id, handler);
+}
+
+export function listTransparencyProviders() {
+  return [...providers.keys()];
+}
+
+export function getTransparencyProvider(id) {
+  return providers.get(id) || null;
+}
+
+function mergeById(records, policy) {
+  const map = new Map();
+  const conflicts = [];
+  const rankFn = (pid) => providerRank(pid, policy);
+  for (const rec of records) {
+    if (!map.has(rec.id)) {
+      map.set(rec.id, rec);
+      continue;
+    }
+    const { record, conflicts: c } = mergeDisclosures(map.get(rec.id), rec, rankFn);
+    map.set(rec.id, record);
+    if (c.length) {
+      conflicts.push({ id: rec.id, keys: c, providers: record.meta?.mergedFrom });
+    }
+  }
+  return { records: [...map.values()], conflicts };
+}
+
+/**
+ * Collect from all providers, normalize, merge by id using policy priority.
+ * @param {string|Document|ParentNode|object} root
+ * @param {{ policy: object, file?: string, lang?: string, meta?: object, apiDisclosures?: object[] }} ctx
+ */
+export async function collectAllDisclosures(root, ctx) {
+  const drafts = [];
+  for (const [id, handler] of providers) {
+    const items = await handler.collect(root, { ...ctx, providerId: id });
+    for (const item of items || []) {
+      drafts.push(normalizeDisclosure({ ...item, provider: item.provider || id }, {
+        provider: item.provider || id,
+        file: ctx.file,
+        lang: ctx.lang,
+      }));
+    }
+  }
+  return mergeById(drafts, ctx.policy);
+}
+
+function attr(tag, name) {
+  const re = new RegExp(`\\b${name}=["']([^"']*)["']`, 'i');
+  return tag.match(re)?.[1];
+}
+
+function hasAttr(tag, name) {
+  return new RegExp(`(?:\\s|^|<)${name}(?:[\\s>=/]|$)`, 'i').test(tag);
+}
+
+/**
+ * Parse HTML string for velin-transparency hosts and JSON blocks.
+ */
+export function collectFromHtmlString(html) {
+  const items = [];
+  const tagRe = /<([a-z0-9-]+)(\s[^>]*)?>/gi;
+  let m;
+  while ((m = tagRe.exec(html))) {
+    const full = m[0];
+    if (!hasAttr(full, 'velin-transparency') && !hasAttr(full, 'velin-disclosure')) continue;
+    const tagName = m[1].toUpperCase();
+    const id = attr(full, 'velin-transparency-id') || attr(full, 'id');
+    const type = attr(full, 'velin-type') || 'ai';
+    const status = attr(full, 'velin-status');
+    const review = attr(full, 'velin-review');
+    const license = attr(full, 'velin-license');
+    const label = attr(full, 'velin-label') || attr(full, 'velin-ai-label');
+    const description = attr(full, 'velin-description') || attr(full, 'velin-ai-description');
+    const overlay = attr(full, 'velin-overlay') || attr(full, 'velin-renderer') || attr(full, 'velin-ai-overlay');
+    const tone = attr(full, 'velin-tone') || attr(full, 'velin-ai-tone');
+    const position = attr(full, 'velin-position') || attr(full, 'velin-ai-position');
+    const src = attr(full, 'src') || attr(full, 'href');
+    items.push({
+      id,
+      type,
+      status,
+      review,
+      license,
+      label,
+      description,
+      overlay,
+      tone,
+      position,
+      src,
+      tag: tagName,
+      selector: id ? `#${id}` : undefined,
+      provenance: {
+        createdBy: attr(full, 'velin-created-by'),
+        createdAt: attr(full, 'velin-created-at'),
+        reviewedAt: attr(full, 'velin-reviewed-at'),
+        approvedBy: attr(full, 'velin-approved-by'),
+        source: attr(full, 'velin-source'),
+        license: license || undefined,
+        version: attr(full, 'velin-version'),
+        publishedAt: attr(full, 'velin-published-at'),
+      },
+      provider: 'html',
+    });
+  }
+
+  const scriptRe = /<script\b[^>]*type=["']application\/vnd\.velinstyle\.transparency\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  let sm;
+  while ((sm = scriptRe.exec(html))) {
+    try {
+      const data = JSON.parse(sm[1].trim());
+      const list = Array.isArray(data) ? data : data.items || [data];
+      for (const item of list) items.push({ ...item, provider: item.provider || 'json' });
+    } catch { /* ignore */ }
+  }
+
+  const jsonAttrRe = /<([a-z0-9-]+)([^>]*\bvelin-transparency-json=["']([^"']+)["'][^>]*)>/gi;
+  let jm;
+  while ((jm = jsonAttrRe.exec(html))) {
+    try {
+      const data = JSON.parse(jm[3].replace(/&quot;/g, '"'));
+      items.push({ ...data, tag: jm[1].toUpperCase(), provider: 'json' });
+    } catch { /* ignore */ }
+  }
+
+  return items;
+}
+
+function collectFromDom(root) {
+  if (typeof root?.querySelectorAll !== 'function') return [];
+  const items = [];
+  root.querySelectorAll('[velin-transparency], [velin-disclosure]').forEach((el) => {
+    const get = (n) => el.getAttribute(n);
+    items.push({
+      id: get('velin-transparency-id') || el.id || undefined,
+      type: get('velin-type') || 'ai',
+      status: get('velin-status'),
+      review: get('velin-review'),
+      license: get('velin-license'),
+      label: get('velin-label') || get('velin-ai-label'),
+      description: get('velin-description'),
+      overlay: get('velin-overlay') || get('velin-renderer'),
+      tone: get('velin-tone'),
+      position: get('velin-position'),
+      src: el.getAttribute('src') || el.getAttribute('href') || undefined,
+      tag: el.tagName,
+      selector: el.id ? `#${el.id}` : undefined,
+      provenance: {
+        createdBy: get('velin-created-by'),
+        createdAt: get('velin-created-at'),
+        reviewedAt: get('velin-reviewed-at'),
+        approvedBy: get('velin-approved-by'),
+        source: get('velin-source'),
+        license: get('velin-license'),
+        version: get('velin-version'),
+        publishedAt: get('velin-published-at'),
+      },
+      provider: 'html',
+    });
+  });
+  root.querySelectorAll('script[type="application/vnd.velinstyle.transparency+json"]').forEach((script) => {
+    try {
+      const data = JSON.parse(script.textContent || '{}');
+      const list = Array.isArray(data) ? data : data.items || [data];
+      for (const item of list) items.push({ ...item, provider: item.provider || 'json' });
+    } catch { /* ignore */ }
+  });
+  return items;
+}
+
+registerTransparencyProvider('html', {
+  async collect(root) {
+    if (typeof root === 'string') return collectFromHtmlString(root).filter((i) => i.provider === 'html');
+    return collectFromDom(root);
+  },
+});
+
+registerTransparencyProvider('json', {
+  async collect(root) {
+    if (root && typeof root === 'object' && !root.querySelectorAll && (Array.isArray(root) || root.type || root.items)) {
+      const list = Array.isArray(root) ? root : root.items || [root];
+      return list.map((item) => ({ ...item, provider: 'json' }));
+    }
+    if (typeof root === 'string') {
+      return collectFromHtmlString(root).filter((i) => i.provider === 'json');
+    }
+    return [];
+  },
+});
+
+registerTransparencyProvider('meta', {
+  async collect(root, ctx = {}) {
+    if (ctx.meta?.transparency) {
+      const t = ctx.meta.transparency;
+      const list = Array.isArray(t) ? t : t.disclosures || t.items || [];
+      return list.map((item) => ({ ...item, provider: 'meta' }));
+    }
+    if (typeof root === 'string') {
+      const m = root.match(
+        /<script\b[^>]*(?:id=["']velin-meta["']|type=["']application\/vnd\.velinstyle\.meta\+json["'])[^>]*>([\s\S]*?)<\/script>/i,
+      );
+      if (!m) return [];
+      try {
+        const meta = JSON.parse(m[1].trim());
+        const t = meta.transparency || meta.aiDisclosure;
+        if (!t) return [];
+        const list = Array.isArray(t) ? t : t.disclosures || t.items || [];
+        return list.map((item) => ({ ...item, provider: 'meta' }));
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  },
+});
+
+registerTransparencyProvider('api', {
+  async collect(_root, ctx = {}) {
+    return Array.isArray(ctx.apiDisclosures)
+      ? ctx.apiDisclosures.map((i) => ({ ...i, provider: 'api' }))
+      : [];
+  },
+});