@nebulacomponents/citable 0.1.0

package/src/installer/providers.js

@@ -0,0 +1,164 @@
+import path from 'node:path';
+
+export const PROVIDERS = Object.freeze({
+  claude: {
+    id: 'claude',
+    displayName: 'Claude Code',
+    aliases: ['claude-code', 'claudecode'],
+    projectDir: '.claude',
+    projectSkillsDir: '.claude/skills',
+    globalHints: ['.claude'],
+    globalSkillsDir: '.claude/skills',
+  },
+  codex: {
+    id: 'codex',
+    displayName: 'OpenAI Codex',
+    aliases: ['openai', 'openai-codex', 'agents'],
+    projectDir: '.agents',
+    projectSkillsDir: '.agents/skills',
+    globalHints: ['.codex', '.agents'],
+    globalSkillsDir: '.agents/skills',
+  },
+  cursor: {
+    id: 'cursor',
+    displayName: 'Cursor',
+    aliases: [],
+    projectDir: '.cursor',
+    projectSkillsDir: '.cursor/skills',
+    globalHints: ['.cursor'],
+    globalSkillsDir: '.cursor/skills',
+  },
+  gemini: {
+    id: 'gemini',
+    displayName: 'Gemini CLI',
+    aliases: ['gemini-cli'],
+    projectDir: '.gemini',
+    projectSkillsDir: '.gemini/skills',
+    globalHints: ['.gemini'],
+    globalSkillsDir: '.gemini/skills',
+  },
+  github: {
+    id: 'github',
+    displayName: 'GitHub Copilot',
+    aliases: ['copilot', 'github-copilot'],
+    projectDir: '.github',
+    projectSkillsDir: '.github/skills',
+    globalHints: ['.github'],
+    globalSkillsDir: '.github/skills',
+  },
+  opencode: {
+    id: 'opencode',
+    displayName: 'OpenCode',
+    aliases: ['open-code'],
+    projectDir: '.opencode',
+    projectSkillsDir: '.opencode/skills',
+    globalHints: ['.opencode'],
+    globalSkillsDir: '.opencode/skills',
+  },
+  kiro: {
+    id: 'kiro',
+    displayName: 'Kiro',
+    aliases: [],
+    projectDir: '.kiro',
+    projectSkillsDir: '.kiro/skills',
+    globalHints: ['.kiro'],
+    globalSkillsDir: '.kiro/skills',
+  },
+  pi: {
+    id: 'pi',
+    displayName: 'Pi',
+    aliases: ['pi-agent'],
+    projectDir: '.pi',
+    projectSkillsDir: '.pi/agent/skills',
+    globalHints: ['.pi'],
+    globalSkillsDir: '.pi/agent/skills',
+  },
+  qoder: {
+    id: 'qoder',
+    displayName: 'Qoder',
+    aliases: [],
+    projectDir: '.qoder',
+    projectSkillsDir: '.qoder/skills',
+    globalHints: ['.qoder'],
+    globalSkillsDir: '.qoder/skills',
+  },
+  trae: {
+    id: 'trae',
+    displayName: 'Trae',
+    aliases: [],
+    projectDir: '.trae',
+    projectSkillsDir: '.trae/skills',
+    globalHints: ['.trae'],
+    globalSkillsDir: '.trae/skills',
+  },
+  'trae-cn': {
+    id: 'trae-cn',
+    displayName: 'Trae CN',
+    aliases: ['traecn'],
+    projectDir: '.trae-cn',
+    projectSkillsDir: '.trae-cn/skills',
+    globalHints: ['.trae-cn'],
+    globalSkillsDir: '.trae-cn/skills',
+  },
+  rovodev: {
+    id: 'rovodev',
+    displayName: 'Rovo Dev',
+    aliases: ['rovo', 'rovo-dev'],
+    projectDir: '.rovodev',
+    projectSkillsDir: '.rovodev/skills',
+    globalHints: ['.rovodev'],
+    globalSkillsDir: '.rovodev/skills',
+  },
+});
+
+export const PROVIDER_IDS = Object.freeze(Object.keys(PROVIDERS));
+
+const ALIASES = new Map();
+for (const provider of Object.values(PROVIDERS)) {
+  ALIASES.set(provider.id, provider.id);
+  for (const alias of provider.aliases) ALIASES.set(alias, provider.id);
+}
+
+export function normalizeProviderId(value) {
+  const key = String(value ?? '').trim().toLowerCase();
+  if (!key) return null;
+  return ALIASES.get(key) ?? null;
+}
+
+export function parseProviderList(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return { kind: 'explicit', providers: [], unknown: [] };
+  const lowered = raw.toLowerCase();
+  if (lowered === 'detected') return { kind: 'detected', providers: [], unknown: [] };
+  if (lowered === 'all') return { kind: 'all', providers: PROVIDER_IDS, unknown: [] };
+
+  const providers = [];
+  const unknown = [];
+  for (const part of raw.split(',')) {
+    const id = normalizeProviderId(part);
+    if (!id) {
+      unknown.push(part.trim());
+      continue;
+    }
+    if (!providers.includes(id)) providers.push(id);
+  }
+  return { kind: 'explicit', providers, unknown };
+}
+
+export function providerSkillsDir(providerId, scope, roots) {
+  const provider = PROVIDERS[providerId];
+  if (!provider) throw new Error(`unknown provider: ${providerId}`);
+  if (scope === 'project') return path.resolve(roots.projectRoot, provider.projectSkillsDir);
+  if (scope === 'global') return path.resolve(roots.home, provider.globalSkillsDir);
+  throw new Error(`unknown scope: ${scope}`);
+}
+
+export function providerDestination(providerId, scope, roots) {
+  return path.join(providerSkillsDir(providerId, scope, roots), 'citable');
+}
+
+export function providerBundleSkillPath(providerId) {
+  const provider = PROVIDERS[providerId];
+  if (!provider) throw new Error(`unknown provider: ${providerId}`);
+  return path.join('dist', 'universal', provider.projectSkillsDir, 'citable');
+}

