simt-dev 0.2.2 → 0.3.1

package/src/index/govern.mjs

@@ -0,0 +1,222 @@
+// What governs a file (R25, ADR-093).
+//
+// A decision governs the files its Affects line names. The line is prose, so the
+// only tokens that count are the ones in backticks, joined across the lines the
+// paragraph wraps onto. A rule governs a file its scope matches. A skill, a gate
+// and a lesson do the same with their own path list. Nothing here is stored: the
+// answer is the records on disk.
+
+const SIBLING = /^\*{0,2}[A-Z][\w-]*(?:[ \t]+[\w-]+){0,3}:\*{0,2}(?:[ \t]|$)/;
+const HEADING = /^#{1,6}\s/;
+const TOOL = /^(?:simt-dev|simt)\b/;
+
+/** Backticked tokens of the Affects paragraph, in order. */
+export function affectsTokens(text) {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex((line) => /^\s*\*{0,2}Affects:\*{0,2}/.test(line));
+  if (start < 0) return [];
+  const parts = [lines[start].replace(/^\s*\*{0,2}Affects:\*{0,2}\s*/, '')];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line.trim() === '' || SIBLING.test(line) || HEADING.test(line)) break;
+    parts.push(line);
+  }
+  return [...parts.join('\n').matchAll(/`([^`]+)`/g)].map((match) => match[1].trim()).filter(Boolean);
+}
+
+/**
+ * Directories named src. A path written from inside one (`hooks/dispatcher.mjs`)
+ * resolves against each of them, after the repo root has already been tried.
+ * @param {Iterable<string>} files
+ */
+export function sourceRoots(files) {
+  const roots = new Set();
+  for (const file of files) {
+    const parts = file.split('/');
+    for (let i = 0; i < parts.length - 1; i += 1) {
+      if (parts[i] === 'src') roots.add(parts.slice(0, i + 1).join('/'));
+    }
+  }
+  return [...roots].sort();
+}
+
+/**
+ * One Affects token.
+ *
+ * A prefixed command (`simt-dev init`, `simt hooks run`) is a command only when
+ * that command exists. The tool name on its own is not a command and not a path.
+ * Anything else is a path or a glob, at the repo root and then under each source
+ * root. A token that is none of those is unresolved.
+ *
+ * @param {string} token
+ * @param {{files: Set<string>, commands: Set<string>, roots: string[]}} ctx
+ * @returns {{kind: 'command', id: string}|{kind: 'paths', paths: string[]}|{kind: 'unresolved', token: string}}
+ */
+export function resolveToken(token, { files, commands, roots }) {
+  const text = token.trim();
+  const command = commandOf(text, commands);
+  if (command !== undefined) {
+    return command === null ? { kind: 'unresolved', token: text } : { kind: 'command', id: command };
+  }
+  const paths = new Set();
+  for (const candidate of candidates(text, roots)) {
+    if (hasGlob(candidate)) {
+      for (const file of files) if (matchGlob(candidate, file)) paths.add(file);
+    } else if (files.has(candidate)) paths.add(candidate);
+  }
+  if (paths.size > 0) return { kind: 'paths', paths: [...paths].sort() };
+  return { kind: 'unresolved', token: text };
+}
+
+/** Decisions whose Affects line names this file, and tokens that named nothing. */
+export function decisionHits(records, file, ctx) {
+  const hits = [];
+  const unresolved = [];
+  for (const record of records) {
+    let named = false;
+    for (const token of affectsTokens(record.text)) {
+      const resolved = resolveToken(token, ctx);
+      if (resolved.kind === 'unresolved') unresolved.push({ token: resolved.token, id: record.id });
+      else if (resolved.kind === 'paths' && resolved.paths.includes(file)) named = true;
+    }
+    if (named) hits.push({ kind: 'decision', id: record.id, detail: record.title });
+  }
+  return { hits, unresolved };
+}
+
+/** Every unresolved Affects token, one per record. */
+export function unresolvedAffects(records, ctx) {
+  const found = [];
+  for (const record of records) {
+    for (const token of affectsTokens(record.text)) {
+      const resolved = resolveToken(token, ctx);
+      if (resolved.kind === 'unresolved') found.push({ token: resolved.token, id: record.id });
+    }
+  }
+  found.sort((a, b) => cmp(a.token, b.token) || cmp(a.id, b.id));
+  return found;
+}
+
+/** Rules, skills, gates and lessons whose path list matches this file. */
+export function scopeHits(file, { rules = [], skills = [], gates = [], lessons = [], commands = {} }) {
+  const hits = [];
+  for (const rule of rules) {
+    if (rule.paths.some((glob) => matchGlob(glob, file))) hits.push({ kind: 'rule', id: rule.id, detail: rule.detail });
+  }
+  for (const skill of skills) {
+    if (skill.paths.some((glob) => matchGlob(glob, file))) hits.push({ kind: 'skill', id: skill.id, detail: skill.detail });
+  }
+  for (const gate of gates) {
+    const declared = commands[gate.id];
+    const byExt = gate.extensions ? gate.extensions.has(extension(file)) : false;
+    const byCommand = typeof declared === 'string' && declared.split(/\s+/).includes(file);
+    if (byExt || byCommand) hits.push({ kind: 'gate', id: gate.id, detail: gate.detail });
+  }
+  for (const lesson of lessons) {
+    if (lesson.paths.some((glob) => matchGlob(glob, file))) hits.push({ kind: 'lesson', id: lesson.id, detail: lesson.detail });
+  }
+  return hits;
+}
+
+export function sortHits(hits) {
+  const order = { decision: 0, rule: 1, skill: 2, gate: 3, lesson: 4 };
+  return [...hits].sort((a, b) => (order[a.kind] - order[b.kind]) || cmp(a.id, b.id));
+}
+
+/** Path globs from a `simt-scope` list, plus an applies entry that is itself a path. */
+export function scopePaths(text) {
+  const front = frontmatter(text);
+  if (!front) return [];
+  const paths = quotedList(front, 'simt-scope');
+  for (const entry of quotedList(front, 'simt-applies')) {
+    if (entry.includes('/') || entry.includes('*') || entry.startsWith('.')) paths.push(entry);
+  }
+  return paths;
+}
+
+/** `paths` inside a lesson's trigger, either inline or as a YAML list. */
+export function lessonPaths(text) {
+  const front = frontmatter(text);
+  if (!front) return [];
+  const inline = front.match(/paths:\s*\[([^\]]*)\]/);
+  if (inline) return [...inline[1].matchAll(/['"]([^'"]+)['"]/g)].map((match) => match[1]);
+  const paths = [];
+  let on = false;
+  for (const line of front.split('\n')) {
+    if (/paths:\s*$/.test(line)) {
+      on = true;
+      continue;
+    }
+    if (!on) continue;
+    const item = /^\s*-\s+['"]?([^'"]+?)['"]?\s*$/.exec(line);
+    if (!item) break;
+    paths.push(item[1]);
+  }
+  return paths;
+}
+
+export function matchGlob(glob, file) {
+  return expandBraces(glob).some((one) => globRegExp(one).test(file));
+}
+
+function commandOf(token, commands) {
+  if (!TOOL.test(token)) return commands.has(token) ? token : undefined;
+  const rest = token.replace(TOOL, '').trim();
+  if (rest === '') return null;
+  return commands.has(rest) ? rest : null;
+}
+
+function candidates(token, roots) {
+  const norm = token.replaceAll('\\', '/').replace(/^\.\//, '');
+  return [norm, ...roots.map((root) => `${root}/${norm}`)];
+}
+
+function hasGlob(token) {
+  return token.includes('*') || token.includes('?') || token.includes('{');
+}
+
+function expandBraces(glob) {
+  const match = /\{([^{}]+)\}/.exec(glob);
+  if (!match) return [glob];
+  return match[1].split(',').flatMap((alt) => expandBraces(glob.replace(match[0], alt)));
+}
+
+function globRegExp(glob) {
+  let re = '^';
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      i += 1;
+      if (glob[i + 1] === '/') {
+        re += '(?:.*/)?';
+        i += 1;
+      } else re += '.*';
+    } else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[\\^$+?.()|[\]{}]/g, '\\$&');
+  }
+  return new RegExp(`${re}$`);
+}
+
+function extension(file) {
+  const base = file.slice(file.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  return dot < 0 ? '' : base.slice(dot);
+}
+
+function frontmatter(text) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(String(text));
+  return match ? match[1] : '';
+}
+
+function quotedList(front, key) {
+  const match = new RegExp(`^${key}:\\s*\\[([^\\]]*)\\]`, 'm').exec(front);
+  if (!match) return [];
+  return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map((item) => item[1]);
+}
+
+function cmp(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}

package/src/index/impact.mjs

@@ -0,0 +1,186 @@
+// Who a change reaches (R23, ADR-096).
+//
+// Reverse dependents, the tests that import them, the owners a CODEOWNERS
+// line names, and another repository that references a contract this change
+// touches. The walk stops at a fixed count: an unbounded report is not an
+// answer a reader can use.
+
+import { isTestPath } from '../bench/mine.mjs';
+import { selectTests } from './gate.mjs';
+
+const IMPACT_LIMIT = 64;
+
+const CONTRACT_EXT = new Set(['json', 'yaml', 'yml']);
+
+/**
+ * Non-test files that import `file`, directly or through other files, and the
+ * tests that import that closure. Past the limit, the rest is reported as
+ * truncated rather than dropped silently.
+ *
+ * @param {string} file
+ * @param {{src: string, dst: string, kind?: string}[]} imports
+ * @param {number} [limit]
+ */
+export function dependents(file, imports, limit = IMPACT_LIMIT) {
+  const reverse = new Map();
+  for (const edge of imports) {
+    if (edge.kind && edge.kind !== 'import') continue;
+    const list = reverse.get(edge.dst);
+    if (list) list.push(edge.src);
+    else reverse.set(edge.dst, [edge.src]);
+  }
+  const importers = [];
+  const seen = new Set([file]);
+  const queue = [file];
+  let truncated = false;
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const next = reverse.get(current);
+    if (!next) continue;
+    for (const src of next) {
+      if (seen.has(src)) continue;
+      seen.add(src);
+      if (isTestPath(src)) continue;
+      if (importers.length >= limit) {
+        truncated = true;
+        continue;
+      }
+      importers.push(src);
+      queue.push(src);
+    }
+  }
+  importers.sort();
+  const tests = selectTests([file], imports).filter((path) => path !== file);
+  const shown = tests.length > limit ? tests.slice(0, limit) : tests;
+  if (tests.length > limit) truncated = true;
+  return { importers, tests: shown, truncated };
+}
+
+/** Files that export `name`. A private symbol is not an export. */
+export function filesExporting(name, symbols) {
+  const found = new Set();
+  for (const symbol of symbols) {
+    if (symbol.exported && symbol.name === name) found.add(symbol.path);
+  }
+  return [...found].sort();
+}
+
+/**
+ * The last matching CODEOWNERS pattern wins, which is the rule the file is
+ * read under. A pattern with no slash matches the file name in any directory.
+ *
+ * @param {string} text
+ * @param {string} file
+ * @returns {string[]}
+ */
+export function ownersOf(text, file) {
+  let owners = [];
+  for (const raw of String(text).split('\n')) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const parts = line.split(/\s+/);
+    const pattern = parts[0];
+    if (!pattern || !matchPattern(pattern, file)) continue;
+    owners = parts.slice(1).filter((part) => part.startsWith('@') || part.includes('@'));
+  }
+  return owners;
+}
+
+/** A path that is a contract by name: OpenAPI, or a JSON Schema file. */
+export function isContractPath(file) {
+  const base = file.slice(file.lastIndexOf('/') + 1).toLowerCase();
+  if (base === 'openapi.json' || base === 'openapi.yaml' || base === 'openapi.yml') return true;
+  if (base.endsWith('.schema.json')) return true;
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return false;
+  return CONTRACT_EXT.has(base.slice(dot + 1)) && base.includes('schema');
+}
+
+/**
+ * Contracts this change can reach: the file itself, a dependent, or a contract
+ * whose text names the file or the export.
+ *
+ * @param {{path: string, text: string}[]} contracts
+ * @param {{file: string, symbol: string, importers: string[]}} target
+ */
+export function relatedContracts(contracts, { file, symbol, importers }) {
+  const reached = new Set([file, ...importers]);
+  const related = [];
+  for (const contract of contracts) {
+    if (reached.has(contract.path) || names(contract.text, file, symbol)) related.push(contract.path);
+  }
+  related.sort();
+  return related;
+}
+
+/**
+ * Files in other repositories whose text contains a contract path. The path
+ * has to include a directory, so a bare filename is not a reference.
+ *
+ * @param {string[]} contracts repo-relative contract paths
+ * @param {string} repoName the repository that owns the contracts
+ * @param {{repo: string, path: string, text: string}[]} files
+ * @param {number} [limit]
+ */
+export function contractReferences(contracts, repoName, files, limit = IMPACT_LIMIT) {
+  const needles = [];
+  for (const contract of contracts) {
+    if (!contract.includes('/')) continue;
+    needles.push({ contract, needle: contract });
+    if (repoName) needles.push({ contract, needle: `${repoName}/${contract}` });
+  }
+  const found = [];
+  let truncated = false;
+  const seen = new Set();
+  for (const file of files) {
+    for (const item of needles) {
+      if (!file.text.includes(item.needle)) continue;
+      const key = `${file.repo}\0${file.path}\0${item.contract}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      if (found.length >= limit) {
+        truncated = true;
+        continue;
+      }
+      found.push({ repo: file.repo, path: file.path, contract: item.contract });
+    }
+  }
+  found.sort((a, b) => cmp(a.repo, b.repo) || cmp(a.path, b.path) || cmp(a.contract, b.contract));
+  return { references: found, truncated };
+}
+
+function names(text, file, symbol) {
+  if (file && text.includes(file)) return true;
+  if (!symbol) return false;
+  const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\b${escaped}\\b`).test(text);
+}
+
+function matchPattern(pattern, file) {
+  let pat = pattern.startsWith('/') ? pattern.slice(1) : pattern;
+  const directory = pat.endsWith('/');
+  if (directory) pat = pat.slice(0, -1);
+  if (pat === '') return false;
+  if (!pat.includes('/')) {
+    if (directory) return file === pat || file.startsWith(`${pat}/`) || file.split('/').includes(pat);
+    const base = file.slice(file.lastIndexOf('/') + 1);
+    return glob(pat, base);
+  }
+  if (directory) return file === pat || file.startsWith(`${pat}/`);
+  return glob(pat, file);
+}
+
+function glob(pattern, text) {
+  const body = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replaceAll('**', '\u0000')
+    .replaceAll('*', '[^/]*')
+    .replaceAll('\u0000', '.*');
+  return new RegExp(`^${body}$`).test(text);
+}
+
+function cmp(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}