@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/config/source-targets.mjs

@@ -1,18 +1,36 @@
 /**
  * lib/config/source-targets.mjs — typed integration source targets in construct.config.json.
  *
- * Validates GitHub, Jira, Linear, and Slack selector records, merges legacy env
- * target lists additively, deduplicates by provider+selector signature, and
- * converts resolved targets into embed provider source records for auto-discovery.
+ * Validates provider selector records, merges legacy env target lists
+ * additively, deduplicates by provider+selector signature, and converts
+ * resolved targets into embed provider source records for auto-discovery.
+ *
+ * Every function here dispatches on the manifest-derived descriptors from
+ * lib/config/source-target-registry.mjs rather than naming providers
+ * directly — adding a fifth source-target-eligible provider means adding a
+ * `sourceTarget` block to that provider's manifest, not editing this file.
+ * See source-target-registry.mjs's header for what each descriptor field
+ * drives.
  */
 
-export const SOURCE_PROVIDERS = Object.freeze(['github', 'jira', 'linear', 'slack']);
+import {
+  SOURCE_TARGET_PROVIDERS,
+  getSourceTargetDescriptor,
+  listSourceTargetDescriptors,
+  renderTemplate,
+} from './source-target-registry.mjs';
+
+export const SOURCE_PROVIDERS = SOURCE_TARGET_PROVIDERS;
 
-export const SLACK_INTENTS = Object.freeze(['internal', 'risk', 'decision', 'external', 'how-to']);
+const slackDescriptor = getSourceTargetDescriptor('slack');
+export const SLACK_INTENTS = Object.freeze(slackDescriptor?.secondaryField?.enum ?? []);
 
 const ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
