@nebulacomponents/citable 1.9.0 → 1.10.0

package/src/cli/index.js

@@ -19,6 +19,7 @@ import { evaluateObjective, importMetrics, initializeObjective, validateObjectiv
 import { configureConnection, connectionStatus, discoverConnections, disconnectConnection, syncConnection, validateConnection } from '../commands/connect.js';
 import { evaluateDispositions, validateGovernance } from '../commands/governance.js';
 import { evaluateReviews, initializeSamplingPlan, prioritizeReviews, queueReviews, selectSample } from '../commands/reviews.js';
+import { projectGithub, runSchedule } from '../commands/delivery.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -62,6 +63,8 @@ Commands
   reviews plan              Validate/add a sampling plan from --input
   reviews sample [plan]     Select a reproducible census or seeded random sample
   reviews evaluate          Detect stale decisions and require disagreement adjudication
+  schedules run [id]        Execute an active version-pinned audit schedule
+  project github [run]      Render non-authoritative GitHub annotations from a run
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
@@ -272,6 +275,18 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         out(args,`reviews ${mode}: ${r.created?.length ?? r.items?.length ?? r.selected_item_ids?.length ?? r.results?.length ?? 1} item(s)${args.write?' written':' (dry run)'}`,r);
         break;
       }
+      case 'schedules': {
+        if(args._[0]!=='run') throw new Error('usage: citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]');
+        const r=await runSchedule(root,{scheduleId:args._[1],refDate:args.refDate});
+        out(args,`schedule ${r.schedule_execution.schedule_id}: audit ${r.runId}\nEvidence package: ${r.dir}\nExecution record: ${r.execution_file}`,r);
+        break;
+      }
+      case 'project': {
+        if(args._[0]!=='github') throw new Error('usage: citable project github <run-id>');
+        const r=projectGithub(root,{runId:args._[1]});
+        out(args,`project github ${r.source_run_id}: ${r.annotations.length} annotation(s)\nProjection: ${path.join(r.dir,'annotations.json')}`,r);
+        break;
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);

package/src/commands/compareSnapshots.js

@@ -27,6 +27,16 @@ export function compareSnapshots(root, { runA, runB } = {}) {
   };
   const a = load(runA);
   const b = load(runB);
+  const changedKeys = (left = {}, right = {}) => [...new Set([...Object.keys(left), ...Object.keys(right)])].filter((key) => left[key] !== right[key]);
+  const changeDimensions = {
+    resource_changed: changedKeys(a.manifest.input_hashes, b.manifest.input_hashes),
+    evidence_artifacts_changed: changedKeys(a.manifest.output_hashes, b.manifest.output_hashes),
+    detector_set_changed: JSON.stringify(a.manifest.detectors_run) !== JSON.stringify(b.manifest.detectors_run),
+    configuration_changed: a.manifest.configuration_hash !== b.manifest.configuration_hash,
+    observation_method_changed: a.manifest.command !== b.manifest.command || JSON.stringify(a.manifest.argv) !== JSON.stringify(b.manifest.argv) || a.manifest.target?.kind !== b.manifest.target?.kind,
+    tool_changed: a.manifest.tool_version !== b.manifest.tool_version,
+    external_system_may_have_changed: a.manifest.target?.kind === 'url' || b.manifest.target?.kind === 'url',
+  };
   const key = (f) => `${f.detector_id}|${f.subject.identifier}|${f.observation.summary}`;
   const aKeys = new Map(a.findings.map((f) => [key(f), f]));
   const bKeys = new Map(b.findings.map((f) => [key(f), f]));
