arckit-cli 6.1.1__py3-none-any.whl

arckit_cli-6.1.1.data/data/share/arckit/extensions/arckit-codex/hooks/graph-rollups.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * ArcKit Graph Rollups — Shared health, coverage, and compliance computations
+ *
+ * Used by:
+ * - graph-inject.mjs (formatNavigator, formatGraphReport, formatHealth)
+ * - sync-guides.mjs  (manifest.projectHealth + per-node health flags for the
+ *                     dashboard Document Map and Project Health panel)
+ *
+ * Pure data — no Markdown formatting. Callers shape the output.
+ */
+
+import { DOC_TYPES } from '../config/doc-types.mjs';
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+/**
+ * Doc types whose category yields HIGH severity in classifySeverity().
+ * Used for "compliance readiness" scoring.
+ */
+export const HIGH_SEVERITY_TYPES = ['TCOP', 'SECD', 'SECD-MOD', 'DPIA', 'SVCASS',
+  'RISK', 'TRAC', 'CONF', 'PRIN-COMP', 'AIPB', 'ATRS', 'JSP936'];
+
+/**
+ * Essential doc types per tier — used by navigator to compute coverage and
+ * recommend the next command. Tiers represent rough dependency order.
+ */
+export const ESSENTIAL_TYPES = [
+  { type: 'REQ',  tier: 1, command: '$arckit-requirements',  label: 'Requirements' },
+  { type: 'STKE', tier: 1, command: '$arckit-stakeholders',  label: 'Stakeholder Analysis' },
+  { type: 'RISK', tier: 1, command: '$arckit-risk',          label: 'Risk Register' },
+  { type: 'SOBC', tier: 2, command: '$arckit-sobc',          label: 'Strategic Outline Business Case' },
+  { type: 'ADR',  tier: 3, command: '$arckit-adr',           label: 'Architecture Decision Record' },
+  { type: 'HLDR', tier: 3, command: '$arckit-hld-review',    label: 'High-Level Design Review' },
+  { type: 'TRAC', tier: 4, command: '$arckit-traceability',  label: 'Traceability Matrix' },
+  { type: 'CONF', tier: 4, command: '$arckit-conformance',   label: 'Conformance Assessment' },
+];
+
+export const CONTEXTUAL_TYPES = [
+  { type: 'DPIA', command: '$arckit-dpia',       trigger: 'processing personal data' },
+  { type: 'SECD', command: '$arckit-secure',     trigger: 'security-sensitive system' },
+  { type: 'TCOP', command: '$arckit-tcop',       trigger: 'UK Gov Service Standard' },
+  { type: 'DATA', command: '$arckit-data-model', trigger: 'DR-* requirements present' },
+];
+
+/** Days since lastModified before a node is flagged stale. */
+export const STALE_THRESHOLD_DAYS = 90;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function safeParseDate(s) {
+  if (!s) return null;
+  const d = new Date(s);
+  return isNaN(d.getTime()) ? null : d;
+}
+
+function daysBetween(date, baseline) {
+  return Math.floor((baseline.getTime() - date.getTime()) / (1000 * 60 * 60 * 24));
+}
+
+function shortIdOf(fullId) {
+  return fullId.replace(/-v[\d.]+$/, '');
+}
+
+function fullIdFromPath(path) {
+  return path.split('/').pop().replace(/\.md$/, '');
+}
+
+// ── Per-node health ────────────────────────────────────────────────────────
+
+/**
+ * Compute health flags for every node in the graph and attach them as
+ * `node.health = { stale, draft, orphan, ageDays }`.
+ *
+ * Mutates graph.nodes in place. Returns the graph for chaining.
+ *
+ * `stale` = lastModified (or createdDate) older than STALE_THRESHOLD_DAYS
+ * `draft` = status matches /draft/i
+ * `orphan` = no incoming or outgoing edges within the project's id-space
+ */
+export function tagNodeHealth(graph, baseline = new Date()) {
+  if (!graph || !graph.nodes) return graph;
+
+  // Build per-project full-id sets so orphan detection is project-scoped.
+  const projectIds = {};
+  for (const [fullId, node] of Object.entries(graph.nodes)) {
+    if (!projectIds[node.project]) projectIds[node.project] = new Set();
+    projectIds[node.project].add(fullId);
+  }
+
+  // Build connected sets per project from edges.
+  const connectedByProject = {};
+  for (const projectName of Object.keys(projectIds)) {
+    connectedByProject[projectName] = new Set();
+  }
+  for (const e of graph.edges || []) {
+    const fromNode = graph.nodes[e.from];
+    if (!fromNode) continue;
+    const proj = fromNode.project;
+    const set = connectedByProject[proj];
+    if (!set) continue;
+    set.add(e.from);
+    // Edge `to` is short-id; connect any matching full-id in the same project.
+    for (const fullId of projectIds[proj]) {
+      if (fullId === e.to || shortIdOf(fullId) === e.to) {
+        set.add(fullId);
+      }
+    }
+  }
+
+  for (const [fullId, node] of Object.entries(graph.nodes)) {
+    const dateStr = node.lastModified || node.createdDate;
+    const d = safeParseDate(dateStr);
+    const ageDays = d ? daysBetween(d, baseline) : null;
+    const stale = ageDays != null && ageDays >= STALE_THRESHOLD_DAYS;
+    const draft = /draft/i.test(node.status || '');
+    const connected = connectedByProject[node.project];
+    const orphan = !!connected && !connected.has(fullId);
+
+    node.health = { stale, draft, orphan, ageDays };
+  }
+
+  return graph;
+}
+
+// ── Per-project rollup ─────────────────────────────────────────────────────
+
+/**
+ * Compute a per-project rollup with coverage, compliance, density, and
+ * recommended next commands. Mirrors the formulas used in graph-inject.mjs
+ * formatNavigator + formatGraphReport but returns structured data.
+ *
+ * @param {string} projectName  e.g. '001-foo'
+ * @param {object} graph        from scanAllArtifacts (must include nodes, edges)
+ * @param {Date}   baseline     reference "now" for stale calculations
+ * @returns {object}            project rollup
+ */
+export function computeProjectRollup(projectName, graph, baseline = new Date()) {
+  const projectNodes = Object.values(graph.nodes).filter(n => n.project === projectName);
+  const projectFullIds = new Set(projectNodes.map(n => fullIdFromPath(n.path)));
+
+  // Edges originating in this project
+  const projectEdges = (graph.edges || []).filter(e => projectFullIds.has(e.from));
+  const density = projectNodes.length === 0
+    ? 0
+    : projectEdges.length / projectNodes.length;
+
+  // Type set
+  const presentTypes = new Set(projectNodes.map(n => n.type).filter(Boolean));
+
+  // Essential coverage (Tier 1–4 doc types)
+  const essentialPresent = ESSENTIAL_TYPES.filter(e => presentTypes.has(e.type));
+  const essentialMissing = ESSENTIAL_TYPES.filter(e => !presentTypes.has(e.type));
+  const essentialPct = ESSENTIAL_TYPES.length === 0
+    ? 0
+    : Math.round((essentialPresent.length / ESSENTIAL_TYPES.length) * 100);
+
+  // Contextual artifact suggestions (only flag those NOT present)
+  const contextualMissing = CONTEXTUAL_TYPES.filter(c => !presentTypes.has(c.type));
+
+  // Compliance readiness (HIGH-severity types)
+  const presentHigh = HIGH_SEVERITY_TYPES.filter(t => presentTypes.has(t));
+  const missingHigh = HIGH_SEVERITY_TYPES.filter(t => !presentTypes.has(t));
+  const compliancePct = HIGH_SEVERITY_TYPES.length === 0
+    ? 0
+    : Math.round((presentHigh.length / HIGH_SEVERITY_TYPES.length) * 100);
+
+  // Coverage by category — counts vs total possible types per category
+  const presentByCategory = {};
+  for (const t of presentTypes) {
+    const info = DOC_TYPES[t];
+    if (!info) continue;
+    if (!presentByCategory[info.category]) presentByCategory[info.category] = 0;
+    presentByCategory[info.category]++;
+  }
+
+  // Health rollup (count nodes already tagged via tagNodeHealth)
+  const tagged = projectNodes.every(n => n.health !== undefined);
+  const staleCount = tagged ? projectNodes.filter(n => n.health.stale).length : 0;
+  const draftCount = tagged ? projectNodes.filter(n => n.health.draft).length : 0;
+  const orphanCount = tagged ? projectNodes.filter(n => n.health.orphan).length : 0;
+
+  // Global principles presence
+  const hasGlobalPrin = Object.values(graph.nodes).some(
+    n => n.project === '000-global' && n.type === 'PRIN'
+  );
+
+  // Recommended next commands — missing essentials in tier order, capped at 3
+  const recommendations = essentialMissing
+    .slice()
+    .sort((a, b) => a.tier - b.tier)
+    .slice(0, 3)
+    .map(e => ({
+      command: e.command,
+      label: e.label,
+      type: e.type,
+      tier: e.tier,
+      reason: `Tier ${e.tier} essential missing`,
+    }));
+
+  return {
+    project: projectName,
+    projectId: projectName.match(/^(\d{3})/)?.[1] || '',
+    artifactCount: projectNodes.length,
+    edgeCount: projectEdges.length,
+    density: Number(density.toFixed(2)),
+    coverage: {
+      essentialPresent: essentialPresent.map(e => e.type),
+      essentialMissing: essentialMissing.map(e => ({
+        type: e.type,
+        command: e.command,
+        label: e.label,
+        tier: e.tier,
+      })),
+      essentialPct,
+      presentTypes: [...presentTypes].sort(),
+      presentByCategory,
+    },
+    compliance: {
+      presentHigh,
+      missingHigh,
+      pct: compliancePct,
+      total: HIGH_SEVERITY_TYPES.length,
+    },
+    health: { stale: staleCount, draft: draftCount, orphan: orphanCount },
+    contextualSuggestions: contextualMissing.map(c => ({
+      command: c.command,
+      type: c.type,
+      trigger: c.trigger,
+    })),
+    hasGlobalPrin,
+    recommendations,
+  };
+}
+
+/**
+ * Compute rollups for every working project in the graph (excludes 000-global).
+ *
+ * @param {object} graph     from scanAllArtifacts
+ * @param {Date}   baseline  reference "now"
+ * @returns {object[]}       array of per-project rollups, sorted by project name
+ */
+export function computeAllProjectRollups(graph, baseline = new Date()) {
+  if (!graph || !graph.projects) return [];
+  const working = graph.projects.filter(p => p !== '000-global').sort();
+  return working.map(p => computeProjectRollup(p, graph, baseline));
+}