-const GITHUB_REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-const JIRA_PROJECT_RE = /^[A-Z][A-Z0-9]{1,9}$/;
+
+function applyPatternTransform(value, mode) {
+  if (mode === 'trimUpper') return value.trim().toUpperCase();
+  return value.trim();
+}
 
 export function validateSourceTarget(target, index = 0) {
   const errors = [];
@@ -35,34 +53,26 @@ export function validateSourceTarget(target, index = 0) {
     return errors;
   }
 
+  const descriptor = getSourceTargetDescriptor(target.provider);
+  if (!descriptor) return errors;
+
   const sel = target.selector;
-  switch (target.provider) {
-    case 'github':
-      if (typeof sel.repo !== 'string' || !GITHUB_REPO_RE.test(sel.repo.trim())) {
-        errors.push(`${at}.selector.repo: required owner/repo slug`);
-      }
-      break;
-    case 'jira':
-      if (typeof sel.project !== 'string' || !JIRA_PROJECT_RE.test(sel.project.trim().toUpperCase())) {
-        errors.push(`${at}.selector.project: required Jira project key (2–10 uppercase letters/digits)`);
-      }
-      break;
-    case 'linear':
-      if (typeof sel.team !== 'string' || !sel.team.trim()) {
-        errors.push(`${at}.selector.team: required Linear team key or name`);
-      }
-      break;
-    case 'slack': {
-      if (typeof sel.channel !== 'string' || !sel.channel.trim()) {
-        errors.push(`${at}.selector.channel: required Slack channel name or ID`);
-      }
-      if (sel.intent !== undefined && !SLACK_INTENTS.includes(sel.intent)) {
-        errors.push(`${at}.selector.intent: must be one of ${SLACK_INTENTS.join(', ')}`);
-      }
-      break;
+  const { field, pattern, patternTransform, hint } = descriptor.selector;
+  const raw = sel[field];
+  const valid = typeof raw === 'string' && (
+    pattern
+      ? new RegExp(pattern).test(applyPatternTransform(raw, patternTransform))
+      : !!raw.trim()
+  );
+  if (!valid) {
+    errors.push(`${at}.selector.${field}: ${hint}`);
+  }
+
+  if (descriptor.secondaryField) {
+    const { field: secField, enum: secEnum, hint: secHint } = descriptor.secondaryField;
+    if (sel[secField] !== undefined && !secEnum.includes(sel[secField])) {
+      errors.push(`${at}.selector.${secField}: ${secHint} ${secEnum.join(', ')}`);
     }
-    default:
-      break;
   }
 
   return errors;
@@ -101,73 +111,71 @@ function slugId(value) {
   return String(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 }
 
-function parseSlackChannelEntry(raw) {
+function parseSlackChannelEntry(raw, descriptor) {
   const trimmed = String(raw).trim().replace(/^#/, '');
   const colon = trimmed.indexOf(':');
+  const fallback = descriptor.secondaryField.default;
   if (colon === -1) {
-    return { channel: trimmed, intent: 'internal' };
+    return { channel: trimmed, intent: fallback };
   }
-  return { channel: trimmed.slice(0, colon), intent: trimmed.slice(colon + 1) || 'internal' };
+  const intent = trimmed.slice(colon + 1) || fallback;
+  return { channel: trimmed.slice(0, colon), intent };
+}
+
+function legacyEnvRawValue(vars, env) {
+  return vars.reduce((acc, name) => (acc !== undefined ? acc : env[name]), undefined);
 }
 
 export function legacyEnvSourceTargets(env = process.env) {
   const targets = [];
 
-  for (const repo of parseCsv(env.GITHUB_REPOS ?? env.GITHUB_REPO)) {
-    targets.push({
-      id: `env-github-${slugId(repo)}`,
-      provider: 'github',
-      selector: { repo },
-      provenance: 'env:GITHUB_REPOS',
-    });
-  }
-
-  for (const project of parseCsv(env.JIRA_PROJECTS)) {
-    const key = project.toUpperCase();
-    targets.push({
-      id: `env-jira-${slugId(key)}`,
-      provider: 'jira',
-      selector: { project: key },
-      provenance: 'env:JIRA_PROJECTS',
-    });
-  }
-
-  for (const team of parseCsv(env.LINEAR_TEAMS)) {
-    targets.push({
-      id: `env-linear-${slugId(team)}`,
-      provider: 'linear',
-      selector: { team },
-      provenance: 'env:LINEAR_TEAMS',
-    });
-  }
+  for (const descriptor of listSourceTargetDescriptors()) {
+    const { provider, legacyEnv, selector } = descriptor;
+    if (!legacyEnv) continue;
+    const raw = legacyEnvRawValue(legacyEnv.vars, env);
+    const provenance = `env:${legacyEnv.vars[0]}`;
+
+    if (legacyEnv.parse === 'slackChannelColon') {
+      for (const entry of parseCsv(raw)) {
+        const { channel, intent } = parseSlackChannelEntry(entry, descriptor);
+        targets.push({
+          id: `env-${provider}-${slugId(channel)}`,
+          provider,
+          selector: { [selector.field]: channel, [descriptor.secondaryField.field]: intent },
+          provenance,
+        });
+      }
+      continue;
+    }
 
-  for (const entry of parseCsv(env.SLACK_CHANNELS ?? env.SLACK_CHANNEL)) {
-    const { channel, intent } = parseSlackChannelEntry(entry);
-    targets.push({
-      id: `env-slack-${slugId(channel)}`,
-      provider: 'slack',
-      selector: { channel, intent: SLACK_INTENTS.includes(intent) ? intent : 'internal' },
-      provenance: 'env:SLACK_CHANNELS',
-    });
+    for (const entry of parseCsv(raw)) {
+      const value = legacyEnv.valueTransform === 'upper' ? entry.toUpperCase() : entry;
+      targets.push({
+        id: `env-${provider}-${slugId(value)}`,
+        provider,
+        selector: { [selector.field]: value },
+        provenance,
+      });
+    }
   }
 
   return targets;
 }
 
+function signatureValue(raw, mode) {
+  if (mode === 'optionalLower') return raw?.trim().toLowerCase();
+  if (mode === 'upperOrEmpty') return String(raw ?? '').trim().toUpperCase();
+  return String(raw ?? '').trim().toLowerCase();
+}
+
 export function targetSignature(target) {
   const sel = target.selector ?? {};
-  switch (target.provider) {
-    case 'github':
-      return `github:repo:${sel.repo?.trim().toLowerCase()}`;
-    case 'jira':
-      return `jira:project:${String(sel.project ?? '').trim().toUpperCase()}`;
-    case 'linear':
-      return `linear:team:${String(sel.team ?? '').trim().toLowerCase()}`;
-    case 'slack':
-      return `slack:channel:${String(sel.channel ?? '').trim().toLowerCase()}:intent:${sel.intent ?? 'internal'}`;
-    default:
-      return `${target.provider}:${JSON.stringify(sel)}`;
-  }
+  const descriptor = getSourceTargetDescriptor(target.provider);
+  if (!descriptor) return `${target.provider}:${JSON.stringify(sel)}`;
+
+  const value = signatureValue(sel[descriptor.selector.field], descriptor.signature.valueMode);
+  const intent = descriptor.secondaryField ? (sel[descriptor.secondaryField.field] ?? descriptor.secondaryField.default) : undefined;
+  return renderTemplate(descriptor.signature.template, { value, intent });
 }
 
 export function mergeSourceTargets(configTargets = [], envTargets = []) {
@@ -191,19 +199,21 @@ export function normalizeConfigTarget(raw) {
     provenance: raw.provenance ?? 'config',
   };
 
-  if (out.provider === 'jira' && out.selector.project) {
-    out.selector.project = String(out.selector.project).trim().toUpperCase();
-  }
-  if (out.provider === 'github' && out.selector.repo) {
-    out.selector.repo = String(out.selector.repo).trim();
-  }
-  if (out.provider === 'linear' && out.selector.team) {
-    out.selector.team = String(out.selector.team).trim();
+  const descriptor = getSourceTargetDescriptor(out.provider);
+  if (!descriptor) return out;
+
+  const { field, normalize } = descriptor.selector;
+  if (out.selector[field]) {
+    const value = String(out.selector[field]);
+    out.selector[field] = normalize === 'trimHash'
+      ? value.trim().replace(/^#/, '')
+      : applyPatternTransform(value, normalize === 'trimUpper' ? 'trimUpper' : 'trim');
   }
-  if (out.provider === 'slack' && out.selector.channel) {
-    out.selector.channel = String(out.selector.channel).trim().replace(/^#/, '');
-    if (!out.selector.intent) out.selector.intent = 'internal';
+
+  if (descriptor.secondaryField && !out.selector[descriptor.secondaryField.field]) {
+    out.selector[descriptor.secondaryField.field] = descriptor.secondaryField.default;
   }
+
   return out;
 }
 
@@ -215,55 +225,41 @@ export function resolveEffectiveSourceTargetsFromConfig(config, env = process.en
 
 export function targetsToEmbedSources(targets) {
   const sources = [];
-  const githubRepos = targets.filter((t) => t.provider === 'github').map((t) => t.selector.repo);
-  if (githubRepos.length) {
-    sources.push({
-      provider: 'github',
-      repos: githubRepos,
-      refs: ['prs', 'issues', 'commits'],
-      limit: 25,
-    });
-    sources.push({
-      provider: 'github',
-      repos: githubRepos,
-      refs: ['meta', 'readme', 'docs'],
-      limit: 25,
-    });
-  }
-
-  for (const target of targets.filter((t) => t.provider === 'jira')) {
-    sources.push({
-      provider: 'jira',
-      project: target.selector.project,
-      refs: ['issues'],
-      limit: 50,
-    });
-  }
 
-  for (const target of targets.filter((t) => t.provider === 'linear')) {
-    sources.push({
-      provider: 'linear',
-      team: target.selector.team,
-      refs: ['issues'],
-      limit: 50,
-    });
-  }
-
-  const slackByIntent = new Map();
-  for (const target of targets.filter((t) => t.provider === 'slack')) {
-    const intent = target.selector.intent ?? 'internal';
-    if (!slackByIntent.has(intent)) slackByIntent.set(intent, []);
-    slackByIntent.get(intent).push(target.selector.channel);
-  }
-  for (const [intent, channels] of slackByIntent) {
-    sources.push({
-      provider: 'slack',
-      channels,
-      intent,
-      refs: ['messages'],
-      oldest: 86400,
-      limit: 50,
-    });
+  for (const descriptor of listSourceTargetDescriptors()) {
+    const { provider, embed } = descriptor;
+    if (!embed) continue;
+    const selField = descriptor.selector.field;
+    const providerTargets = targets.filter((t) => t.provider === provider);
+    if (!providerTargets.length) continue;
+
+    if (embed.mode === 'aggregate') {
+      const values = providerTargets.map((t) => t.selector[selField]);
+      for (const group of embed.groups) {
+        sources.push({ provider, [embed.valueField]: values, refs: group.refs, limit: group.limit });
+      }
+    } else if (embed.mode === 'perTarget') {
+      for (const target of providerTargets) {
+        sources.push({ provider, [embed.valueField]: target.selector[selField], refs: embed.refs, limit: embed.limit });
+      }
+    } else if (embed.mode === 'groupBy') {
+      const byGroup = new Map();
+      for (const target of providerTargets) {
+        const key = target.selector[embed.groupField] ?? embed.groupDefault;
+        if (!byGroup.has(key)) byGroup.set(key, []);
+        byGroup.get(key).push(target.selector[selField]);
+      }
+      for (const [key, values] of byGroup) {
+        sources.push({
+          provider,
+          [embed.valueField]: values,
+          [embed.groupField]: key,
+          refs: embed.refs,
+          oldest: embed.oldest,
+          limit: embed.limit,
+        });
+      }
+    }
   }
 
   return sources;
@@ -273,38 +269,33 @@ export function resolveKnownSourcesFromTargets(targets) {
   const sources = [];
 
   for (const target of targets) {
+    const descriptor = getSourceTargetDescriptor(target.provider);
+    if (!descriptor) continue;
     const sel = target.selector ?? {};
-    if (target.provider === 'github' && sel.repo) {
-      const repo = sel.repo;
-      const short = repo.split('/').pop();
-      sources.push({ id: repo.toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
-      sources.push({ id: short.toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
-      sources.push({ id: short.replace(/-/g, '').toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+    const value = sel[descriptor.selector.field];
+    if (!value) continue;
+
+    const display = descriptor.aliases.displayPrefix ? `${descriptor.aliases.displayPrefix}/${value}` : value;
+
+    if (descriptor.aliases.strategy === 'repoWords') {
+      const short = value.split('/').pop();
+      sources.push({ id: value.toLowerCase(), provider: target.provider, ref: value, display, targetId: target.id });
+      sources.push({ id: short.toLowerCase(), provider: target.provider, ref: value, display, targetId: target.id });
+      sources.push({ id: short.replace(/-/g, '').toLowerCase(), provider: target.provider, ref: value, display, targetId: target.id });
       const words = short.split('-');
       if (words.length > 1) {
-        sources.push({ id: words[words.length - 1].toLowerCase(), provider: 'github', ref: repo, display: repo, targetId: target.id });
+        sources.push({ id: words[words.length - 1].toLowerCase(), provider: target.provider, ref: value, display, targetId: target.id });
       }
-    }
-    if (target.provider === 'jira' && sel.project) {
-      const key = sel.project;
-      sources.push({ id: key.toLowerCase(), provider: 'jira', ref: key, display: `Jira/${key}`, targetId: target.id });
-    }
-    if (target.provider === 'linear' && sel.team) {
-      const team = sel.team;
-      sources.push({ id: team.toLowerCase(), provider: 'linear', ref: team, display: `Linear/${team}`, targetId: target.id });
-    }
-    if (target.provider === 'slack' && sel.channel) {
-      const ch = sel.channel;
-      sources.push({ id: ch.toLowerCase(), provider: 'slack', ref: ch, display: `Slack/${ch}`, targetId: target.id });
+    } else {
+      sources.push({ id: value.toLowerCase(), provider: target.provider, ref: value, display, targetId: target.id });
     }
   }
 
   const providers = new Set(targets.map((t) => t.provider));
-  if (providers.has('jira')) {
-    sources.push({ id: 'jira', provider: 'jira', ref: null, display: 'Jira' });
-  }
-  if (providers.has('linear')) {
-    sources.push({ id: 'linear', provider: 'linear', ref: null, display: 'Linear' });
+  for (const descriptor of listSourceTargetDescriptors()) {
+    if (descriptor.aliases.catchAll && providers.has(descriptor.provider)) {
+      sources.push({ id: descriptor.provider, provider: descriptor.provider, ref: null, display: descriptor.aliases.displayPrefix });
+    }
   }
 
   return sources;
@@ -343,48 +334,31 @@ export function targetsToEmbedSourcesWithFilters(targets, { teamId = null } = {}
   });
 
   for (const target of targets) {
+    const descriptor = getSourceTargetDescriptor(target.provider);
+    if (!descriptor?.embedFilters) continue;
+    const ef = descriptor.embedFilters;
     const f = target.filters ?? {};
     const sel = target.selector ?? {};
-    switch (target.provider) {
-      case 'github':
-        sources.push(tag({
-          provider: 'github',
-          repos: [sel.repo],
-          refs: Array.isArray(f.refs) ? f.refs : ['prs', 'issues', 'commits'],
-          limit: Number.isInteger(f.limit) ? f.limit : 25,
-        }, target));
-        break;
-      case 'jira':
-        sources.push(tag({
-          provider: 'jira',
-          project: sel.project,
-          refs: ['issues'],
-          ...(typeof f.jql === 'string' ? { jql: f.jql } : {}),
-          limit: Number.isInteger(f.limit) ? f.limit : 50,
-        }, target));
-        break;
-      case 'linear':
-        sources.push(tag({
-          provider: 'linear',
-          team: sel.team,
-          refs: ['issues'],
-          ...(Array.isArray(f.states) ? { states: f.states } : {}),
-          limit: Number.isInteger(f.limit) ? f.limit : 50,
-        }, target));
-        break;
-      case 'slack':
-        sources.push(tag({
-          provider: 'slack',
-          channels: [sel.channel],
-          intent: sel.intent ?? 'internal',
-          refs: ['messages'],
-          oldest: Number.isInteger(f.oldest) ? f.oldest : 86400,
-          limit: Number.isInteger(f.limit) ? f.limit : 50,
-        }, target));
-        break;
-      default:
-        break;
+    const selField = descriptor.selector.field;
+
+    const rec = {
+      provider: target.provider,
+      [ef.valueField]: ef.valueKind === 'array' ? [sel[selField]] : sel[selField],
+      refs: ef.refsFilterKey && Array.isArray(f[ef.refsFilterKey]) ? f[ef.refsFilterKey] : ef.defaultRefs,
+      limit: Number.isInteger(f.limit) ? f.limit : ef.defaultLimit,
+    };
+
+    if (ef.includeSecondaryField && descriptor.secondaryField) {
+      rec[descriptor.secondaryField.field] = sel[descriptor.secondaryField.field] ?? descriptor.secondaryField.default;
     }
+
+    for (const key of ef.extraFilterKeys ?? []) {
+      if (key === 'jql' && typeof f.jql === 'string') rec.jql = f.jql;
+      if (key === 'states' && Array.isArray(f.states)) rec.states = f.states;
+      if (key === 'oldest') rec.oldest = Number.isInteger(f.oldest) ? f.oldest : descriptor.embed?.oldest;
+    }
+
+    sources.push(tag(rec, target));
   }
 
   return sources;

package/lib/contracts/coverage.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/contracts/coverage.mjs — executable-postcondition coverage for
+ * specialists/org/contracts/*.json (construct-rf26.12).
+ *
+ * A contract's postconditions are pure prose unless something mechanical
+ * evaluates them. This module measures the split: how many postconditions,
+ * across the full contract set, are tagged `postconditionType: 'executable'`
+ * (backed by a real check — see lib/contracts/validate.mjs's file header for
+ * the four enforcement mechanisms) versus `'advisory'` (documented, not
+ * mechanically checked). A legacy bare-string postcondition counts as
+ * neither classified kind and is reported separately — it should not occur
+ * in the shipped contract set after the rf26.12 migration, so a nonzero
+ * count here is itself a drift signal.
+ *
+ * Pure and deterministic: same registry -> same report. Consumed by
+ * `construct doctor consistency` (lib/doctor/watchers/consistency.mjs) and
+ * by tests/contracts-coverage.test.mjs as the durable coverage assertion.
+ */
+
+import { loadRegistry } from '../registry/loader.mjs';
+
+/**
+ * Compute postcondition coverage across every contract in the unified
+ * registry. Returns per-contract counts plus an aggregate summary.
+ */
+export function computePostconditionCoverage({ repoRoot } = {}) {
+  const registry = loadRegistry(repoRoot ? { rootDir: repoRoot } : undefined);
+  const contracts = Object.values(registry.contracts || {});
+
+  const perContract = [];
+  let executable = 0;
+  let advisory = 0;
+  let unclassified = 0;
+
+  for (const contract of contracts) {
+    let cExecutable = 0;
+    let cAdvisory = 0;
+    let cUnclassified = 0;
+    for (const pc of contract.postconditions || []) {
+      if (typeof pc !== 'object' || pc === null) { cUnclassified += 1; continue; }
+      if (pc.postconditionType === 'executable') cExecutable += 1;
+      else if (pc.postconditionType === 'advisory') cAdvisory += 1;
+      else cUnclassified += 1;
+    }
+    const total = cExecutable + cAdvisory + cUnclassified;
+    executable += cExecutable;
+    advisory += cAdvisory;
+    unclassified += cUnclassified;
+    perContract.push({
+      id: contract.id,
+      total,
+      executable: cExecutable,
+      advisory: cAdvisory,
+      unclassified: cUnclassified,
+      coveragePct: total === 0 ? null : Math.round((cExecutable / total) * 1000) / 10,
+    });
+  }
+
+  const total = executable + advisory + unclassified;
+  return {
+    contractCount: contracts.length,
+    total,
+    executable,
+    advisory,
+    unclassified,
+    coveragePct: total === 0 ? 0 : Math.round((executable / total) * 1000) / 10,
+    perContract: perContract.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+  };
+}
+
+/**
+ * One-line human summary, matching the style of `construct decisions`
+ * (lib/decisions/registry.mjs's `Decisions: N (M enforced, K advisory)`).
+ */
+export function formatCoverageSummary(coverage) {
+  return `contract postconditions: ${coverage.total} (${coverage.executable} executable, ${coverage.advisory} advisory, ${coverage.coveragePct}% executable)`;
+}