@@ -38,6 +48,11 @@ export function compareSnapshots(root, { runA, runB } = {}) {
     baseline_timestamp: a.manifest.timestamp,
     comparison_timestamp: b.manifest.timestamp,
     regressions, resolved, persisting,
+    comparability: {
+      comparable: !changeDimensions.detector_set_changed && !changeDimensions.configuration_changed && !changeDimensions.observation_method_changed && !changeDimensions.tool_changed,
+      change_dimensions: changeDimensions,
+      limitation: 'These dimensions identify observed differences between run envelopes; they do not establish what caused a finding change.',
+    },
     summary: {
       new_findings: regressions.length,
       resolved_findings: resolved.length,

package/src/commands/delivery.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { audit } from './audit.js';
+import { loadRegistries } from '../registries/index.js';
+import { readJson, sha256, writeJson, nowIso } from '../shared/io.js';
+
+const PKG = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
+
+export async function runSchedule(root, { scheduleId, refDate } = {}) {
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const schedule = registries.schedules.entries.find((item) => item.schedule_id === scheduleId);
+  if (!schedule) throw new Error(`schedule not found: ${scheduleId}`);
+  if (schedule.status !== 'active') throw new Error(`schedule ${scheduleId} is ${schedule.status}`);
+  if (schedule.expected_tool_version !== PKG.version) throw new Error(`schedule ${scheduleId} expects Citable ${schedule.expected_tool_version}, current version is ${PKG.version}`);
+  const result = await audit(root, { target: schedule.audit.target, scope: schedule.audit.scope, baseUrl: schedule.audit.base_url, refDate });
+  const execution = { schedule_id: scheduleId, cron: schedule.cron, owner: schedule.owner, executed_at: nowIso(), run_id: result.runId, manifest_hash: sha256(fs.readFileSync(path.join(result.dir, 'manifest.json'))), limitations: schedule.limitations };
+  const executionFile = path.join(root, '.citable', 'schedule-executions', `${result.runId}.json`);
+  writeJson(executionFile, execution);
+  return { ...result, schedule_execution: execution, execution_file: executionFile };
+}
+
+function annotationLevel(severity) {
+  if (['critical', 'high'].includes(severity)) return 'failure';
+  if (severity === 'medium') return 'warning';
+  return 'notice';
+}
+
+export function projectGithub(root, { runId } = {}) {
+  if (!runId) throw new Error('projection requires a source run id');
+  const runDir = path.join(root, '.citable', 'runs', runId);
+  const findingsFile = path.join(runDir, 'findings.json');
+  const manifestFile = path.join(runDir, 'manifest.json');
+  if (!fs.existsSync(findingsFile) || !fs.existsSync(manifestFile)) throw new Error(`run ${runId} is missing findings or manifest evidence`);
+  const findingsBytes = fs.readFileSync(findingsFile);
+  const manifestBytes = fs.readFileSync(manifestFile);
+  const annotations = JSON.parse(findingsBytes).map((finding) => ({
+    level: annotationLevel(finding.classification.severity),
+    title: `${finding.detector_id}: ${finding.classification.severity}`,
+    message: finding.observation.summary,
+    path: finding.subject.source_file || null,
+    line: finding.subject.source_location ? Number(String(finding.subject.source_location).match(/\d+/)?.[0]) || null : null,
+    finding_id: finding.finding_id,
+  }));
+  const projection = { source_run_id: runId, source_manifest_hash: sha256(manifestBytes), source_findings_hash: sha256(findingsBytes), generated_at: nowIso(), projection: 'github-check-annotations', authoritative: false, annotations };
+  const dir = path.join(root, '.citable', 'projections', 'github', runId);
+  writeJson(path.join(dir, 'annotations.json'), projection);
+  return { ...projection, dir };
+}

package/src/registries/index.js

@@ -22,6 +22,7 @@ export const REGISTRY_SPECS = [
   { file: 'exceptions.yaml', kind: 'exceptions', schema: 'exception.schema.json', idField: 'exception_id' },
   { file: 'review-items.yaml', kind: 'review_items', schema: 'review-item.schema.json', idField: 'review_item_id' },
   { file: 'sampling-plans.yaml', kind: 'sampling_plans', schema: 'sampling-plan.schema.json', idField: 'sampling_plan_id' },
+  { file: 'schedules.yaml', kind: 'schedules', schema: 'schedule.schema.json', idField: 'schedule_id' },
 ];
 
 export function contextDir(root) {