arckit_cli-6.1.1.data/data/share/arckit/extensions/arckit-codex/hooks/graph-utils.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * ArcKit Graph Utilities — Shared dependency graph builder
+ *
+ * Used by:
+ * - impact-scan.mjs (UserPromptSubmit hook for /arckit:impact)
+ * - sync-guides.mjs (UserPromptSubmit hook for /arckit:pages → manifest.json)
+ *
+ * v2: Optional `opts` enrich the graph with content, full requirement records,
+ * vendors, principles, risks, and external-file listings. Defaults preserve v1
+ * behaviour exactly so existing consumers need no changes. See issue #162.
+ */
+
+import { join } from 'node:path';
+import {
+  isDir, isFile, readText, listDir, listFilesRecursive, mtimeMs,
+  extractDocType, extractVersion,
+  extractDocControlFields, extractRequirementIds,
+  extractRequirementDetails, extractPrinciples, extractRiskEntries,
+} from './hook-utils.mjs';
+import { DOC_TYPES } from '../config/doc-types.mjs';
+
+const DEFAULT_OPTS = Object.freeze({
+  withNodeMetadata: false, // version, owner, classification, vendor, subdir, controlFields, reqIds
+  withContent: false,      // full text + mtimeMs
+  withPreview: false,      // ~500-char post-control preview
+  withRequirements: false, // full requirement records per project
+  withVendors: false,      // vendor structure with reviews + verdicts
+  withPrinciples: false,   // extracted principles per project
+  withRisks: false,        // extracted risk entries per project
+  withExternals: false,    // projects/*/external/ listing
+  excludeGlobal: false,    // skip 000-global
+  projectFilter: null,     // dir name or 3-digit prefix
+});
+
+function resolveOpts(opts) {
+  return { ...DEFAULT_OPTS, ...(opts || {}) };
+}
+
+/**
+ * Extract first markdown heading from content.
+ */
+export function extractTitle(content) {
+  const match = content.match(/^#\s+(.+)/m);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Classify impact severity based on document type category.
+ * HIGH = Compliance/Governance, MEDIUM = Architecture, LOW = everything else.
+ */
+export function classifySeverity(docType) {
+  const info = DOC_TYPES[docType];
+  if (!info) return 'LOW';
+  const cat = info.category;
+  if (cat === 'Compliance' || cat === 'Governance') return 'HIGH';
+  if (cat === 'Architecture') return 'MEDIUM';
+  return 'LOW';
+}
+
+/**
+ * Build a ~500-char preview by skipping the leading doc-control table.
+ */
+export function extractPreview(content, maxLen = 500) {
+  const lines = content.split('\n');
+  let inTable = false;
+  let pastControl = false;
+  const previewLines = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (!pastControl) {
+      if (trimmed.startsWith('|') || trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith('---')) {
+        if (trimmed.startsWith('|')) inTable = true;
+        else if (inTable && !trimmed.startsWith('|')) {
+          inTable = false;
+          pastControl = true;
+        }
+        continue;
+      }
+      pastControl = true;
+    }
+
+    if (pastControl && trimmed) {
+      previewLines.push(trimmed);
+    }
+
+    if (previewLines.join(' ').length >= maxLen) break;
+  }
+
+  return previewLines.join(' ').substring(0, maxLen);
+}
+
+/**
+ * Derive { subdir, vendor } from the prefix used while scanning.
+ *   ''                       → { subdir: null, vendor: null }
+ *   'decisions/'             → { subdir: 'decisions', vendor: null }
+ *   'vendors/foo/'           → { subdir: 'vendors/foo', vendor: 'foo' }
+ *   'vendors/foo/reviews/'   → { subdir: 'vendors/foo/reviews', vendor: 'foo' }
+ */
+function locationFromPrefix(prefix) {
+  if (!prefix) return { subdir: null, vendor: null };
+  const stripped = prefix.replace(/\/$/, '');
+  const vendorMatch = stripped.match(/^vendors\/([^/]+)/);
+  return { subdir: stripped, vendor: vendorMatch ? vendorMatch[1] : null };
+}
+
+/**
+ * Scan a single project directory for ARC documents and build graph data.
+ * Mutates nodes, edges, reqIndex in-place (legacy contract preserved).
+ *
+ * Optional `opts` (v2) enriches per-node fields and accumulates aggregations
+ * into the optional `aggregations` argument when provided.
+ */
+export function scanProjectDir(projectDir, projectName, nodes, edges, reqIndex, opts, aggregations) {
+  const o = resolveOpts(opts);
+  const dirsToScan = [
+    { dir: projectDir, prefix: '' },
+    { dir: join(projectDir, 'decisions'), prefix: 'decisions/' },
+    { dir: join(projectDir, 'diagrams'), prefix: 'diagrams/' },
+    { dir: join(projectDir, 'wardley-maps'), prefix: 'wardley-maps/' },
+    { dir: join(projectDir, 'data-contracts'), prefix: 'data-contracts/' },
+    { dir: join(projectDir, 'reviews'), prefix: 'reviews/' },
+    { dir: join(projectDir, 'research'), prefix: 'research/' },
+  ];
+
+  const vendorsDir = join(projectDir, 'vendors');
+  if (isDir(vendorsDir)) {
+    for (const vendor of listDir(vendorsDir)) {
+      const vd = join(vendorsDir, vendor);
+      if (isDir(vd)) {
+        dirsToScan.push({ dir: vd, prefix: `vendors/${vendor}/` });
+        const vrd = join(vd, 'reviews');
+        if (isDir(vrd)) {
+          dirsToScan.push({ dir: vrd, prefix: `vendors/${vendor}/reviews/` });
+        }
+      }
+    }
+  }
+
+  // Aggregations only populated when caller passes the bucket
+  const reqAccum = aggregations?.requirements;
+  const principlesAccum = aggregations?.principles;
+  const risksAccum = aggregations?.risks;
+
+  for (const { dir, prefix } of dirsToScan) {
+    if (!isDir(dir)) continue;
+    for (const f of listDir(dir)) {
+      if (!f.startsWith('ARC-') || !f.endsWith('.md')) continue;
+      const fp = join(dir, f);
+      if (!isFile(fp)) continue;
+
+      const content = readText(fp);
+      if (!content) continue;
+
+      const docType = extractDocType(f);
+      const fields = extractDocControlFields(content);
+      const title = extractTitle(content) || fields['Document Title'] || f;
+      const status = fields['Status'] || '';
+      const { subdir, vendor } = locationFromPrefix(prefix);
+
+      const shortId = f.replace(/-v[\d.]+\.md$/, '');
+      const fullId = f.replace(/\.md$/, '');
+
+      const reqIdsSet = extractRequirementIds(content);
+
+      // v1 fields — always populated, identical to pre-v2 output
+      const node = {
+        type: docType,
+        project: projectName,
+        path: `projects/${projectName}/${prefix}${f}`,
+        title,
+        status,
+        severity: classifySeverity(docType),
+        createdDate: fields['Created Date'] || null,
+        lastModified: fields['Last Modified'] || null,
+      };
+
+      // v2 enrichments — gated to keep impact/pages output byte-stable
+      if (o.withNodeMetadata) {
+        node.version = extractVersion(f);
+        node.owner = fields['Owner'] || fields['Document Owner'] || '';
+        node.classification = fields['Classification'] || '';
+        node.vendor = vendor;
+        node.subdir = subdir;
+        node.controlFields = fields;
+        node.reqIds = Array.from(reqIdsSet);
+      }
+      if (o.withContent) {
+        node.content = content;
+        node.mtimeMs = mtimeMs(fp);
+      }
+      if (o.withPreview) {
+        node.preview = extractPreview(content);
+      }
+
+      nodes[fullId] = node;
+
+      for (const reqId of reqIdsSet) {
+        if (!reqIndex[reqId]) reqIndex[reqId] = [];
+        if (!reqIndex[reqId].includes(fullId)) {
+          reqIndex[reqId].push(fullId);
+        }
+      }
+
+      // Extract cross-references to other ARC documents (deduplicated per source)
+      const ARC_REF_RE = /\bARC-(\d{3})-([A-Z][\w-]*?)(?:-(\d{3}))?(?:-v[\d.]+)?(?:\.md)?\b/g;
+      const seenRefs = new Set();
+      for (const m of content.matchAll(ARC_REF_RE)) {
+        const refStr = m[0].replace(/\.md$/, '');
+        const refShort = refStr.replace(/-v[\d.]+$/, '');
+        const edgeKey = fullId + '>' + refShort;
+        if (refShort !== shortId && !seenRefs.has(edgeKey)) {
+          seenRefs.add(edgeKey);
+          edges.push({ from: fullId, to: refShort, type: 'references' });
+        }
+      }
+
+      // Aggregations
+      if (reqAccum && docType === 'REQ') {
+        if (!reqAccum[projectName]) reqAccum[projectName] = [];
+        const details = extractRequirementDetails(content);
+        for (const r of details) {
+          reqAccum[projectName].push({ ...r, sourceFile: f });
+        }
+      }
+      if (principlesAccum && docType === 'PRIN') {
+        if (!principlesAccum[projectName]) principlesAccum[projectName] = [];
+        for (const p of extractPrinciples(content)) {
+          principlesAccum[projectName].push({ ...p, sourceFile: f });
+        }
+      }
+      if (risksAccum && docType === 'RISK') {
+        if (!risksAccum[projectName]) risksAccum[projectName] = [];
+        for (const r of extractRiskEntries(content)) {
+          risksAccum[projectName].push({ ...r, sourceFile: f });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Build a per-project vendor structure with reviews + verdicts.
+ */
+function scanVendors(projectDir) {
+  const vendors = [];
+  const vendorsDir = join(projectDir, 'vendors');
+  if (!isDir(vendorsDir)) return vendors;
+
+  for (const name of listDir(vendorsDir)) {
+    const vendorDir = join(vendorsDir, name);
+    if (!isDir(vendorDir)) continue;
+
+    const entry = { name, docs: [], reviews: [] };
+
+    for (const f of listDir(vendorDir)) {
+      if (!f.endsWith('.md')) continue;
+      if (!isFile(join(vendorDir, f))) continue;
+      entry.docs.push(f);
+    }
+
+    const reviewsDir = join(vendorDir, 'reviews');
+    if (isDir(reviewsDir)) {
+      for (const f of listDir(reviewsDir)) {
+        if (!f.endsWith('.md') || !isFile(join(reviewsDir, f))) continue;
+        const content = readText(join(reviewsDir, f));
+        let verdict = null;
+        if (content) {
+          if (/APPROVED\s+WITH\s+CONDITIONS/i.test(content)) verdict = 'APPROVED WITH CONDITIONS';
+          else if (/\bREJECTED\b/i.test(content)) verdict = 'REJECTED';
+          else if (/\bAPPROVED\b/i.test(content)) verdict = 'APPROVED';
+          else if (/\bPENDING\b/i.test(content)) verdict = 'PENDING';
+        }
+        entry.reviews.push({ file: f, verdict });
+      }
+    }
+
+    vendors.push(entry);
+  }
+
+  return vendors;
+}
+
+/**
+ * List files in projects/<name>/external/ recursively with mtimes
+ * (excluding README.md files).
+ */
+function scanExternals(projectDir) {
+  const externalDir = join(projectDir, 'external');
+  if (!isDir(externalDir)) return [];
+  const out = [];
+  for (const file of listFilesRecursive(externalDir)) {
+    if (file.name === 'README.md') continue;
+    out.push({
+      filename: file.relativePath,
+      path: file.path,
+      mtimeMs: mtimeMs(file.path),
+    });
+  }
+  return out;
+}
+
+/**
+ * Scan all projects in the projects/ directory and build a complete dependency graph.
+ *
+ * v1 contract preserved: with no `opts`, returns `{ nodes, edges, reqIndex, projects }`
+ * exactly as before. Optional fields (`requirements`, `vendors`, `principles`, `risks`,
+ * `externalFiles`) are added only when the corresponding flag is set.
+ */
+export function scanAllArtifacts(projectsDir, opts) {
+  const o = resolveOpts(opts);
+  const nodes = {};
+  const edges = [];
+  const reqIndex = {};
+
+  let projectDirs = listDir(projectsDir)
+    .filter(e => isDir(join(projectsDir, e)) && /^\d{3}-/.test(e));
+
+  if (o.excludeGlobal) {
+    projectDirs = projectDirs.filter(e => e !== '000-global');
+  }
+
+  if (o.projectFilter) {
+    projectDirs = projectDirs.filter(d =>
+      d === o.projectFilter || d.startsWith(o.projectFilter)
+    );
+  }
+
+  // Aggregation buckets (only built when requested)
+  const aggregations = {};
+  if (o.withRequirements) aggregations.requirements = {};
+  if (o.withPrinciples) aggregations.principles = {};
+  if (o.withRisks) aggregations.risks = {};
+
+  for (const projectName of projectDirs) {
+    const projectDir = join(projectsDir, projectName);
+    scanProjectDir(projectDir, projectName, nodes, edges, reqIndex, o, aggregations);
+  }
+
+  const result = { nodes, edges, reqIndex, projects: projectDirs };
+
+  if (o.withRequirements) result.requirements = aggregations.requirements;
+  if (o.withPrinciples) result.principles = aggregations.principles;
+  if (o.withRisks) result.risks = aggregations.risks;
+
+  if (o.withVendors) {
+    result.vendors = {};
+    for (const projectName of projectDirs) {
+      result.vendors[projectName] = scanVendors(join(projectsDir, projectName));
+    }
+  }
+
+  if (o.withExternals) {
+    result.externalFiles = {};
+    for (const projectName of projectDirs) {
+      result.externalFiles[projectName] = scanExternals(join(projectsDir, projectName));
+    }
+  }
+
+  return result;
+}