package/src/registries/index.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readYaml, writeYaml, nowIso, sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+export const REGISTRY_SPECS = [
+  { file: 'queries.yaml', kind: 'queries', schema: 'query.schema.json', idField: 'query_id' },
+  { file: 'prompts.yaml', kind: 'prompts', schema: 'prompt.schema.json', idField: 'prompt_id' },
+  { file: 'entities.yaml', kind: 'entities', schema: 'entity.schema.json', idField: 'entity_id' },
+  { file: 'claims.yaml', kind: 'claims', schema: 'claim.schema.json', idField: 'claim_id' },
+  { file: 'evidence.yaml', kind: 'evidence', schema: 'evidence.schema.json', idField: 'evidence_id' },
+  { file: 'pages.yaml', kind: 'pages', schema: 'page.schema.json', idField: 'page_id' },
+  { 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' },
+];
+
+export function contextDir(root) {
+  return path.join(root, '.citable');
+}
+
+export function emptyRegistry(kind) {
+  return { version: 1, kind, updated: nowIso(), entries: [] };
+}
+
+/** Load all registries under <root>/.citable. Missing files load as empty. */
+export function loadRegistries(root) {
+  const dir = contextDir(root);
+  const registries = {};
+  const problems = [];
+  for (const spec of REGISTRY_SPECS) {
+    const file = path.join(dir, spec.file);
+    let data;
+    if (fs.existsSync(file)) {
+      try {
+        data = readYaml(file) ?? emptyRegistry(spec.kind);
+      } catch (err) {
+        problems.push(`${spec.file}: YAML parse failure: ${err.message}`);
+        data = emptyRegistry(spec.kind);
+      }
+    } else {
+      data = emptyRegistry(spec.kind);
+    }
+    const { valid, errors } = validateAgainst(spec.schema, data);
+    if (!valid) problems.push(...errors.map((e) => `${spec.file}: ${e}`));
+    registries[spec.kind] = data;
+  }
+  return { registries, problems };
+}
+
+/** Referential-integrity check across registries. Returns list of problem strings. */
+export function checkReferentialIntegrity(registries) {
+  const problems = [];
+  const ids = {};
+  for (const spec of REGISTRY_SPECS) {
+    ids[spec.kind] = new Set((registries[spec.kind]?.entries || []).map((e) => e[spec.idField]));
+    const seen = new Set();
+    for (const e of registries[spec.kind]?.entries || []) {
+      const id = e[spec.idField];
+      if (seen.has(id)) problems.push(`${spec.kind}: duplicate id ${id}`);
+      seen.add(id);
+    }
+  }
+  const refChecks = [
+    ['claims', 'evidence', 'evidence', 'claim_id'],
+    ['claims', 'external_corroboration', 'evidence', 'claim_id'],
+    ['entities', 'evidence', 'evidence', 'entity_id'],
+    ['pages', 'published_claims', 'claims', 'page_id'],
+    ['pages', 'evidence_references', 'evidence', 'page_id'],
+    ['pages', 'target_queries', 'queries', 'page_id'],
+    ['pages', 'target_prompts', 'prompts', 'page_id'],
+    ['evidence', 'supports_claims', 'claims', 'evidence_id'],
+  ];
+  for (const [kind, field, targetKind, idField] of refChecks) {
+    for (const e of registries[kind]?.entries || []) {
+      for (const ref of e[field] || []) {
+        if (typeof ref === 'string' && !ids[targetKind].has(ref)) {
+          problems.push(`${kind}/${e[idField]}: ${field} references unknown ${targetKind} id "${ref}"`);
+        }
+      }
+    }
+  }
+  // entity references from claims / pages
+  for (const c of registries.claims?.entries || []) {
+    if (c.entity && !ids.entities.has(c.entity)) {
+      problems.push(`claims/${c.claim_id}: entity references unknown entity id "${c.entity}"`);
+    }
+  }
+  for (const p of registries.pages?.entries || []) {
+    for (const ent of p.primary_entities || []) {
+      if (!ids.entities.has(ent)) problems.push(`pages/${p.page_id}: primary_entities references unknown entity id "${ent}"`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * Persist a registry, preserving prior version in .citable/snapshots/registry-history/.
+ * Never overwrites without recording the previous content.
+ */
+export function saveRegistry(root, kind, data) {
+  const spec = REGISTRY_SPECS.find((s) => s.kind === kind);
+  if (!spec) throw new Error(`unknown registry kind: ${kind}`);
+  const { valid, errors } = validateAgainst(spec.schema, data);
+  if (!valid) throw new Error(`refusing to save invalid ${kind} registry:\n${errors.join('\n')}`);
+  const file = path.join(contextDir(root), spec.file);
+  if (fs.existsSync(file)) {
+    const prev = fs.readFileSync(file, 'utf8');
+    const histDir = path.join(contextDir(root), 'snapshots', 'registry-history');
+    fs.mkdirSync(histDir, { recursive: true });
+    const stamp = nowIso().replace(/[:.]/g, '-');
+    fs.writeFileSync(path.join(histDir, `${spec.kind}-${stamp}-${sha256(prev).slice(0, 8)}.yaml`), prev);
+  }
+  data.updated = nowIso();
+  writeYaml(file, data);
+  return file;
+}
+
+/** Structural diff of two registry objects (entries keyed by id). */
+export function diffRegistries(before, after, idField) {
+  const b = new Map((before?.entries || []).map((e) => [e[idField], e]));
+  const a = new Map((after?.entries || []).map((e) => [e[idField], e]));
+  const added = [...a.keys()].filter((k) => !b.has(k));
+  const removed = [...b.keys()].filter((k) => !a.has(k));
+  const changed = [...a.keys()].filter((k) => b.has(k) && JSON.stringify(b.get(k)) !== JSON.stringify(a.get(k)));
+  return { added, removed, changed };
+}

package/src/reporting/report.js

@@ -0,0 +1,82 @@
+const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, informational: 4, experimental: 5 };
+
+export function summarize(findings) {
+  const bySeverity = {};
+  const byNamespace = {};
+  const byDiscipline = { seo: 0, aeo: 0, geo: 0 };
+  let deterministic = 0;
+  for (const f of findings) {
+    bySeverity[f.classification.severity] = (bySeverity[f.classification.severity] || 0) + 1;
+    const ns = f.detector_id.split('-')[0];
+    byNamespace[ns] = (byNamespace[ns] || 0) + 1;
+    for (const d of f.discipline) byDiscipline[d] = (byDiscipline[d] || 0) + 1;
+    if (f.classification.deterministic) deterministic++;
+  }
+  return {
+    total: findings.length,
+    deterministic_observations: deterministic,
+    semantic_or_heuristic: findings.length - deterministic,
+    by_severity: bySeverity,
+    by_namespace: byNamespace,
+    by_discipline: byDiscipline,
+  };
+}
+
+export function renderMarkdownReport({ findings, manifest, summary, detectorsSkipped = [] }) {
+  const lines = [];
+  lines.push(`# Citable audit report`);
+  lines.push('');
+  lines.push(`- Run: \`${manifest.run_id}\``);
+  lines.push(`- Command: \`${manifest.command}\``);
+  lines.push(`- Target: ${manifest.target?.kind} — ${manifest.target?.location}`);
+  lines.push(`- Timestamp: ${manifest.timestamp}`);
+  lines.push(`- Tool version: ${manifest.tool_version}; commit: ${manifest.repository_commit ?? 'n/a'} (${manifest.working_tree_state ?? 'no git'})`);
+  lines.push('');
+  lines.push(`> Findings describe observed conditions and probabilities. Nothing in this report guarantees crawling, indexing, ranking, citation, recommendation, or conversion outcomes.`);
+  lines.push('');
+  lines.push(`## Summary`);
+  lines.push('');
+  lines.push(`| Metric | Value |`);
+  lines.push(`| --- | --- |`);
+  lines.push(`| Total findings | ${summary.total} |`);
+  lines.push(`| Deterministic observations | ${summary.deterministic_observations} |`);
+  lines.push(`| Heuristic / semantic findings | ${summary.semantic_or_heuristic} |`);
+  for (const [sev, n] of Object.entries(summary.by_severity).sort((a, b) => SEV_ORDER[a[0]] - SEV_ORDER[b[0]])) {
+    lines.push(`| ${sev} | ${n} |`);
+  }
+  lines.push('');
+  if (detectorsSkipped.length) {
+    lines.push(`## Skipped checks`);
+    lines.push('');
+    for (const s of detectorsSkipped) lines.push(`- \`${s.detector_id}\`: ${s.reason}`);
+    lines.push('');
+  }
+  if (manifest.incomplete_checks?.length) {
+    lines.push(`## Incomplete or untestable conditions`);
+    lines.push('');
+    for (const c of manifest.incomplete_checks) lines.push(`- ${c}`);
+    lines.push('');
+  }
+  lines.push(`## Findings`);
+  lines.push('');
+  const sorted = [...findings].sort((a, b) => SEV_ORDER[a.classification.severity] - SEV_ORDER[b.classification.severity]);
+  for (const f of sorted) {
+    lines.push(`### ${f.classification.severity.toUpperCase()} · ${f.detector_id} · ${f.observation.summary}`);
+    lines.push('');
+    lines.push(`- Subject: \`${f.subject.identifier}\`${f.subject.source_file ? ` (${f.subject.source_file})` : ''}`);
+    lines.push(`- Type: ${f.classification.finding_type}; confidence: ${f.classification.confidence}; deterministic: ${f.classification.deterministic}`);
+    const impacts = Object.entries(f.classification.impact || {}).filter(([, v]) => v && v !== 'none').map(([k, v]) => `${k}:${v}`).join(', ');
+    if (impacts) lines.push(`- Impact: ${impacts}`);
+    lines.push(`- Evidence:`);
+    for (const e of f.observation.evidence) lines.push(`  - ${e}`);
+    lines.push(`- Remediation: ${f.remediation.preferred}`);
+    lines.push(`- Verify: ${f.verification.method} (rerun \`${f.verification.detector_to_rerun}\`)`);
+    if (f.reasoning?.limitations?.length) lines.push(`- Limitations: ${f.reasoning.limitations.join('; ')}`);
+    lines.push('');
+  }
+  if (findings.length === 0) {
+    lines.push(`No findings from the executed detectors. Absence of findings is not proof of eligibility — see skipped and incomplete checks above.`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/shared/io.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { load as yamlLoad, dump as yamlDump } from 'js-yaml';
+
+export function readYaml(file) {
+  return yamlLoad(fs.readFileSync(file, 'utf8'));
+}
+
+export function writeYaml(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, yamlDump(data, { lineWidth: 100, noRefs: true, sortKeys: false }));
+}
+
+export function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+}
+
+export function sha256(input) {
+  return crypto.createHash('sha256').update(input).digest('hex');
+}
+
+export function sha256File(file) {
+  return sha256(fs.readFileSync(file));
+}
+
+export function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function isPastDate(isoDate, ref = new Date()) {
+  if (!isoDate) return false;
+  const d = new Date(String(isoDate).slice(0, 10) + 'T23:59:59Z');
+  return !Number.isNaN(d.getTime()) && d < ref;
+}
+
+export function listFiles(dir, predicate = () => true, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const name of fs.readdirSync(dir)) {
+    if (name === 'node_modules' || name === '.git' || name === '.citable') continue;
+    const p = path.join(dir, name);
+    const st = fs.statSync(p);
+    if (st.isDirectory()) listFiles(p, predicate, out);
+    else if (predicate(p)) out.push(p);
+  }
+  return out;
+}

package/src/shared/schemaValidator.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+const SCHEMA_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../schemas');
+
+let ajv = null;
+
+export function getAjv() {
+  if (ajv) return ajv;
+  ajv = new Ajv({ allErrors: true, strict: false, allowUnionTypes: true });
+  addFormats(ajv);
+  for (const f of fs.readdirSync(SCHEMA_DIR)) {
+    if (f.endsWith('.json')) ajv.addSchema(JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, f), 'utf8')));
+  }
+  return ajv;
+}
+
+export function validateAgainst(schemaName, data) {
+  const validator = getAjv().getSchema(`citable://schemas/${schemaName}`);
+  if (!validator) throw new Error(`unknown schema: ${schemaName}`);
+  const valid = validator(data);
+  return {
+    valid,
+    errors: (validator.errors || []).map((e) => `${e.instancePath || '/'} ${e.message}`),
+  };
+}