@juangcarmona/lighthouse-sdlc 0.2.0 → 0.4.0

package/src/decompose.mjs

@@ -0,0 +1,53 @@
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function orderSlices(slices) {
+  const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  const visiting = new Set();
+  const visited = new Set();
+  const ordered = [];
+  const errors = [];
+  function visit(id) {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) { errors.push(issue('decompose.cycle', `dependency cycle includes ${id}`, 'slices')); return; }
+    visiting.add(id);
+    for (const dependency of byId.get(id)?.dependencies ?? []) if (byId.has(dependency)) visit(dependency);
+    visiting.delete(id);
+    visited.add(id);
+    ordered.push(id);
+  }
+  for (const slice of slices) visit(slice.id);
+  return { ordered, errors };
+}
+
+export function buildDecompositionPlan(input) {
+  const errors = [];
+  if (!isRecord(input)) return { schemaVersion: 1, status: 'invalid', valid: false, canApply: false, errors: [issue('decompose.invalid', 'decomposition input must be an object')] };
+  if (input.schemaVersion !== 1) errors.push(issue('decompose.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (!isRecord(input.parent) || typeof input.parent.id !== 'string' || !input.parent.id.trim() || typeof input.parent.title !== 'string' || !input.parent.title.trim()) errors.push(issue('decompose.parent', 'parent needs id and title', 'parent'));
+  if (!Array.isArray(input.slices) || input.slices.length === 0) errors.push(issue('decompose.slices', 'slices must be a non-empty array', 'slices'));
+  const ids = new Set();
+  const slices = Array.isArray(input.slices) ? input.slices.map((slice, index) => {
+    if (!isRecord(slice) || typeof slice.id !== 'string' || !slice.id.trim() || typeof slice.title !== 'string' || !slice.title.trim()) { errors.push(issue('decompose.slice', `slice ${index} needs id and title`, `slices[${index}]`)); return null; }
+    if (ids.has(slice.id)) errors.push(issue('decompose.duplicate', `slice ${slice.id} appears more than once`, `slices[${index}].id`));
+    ids.add(slice.id);
+    if (!Array.isArray(slice.dependencies)) errors.push(issue('decompose.dependencies', `slice ${slice.id} needs a dependencies array`, `slices[${index}].dependencies`));
+    if (!Array.isArray(slice.acceptance) || slice.acceptance.length === 0 || slice.acceptance.some((item) => typeof item !== 'string' || !item.trim())) errors.push(issue('decompose.acceptance', `slice ${slice.id} needs independent acceptance evidence`, `slices[${index}].acceptance`));
+    return { id: slice.id, title: slice.title, acceptance: [...(slice.acceptance ?? [])], dependencies: [...(slice.dependencies ?? [])].sort(), scope: [...(slice.scope ?? [])].sort(), labels: [...(slice.labels ?? [])].sort() };
+  }).filter(Boolean) : [];
+  for (const slice of slices) for (const dependency of slice.dependencies) if (!ids.has(dependency)) errors.push(issue('decompose.unknown-dependency', `slice ${slice.id} depends on unknown slice ${dependency}`, 'slices'));
+  const order = orderSlices(slices);
+  errors.push(...order.errors);
+  const status = errors.length ? 'invalid' : 'ready';
+  return { schemaVersion: 1, status, valid: errors.length === 0, canApply: status === 'ready', parent: input.parent ?? null, slices, order: order.ordered, operations: status === 'ready' ? order.ordered.map((id) => ({ type: 'create-child', parentId: input.parent?.id, sliceId: id })) : [], errors };
+}
+
+export function applyDecompositionPlan(plan) {
+  if (!plan?.canApply) throw new Error('Decomposition plan is not ready to apply. Resolve its errors first.');
+  return { ...plan, applied: true };
+}

package/src/github.mjs

@@ -0,0 +1,67 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export async function ghJson(args, { command = 'gh', cwd } = {}) {
+  const { stdout } = await execFileAsync(command, ['api', ...args], { cwd, maxBuffer: 10 * 1024 * 1024 });
+  return JSON.parse(stdout);
+}
+
+export async function readGithubIssue(repo, number, options = {}) {
+  if (!repo || !number) throw new Error('repo and issue number are required');
+  const issueRecord = await ghJson([`repos/${repo}/issues/${number}`], options);
+  return {
+    schemaVersion: 1,
+    workItem: { id: `GH-${issueRecord.number}`, title: issueRecord.title, type: issueRecord.pull_request ? 'pull-request' : 'issue', url: issueRecord.html_url, state: issueRecord.state },
+    currentLabels: (issueRecord.labels ?? []).map((label) => typeof label === 'string' ? label : label.name).filter(Boolean).sort(),
+    links: { url: issueRecord.html_url, parent: issueRecord.parent ?? null, subIssues: issueRecord.sub_issues ?? [] },
+    dependencies: issueRecord.dependencies ?? [],
+    source: { provider: 'github', repository: repo, number: issueRecord.number },
+  };
+}
+
+export async function readGithubLabels(repo, options = {}) {
+  if (!repo) throw new Error('repo is required');
+  const labels = await ghJson([`repos/${repo}/labels?per_page=100`], options);
+  return Array.isArray(labels) ? labels.map((label) => ({ name: label.name, color: label.color, description: label.description ?? null })).sort((left, right) => left.name.localeCompare(right.name)) : [];
+}
+
+export async function createGithubLabel(repo, label, options = {}) {
+  if (!label?.name) throw new Error('label name is required');
+  if (options.dryRun !== false) return { applied: false, label };
+  const created = await ghJson(['--method', 'POST', `repos/${repo}/labels`, '-f', `name=${label.name}`, '-f', `color=${String(label.color ?? '8B949E').replace(/^#/u, '')}`, '-f', `description=${label.description ?? ''}`], options);
+  return { applied: true, label: { name: created.name, color: created.color, description: created.description ?? null } };
+}
+
+export function mergeGithubTriage(issueRecord, assessment, configuration) {
+  if (!issueRecord || typeof issueRecord !== 'object') return { errors: [issue('github.issue', 'issue metadata is required')] };
+  if (!assessment || typeof assessment !== 'object') return { errors: [issue('github.assessment', 'structured assessment is required')] };
+  return { ...issueRecord, assessment, configuration };
+}
+
+export async function replaceGithubLabels(repo, number, labels, options = {}) {
+  if (!Array.isArray(labels)) throw new Error('labels must be an array');
+  if (options.dryRun !== false) return { applied: false, labels: [...labels] };
+  const { stdout } = await execFileAsync(options.command ?? 'gh', ['api', '--method', 'PUT', `repos/${repo}/issues/${number}/labels`, ...labels.flatMap((label) => ['-f', `labels[]=${label}`])], { cwd: options.cwd, maxBuffer: 10 * 1024 * 1024 });
+  return { applied: true, labels: JSON.parse(stdout).map((label) => label.name).sort() };
+}
+
+export async function createGithubSubIssues(repo, parentNumber, plan, options = {}) {
+  if (!plan?.canApply) throw new Error('Decomposition plan is not ready to apply. Resolve its errors first.');
+  const operations = plan.order.map((id) => {
+    const slice = plan.slices.find((candidate) => candidate.id === id);
+    return { type: 'create-child-issue', parent: Number(parentNumber), sliceId: id, title: slice.title, body: `Parent issue: #${parentNumber}\n\nAcceptance evidence:\n${slice.acceptance.map((item) => `- ${item}`).join('\n')}` };
+  });
+  if (options.dryRun !== false) return { applied: false, operations };
+  const created = [];
+  for (const operation of operations) {
+    const issueRecord = await ghJson(['--method', 'POST', `repos/${repo}/issues`, '-f', `title=${operation.title}`, '-f', `body=${operation.body}`], options);
+    created.push({ ...operation, number: issueRecord.number, url: issueRecord.html_url });
+  }
+  return { applied: true, operations: created };
+}

package/src/memory.mjs

@@ -0,0 +1,22 @@
+export const MEMORY_SCOPES = Object.freeze(['run', 'project', 'shared']);
+const scopeSet = new Set(MEMORY_SCOPES);
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function validateMemoryRecord(record, policy = {}) {
+  const errors = [];
+  if (!isRecord(record)) return [issue('memory.invalid', 'memory record must be an object')];
+  for (const field of ['id', 'owner', 'source', 'confidence', 'retention', 'sensitivity']) if (typeof record[field] !== 'string' || !record[field].trim()) errors.push(issue(`memory.${field}`, `${field} must be a non-empty string`, field));
+  if (!scopeSet.has(record.scope)) errors.push(issue('memory.scope', `scope must be one of ${MEMORY_SCOPES.join(', ')}`, 'scope'));
+  if (record.scope === 'run' && (typeof record.runId !== 'string' || !record.runId.trim())) errors.push(issue('memory.run-id', 'run-scoped memory needs runId', 'runId'));
+  if (record.scope === 'project' && (typeof record.projectId !== 'string' || !record.projectId.trim())) errors.push(issue('memory.project-id', 'project-scoped memory needs projectId', 'projectId'));
+  if (record.scope === 'shared' && policy.shared !== true) errors.push(issue('memory.shared-disabled', 'shared memory is not enabled by the control-plane policy', 'scope'));
+  if (!isRecord(record.value)) errors.push(issue('memory.value', 'value must be an object', 'value'));
+  return errors;
+}

package/src/reconcile.mjs

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import { validateConfiguration, suggestedLabelColors } from './triage.mjs';
+
+const CAPABILITY_ID = 'labels';
+const SUPPORTED_PROVIDER = 'github';
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (!isRecord(value)) return JSON.stringify(value);
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`;
+}
+
+function digest(value) {
+  return createHash('sha256').update(stable(value)).digest('hex');
+}
+
+function color(value) {
+  return typeof value === 'string' ? value.replace(/^#/u, '').toUpperCase() : null;
+}
+
+function comparableName(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]/gu, '');
+}
+
+function normalizeExisting(labels) {
+  const errors = [];
+  if (!Array.isArray(labels)) return { labels: [], errors: [issue('labels.existing', 'existing labels must be an array', 'existing')] };
+  const seen = new Set();
+  const normalized = [];
+  for (const [index, item] of labels.entries()) {
+    const value = typeof item === 'string' ? { name: item } : item;
+    if (!isRecord(value) || typeof value.name !== 'string' || !value.name.trim()) {
+      errors.push(issue('labels.existing-item', `existing label ${index} needs a name`, `existing[${index}]`));
+      continue;
+    }
+    const name = value.name.trim();
+    if (seen.has(name)) errors.push(issue('labels.existing-duplicate', `existing label ${name} appears more than once`, 'existing'));
+    seen.add(name);
+    normalized.push({ name, color: color(value.color), description: value.description ?? null });
+  }
+  normalized.sort((left, right) => left.name.localeCompare(right.name));
+  return { labels: normalized, errors };
+}
+
+function capabilityConfig(capability) {
+  return capability?.configuration && isRecord(capability.configuration) ? capability.configuration : capability;
+}
+
+export function validateCapabilityDeclaration(declaration) {
+  const errors = [];
+  if (!isRecord(declaration)) return [issue('capabilities.invalid', 'capability declaration must be an object')];
+  if (declaration.schemaVersion !== 1) errors.push(issue('capabilities.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (!Array.isArray(declaration.capabilities) || declaration.capabilities.length === 0) {
+    errors.push(issue('capabilities.list', 'capabilities must be a non-empty array', 'capabilities'));
+    return errors;
+  }
+  const selected = declaration.capabilities.filter((capability) => capability?.id === CAPABILITY_ID);
+  if (selected.length !== 1) errors.push(issue('capabilities.labels-selection', 'exactly one labels capability must be selected', 'capabilities'));
+  for (const [index, capability] of declaration.capabilities.entries()) {
+    if (!isRecord(capability) || typeof capability.id !== 'string' || !capability.id.trim()) {
+      errors.push(issue('capability.invalid', `capability ${index} needs an id`, `capabilities[${index}]`));
+      continue;
+    }
+    if (typeof capability.provider !== 'string' || !capability.provider.trim()) errors.push(issue('capability.provider', `capability ${capability.id} needs a provider`, `capabilities[${index}].provider`));
+    if (typeof capability.version !== 'string' || !capability.version.trim()) errors.push(issue('capability.version', `capability ${capability.id} needs a version`, `capabilities[${index}].version`));
+  }
+  const labels = selected[0];
+  if (labels) errors.push(...validateConfiguration(capabilityConfig(labels)).errors);
+  return errors;
+}
+
+export function buildLabelReconciliationPlan(declaration, existingLabels, previousRecord = null) {
+  const errors = validateCapabilityDeclaration(declaration);
+  const capability = declaration?.capabilities?.find((item) => item?.id === CAPABILITY_ID);
+  const existing = normalizeExisting(existingLabels);
+  errors.push(...existing.errors);
+  if (capability && capability.provider !== SUPPORTED_PROVIDER) errors.push(issue('capability.provider-unsupported', `labels provider ${capability.provider} is not supported by this adapter`, 'capabilities'));
+  const configuration = capabilityConfig(capability);
+  const desired = (Array.isArray(configuration?.labels) ? configuration.labels : []).filter((label) => isRecord(label) && typeof label.name === 'string' && label.name.trim()).map((label) => ({
+    name: label.name.trim(),
+    color: color(label.color ?? suggestedLabelColors[label.name]),
+    description: label.description ?? null,
+    role: label.role,
+    dimension: label.dimension,
+    value: label.value,
+  })).sort((left, right) => left.name.localeCompare(right.name));
+  const existingByName = new Map(existing.labels.map((label) => [label.name, label]));
+  const existingByComparableName = new Map();
+  for (const label of existing.labels) {
+    const key = comparableName(label.name);
+    existingByComparableName.set(key, [...(existingByComparableName.get(key) ?? []), label]);
+  }
+  const desiredNames = new Set();
+  const changes = [];
+  const operations = [];
+  for (const label of desired) {
+    if (desiredNames.has(label.name)) {
+      errors.push(issue('labels.desired-duplicate', `desired label ${label.name} appears more than once`, 'capabilities'));
+      continue;
+    }
+    desiredNames.add(label.name);
+    const current = existingByName.get(label.name);
+    if (!current) {
+      const equivalents = existingByComparableName.get(comparableName(label.name)) ?? [];
+      if (equivalents.length) {
+        changes.push({ name: label.name, status: 'conflict', desired: label, candidates: equivalents });
+        continue;
+      }
+      changes.push({ name: label.name, status: 'missing', desired: label });
+      operations.push({ type: 'create-label', name: label.name, color: label.color ?? '8B949E', description: label.description ?? '' });
+      continue;
+    }
+    const customized = (label.color !== null && current.color !== label.color) || (label.description !== null && current.description !== label.description);
+    changes.push({ name: label.name, status: customized ? 'customized' : 'unchanged', existing: current, desired: label });
+  }
+  for (const label of existing.labels) if (!desiredNames.has(label.name)) changes.push({ name: label.name, status: 'preserved', existing: label });
+  changes.sort((left, right) => left.name.localeCompare(right.name));
+  const target = [...existing.labels, ...operations.map((operation) => ({ name: operation.name, color: operation.color, description: operation.description }))].sort((left, right) => left.name.localeCompare(right.name));
+  const observedHash = digest(existing.labels);
+  const targetHash = digest(target);
+  const drift = previousRecord && previousRecord.targetHash !== observedHash
+    ? { status: 'drift', expectedHash: previousRecord.targetHash, observedHash }
+    : { status: 'none', expectedHash: previousRecord?.targetHash ?? null, observedHash };
+  const conflicts = changes.filter((change) => change.status === 'conflict');
+  const status = errors.length ? 'invalid' : conflicts.length ? 'blocked' : 'ready';
+  return {
+    schemaVersion: 1,
+    status,
+    valid: errors.length === 0,
+    canApply: status === 'ready',
+    capability: capability ? { id: capability.id, provider: capability.provider, version: capability.version } : null,
+    desiredHash: digest(desired),
+    observedHash,
+    targetHash,
+    drift,
+    changes,
+    operations,
+    errors,
+    record: {
+      schemaVersion: 1,
+      capability: capability ? { id: capability.id, provider: capability.provider, version: capability.version } : null,
+      desiredHash: digest(desired),
+      observedHash: targetHash,
+      targetHash,
+      operations: operations.map(({ type, name, color: labelColor, description }) => ({ type, name, color: labelColor, description })),
+      verified: false,
+    },
+  };
+}
+
+export function applyLabelReconciliationPlan(plan, existingLabels) {
+  if (!plan?.canApply) throw new Error('Label reconciliation is not ready to apply. Resolve its errors first.');
+  const existing = normalizeExisting(existingLabels);
+  if (existing.errors.length) throw new Error(existing.errors.map((error) => error.message).join('\n'));
+  const names = new Set(existing.labels.map((label) => label.name));
+  return [...existing.labels, ...plan.operations.filter((operation) => !names.has(operation.name)).map((operation) => ({ name: operation.name, color: operation.color, description: operation.description }))].sort((left, right) => left.name.localeCompare(right.name));
+}

package/src/routes.mjs

@@ -0,0 +1,22 @@
+import { GATES, STAGES } from './contracts.mjs';
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function validateRouteDescriptor(route, contract = {}) {
+  const errors = [];
+  if (!route || typeof route !== 'object') return [issue('route.invalid', 'route must be an object')];
+  if (typeof route.id !== 'string' || !route.id.trim()) errors.push(issue('route.id', 'route id must be a non-empty string', 'id'));
+  if (!Array.isArray(route.stages) || route.stages.length === 0 || route.stages.some((stage) => !STAGES.includes(stage))) errors.push(issue('route.stages', `stages must use ${STAGES.join(', ')}`, 'stages'));
+  if (!Array.isArray(route.humanGates) || route.humanGates.some((gate) => !GATES.includes(gate))) errors.push(issue('route.gates', `humanGates must use ${GATES.join(', ')}`, 'humanGates'));
+  if (contract.stages && route.stages?.some((stage, index) => stage !== contract.stages[index])) errors.push(issue('route.order', 'route stages must preserve the package stage order', 'stages'));
+  return errors;
+}
+
+export function buildRoutePlan(route, { available = [], decisions = {} } = {}) {
+  const errors = validateRouteDescriptor(route);
+  const prerequisites = (route.requires ?? []).map((requirement) => ({ id: requirement, status: available.includes(requirement) ? 'passed' : 'pending-review' }));
+  const status = errors.length ? 'invalid' : prerequisites.some((item) => item.status !== 'passed') ? 'blocked' : 'ready';
+  return { schemaVersion: 1, status, valid: errors.length === 0, canRun: status === 'ready', route: route.id, stages: [...(route.stages ?? [])], humanGates: [...(route.humanGates ?? [])], requires: prerequisites, decisions, errors };
+}