@nebulacomponents/citable 1.3.1 → 1.5.0

package/src/observations/common.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRun } from '../evidence/run.js';
+import { nowIso, readJson, sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+export function readInput(input) {
+  if (!input) throw new Error('--input <json> is required for this collector');
+  if (!fs.existsSync(input)) throw new Error(`input not found: ${input}`);
+  return { raw: fs.readFileSync(input, 'utf8'), value: readJson(input), file: path.resolve(input) };
+}
+
+export function envelope(kind, data, { method, source, state = 'observed', confidence = 'confirmed', limitations = [], raw } = {}) {
+  const evidence = raw ?? JSON.stringify(data);
+  const item = {
+    observation_id: `OBS-${kind.toUpperCase()}-${sha256(evidence).slice(0, 16)}`,
+    kind, state, collected_at: nowIso(), collection_method: method,
+    confidence, source, evidence_hash: sha256(evidence), data, limitations,
+  };
+  const check = validateAgainst('observation.schema.json', item);
+  if (!check.valid) throw new Error(`observation violates contract: ${check.errors.join('; ')}`);
+  return item;
+}
+
+export function observationRun(root, command, target, observations, { rawInputs = {}, incomplete = [], warnings = [], artifacts = {} } = {}) {
+  const kind = /^https?:\/\//.test(target) ? 'url' : 'source';
+  const run = createRun(root, { command, argv: process.argv.slice(2), target: { kind, location: target, environment: 'local' } });
+  for (const [name, raw] of Object.entries(rawInputs)) run.addInput(name, raw);
+  observations.forEach((item, i) => run.writeArtifact(`observations/${String(i + 1).padStart(4, '0')}-${item.kind}.json`, item));
+  for (const [name, value] of Object.entries(artifacts)) run.writeArtifact(name, value);
+  run.writeArtifact('summary.json', summarizeObservations(observations));
+  run.manifest.incomplete_checks.push(...incomplete);
+  run.manifest.warnings.push(...warnings);
+  const status = run.manifest.errors.length ? 'completed_with_warnings' : incomplete.length ? 'incomplete' : 'completed';
+  return { runId: run.runId, dir: run.finalize(status), observations, summary: summarizeObservations(observations), manifest: run.manifest };
+}
+
+export function summarizeObservations(items) {
+  const byKind = {}, byState = {};
+  for (const item of items) { byKind[item.kind] = (byKind[item.kind] || 0) + 1; byState[item.state] = (byState[item.state] || 0) + 1; }
+  const citations = items.filter((item) => item.kind === 'citation');
+  const reviews = items.filter((item) => item.kind === 'citation_review');
+  const providers = {};
+  for (const item of citations) {
+    const provider = item.data.provider || 'unknown';
+    providers[provider] ||= { runs: 0, property_cited: 0 };
+    providers[provider].runs++;
+    if (item.data.property_cited) providers[provider].property_cited++;
+  }
+  return {
+    total: items.length, by_kind: byKind, by_state: byState,
+    citation_metrics: citations.length ? {
+      runs: citations.length,
+      citation_presence_rate: citations.filter((x) => x.data.property_cited).length / citations.length,
+      supported_citation_rate: reviews.length ? reviews.filter((x) => x.data.support_status === 'supported').length / reviews.length : null,
+      review_required: reviews.filter((x) => x.state === 'review_required').length,
+      provider_results: providers,
+      competitive_domains: [...new Set(reviews.filter((x) => !x.data.first_party).map((x) => { try { return new URL(x.data.canonical_url).hostname; } catch { return null; } }).filter(Boolean))].sort(),
+    } : null,
+  };
+}

package/src/registries/index.js

@@ -13,6 +13,10 @@ export const REGISTRY_SPECS = [
   { file: 'crawlers.yaml', kind: 'crawlers', schema: 'crawler.schema.json', idField: 'crawler_id' },
   { file: 'competitors.yaml', kind: 'competitors', schema: 'competitor.schema.json', idField: 'competitor_id' },
   { file: 'experiments.yaml', kind: 'experiments', schema: 'experiment.schema.json', idField: 'experiment_id' },
+  { file: 'metrics.yaml', kind: 'metrics', schema: 'metric.schema.json', idField: 'metric_id' },
+  { file: 'objectives.yaml', kind: 'objectives', schema: 'objective.schema.json', idField: 'objective_id' },
+  { file: 'interventions.yaml', kind: 'interventions', schema: 'intervention.schema.json', idField: 'intervention_id' },
+  { file: 'connections.yaml', kind: 'connections', schema: 'connection.schema.json', idField: 'connection_id' },
 ];
 
 export function contextDir(root) {
@@ -91,6 +95,15 @@ export function checkReferentialIntegrity(registries) {
       if (!ids.entities.has(ent)) problems.push(`pages/${p.page_id}: primary_entities references unknown entity id "${ent}"`);
     }
   }
+  const metricIds = ids.metrics || new Set();
+  const objectiveIds = ids.objectives || new Set();
+  for (const objective of registries.objectives?.entries || []) {
+    const refs = [...(objective.primary_metrics || []), ...(objective.supporting_metrics || []), ...(objective.guardrails || []).map((item) => item.metric_id)];
+    for (const ref of refs) if (!metricIds.has(ref)) problems.push(`objectives/${objective.objective_id}: references unknown metric id "${ref}"`);
+  }
+  for (const intervention of registries.interventions?.entries || []) {
+    for (const ref of intervention.objective_ids || []) if (!objectiveIds.has(ref)) problems.push(`interventions/${intervention.intervention_id}: references unknown objective id "${ref}"`);
+  }
   return problems;
 }