flecto 3.0.1 → 3.0.2

package/src/policy.js

@@ -29,6 +29,7 @@ import { containsSecret } from './secrets.js';
  *   beforeLooksSecret?: true,
  *   afterLooksSecret?: true,
  *   afterMatches?: string,
+ *   afterAnyMatches?: string,
  *   numericJump?: { minMultiple: number },
  *   numericDelta?: { min: number },
  *   allOf?: PolicyMatchClause[],
@@ -48,6 +49,7 @@ import { containsSecret } from './secrets.js';
  *   beforeLooksSecret?: true,
  *   afterLooksSecret?: true,
  *   afterMatches?: string,
+ *   afterAnyMatches?: string,
  *   numericJump?: { minMultiple: number },
  *   numericDelta?: { min: number }
  * }} PolicyMatchClause
@@ -74,6 +76,7 @@ import { containsSecret } from './secrets.js';
  *   source?: 'watch' | 'ci' | 'diff',
  *   policies?: string[],
  *   plugins?: string[],
+ *   packRoots?: string[],
  *   severityRemap?: Record<string, PolicySeverity | 'off'>
  * }} PolicyEvalOptions
  */
@@ -85,12 +88,12 @@ const RULE_FIELDS = new Set([
   'id', 'severity', 'when', 'match', 'beforeEquals', 'afterEquals',
   'beforeIn', 'afterIn', 'beforeTruthy', 'afterTruthy', 'numericJump',
   'beforeLooksSecret', 'afterLooksSecret',
-  'afterMatches', 'numericDelta', 'allOf', 'anyOf', 'message', 'messageTemplate',
+  'afterMatches', 'afterAnyMatches', 'numericDelta', 'allOf', 'anyOf', 'message', 'messageTemplate',
 ]);
 const CLAUSE_FIELDS = new Set([
   'match', 'beforeEquals', 'afterEquals', 'beforeIn', 'afterIn',
   'beforeTruthy', 'afterTruthy', 'beforeLooksSecret', 'afterLooksSecret',
-  'afterMatches', 'numericJump', 'numericDelta',
+  'afterMatches', 'afterAnyMatches', 'numericJump', 'numericDelta',
 ]);
 const MATCH_FIELDS = new Set(['path', 'pathFlags', 'pathEquals', 'pathPrefix']);
 // Community distribution convention: an npm package named flecto-pack-<id>
@@ -166,17 +169,34 @@ function validatePack(pack, path) {
 }
 
 /**
- * @param {string} cwd
+ * Every directory whose `policies/` is searched for a local pack, in order.
+ * The first entry is the primary cwd; later entries are fallbacks (the policy
+ * fixture harness runs from the fixture directory but packs are installed into
+ * the invoking project — see #114).
+ * @param {string | string[]} cwd
+ * @returns {string[]}
+ */
+function packRoots(cwd) {
+  const roots = (Array.isArray(cwd) ? cwd : [cwd])
+    .filter((root) => typeof root === 'string' && root)
+    .map((root) => resolve(root));
+  // Distinct roots only: a fixture run from the project root would otherwise
+  // search the same policies/ directory twice and report it twice on failure.
+  return [...new Set(roots)];
+}
+
+/**
+ * @param {string | string[]} cwd
  * @param {string} packId
  * @returns {string | null}
  */
 function resolvePackPath(cwd, packId) {
-  const localJson = resolve(cwd, 'policies', `${packId}.json`);
-  const localYaml = resolve(cwd, 'policies', `${packId}.yaml`);
-  const localYml = resolve(cwd, 'policies', `${packId}.yml`);
-  if (existsSync(localJson)) return localJson;
-  if (existsSync(localYaml)) return localYaml;
-  if (existsSync(localYml)) return localYml;
+  for (const root of packRoots(cwd)) {
+    for (const ext of ['.json', '.yaml', '.yml']) {
+      const localPath = resolve(root, 'policies', `${packId}${ext}`);
+      if (existsSync(localPath)) return localPath;
+    }
+  }
 
   const builtinJson = join(PACKS_DIR, `${packId}.json`);
   if (existsSync(builtinJson)) return builtinJson;
@@ -240,6 +260,7 @@ function validateRule(candidate, location, isClause = false) {
   validateTruthyPredicate(rule.beforeLooksSecret, 'beforeLooksSecret', location);
   validateTruthyPredicate(rule.afterLooksSecret, 'afterLooksSecret', location);
   validateRegexPredicate(rule.afterMatches, 'afterMatches', location);
+  validateRegexPredicate(rule.afterAnyMatches, 'afterAnyMatches', location);
   validateNumericPredicate(rule.numericJump, 'numericJump', 'minMultiple', location, true);
   validateNumericPredicate(rule.numericDelta, 'numericDelta', 'min', location, false);
   for (const name of ['message', 'messageTemplate']) {
@@ -359,13 +380,16 @@ function validateComposition(clauses, name, location) {
 const packCache = new Map();
 
 /**
- * @param {string} cwd
+ * @param {string[]} roots  already-resolved search roots, in order
  * @param {string} path
  * @param {number} mtimeMs
  * @returns {string}
  */
-function packCacheKey(cwd, path, mtimeMs) {
-  return `${resolve(cwd)}\u0000${path}\u0000${mtimeMs}`;
+function packCacheKey(roots, path, mtimeMs) {
+  // Roots are NUL-joined for the same reason the other fields are
+  // NUL-separated: two different root lists must never concatenate into the
+  // same key.
+  return `${roots.join('\u0000')}\u0000${path}\u0000${mtimeMs}`;
 }
 
 /**
@@ -385,11 +409,21 @@ export function loadPack(packId, cwd = process.cwd()) {
   if (!id) throw new Error('Policy pack id is required');
   const path = resolvePackPath(cwd, id);
   if (!path) {
-    throw new Error(`Unknown policy pack "${id}". Add policies/${id}.json or use a built-in pack.`);
+    // Name the directories actually searched. The old message always said
+    // "Add policies/<id>.json", which was actively misleading when the pack
+    // existed but in a directory this lookup never consulted (#114).
+    const searched = packRoots(cwd)
+      .map((root) => join(root, 'policies'))
+      .concat(PACKS_DIR)
+      .join(', ');
+    throw new Error(
+      `Unknown policy pack "${id}". Searched: ${searched}.`
+      + ` Add policies/${id}.json in one of these, or use a built-in pack.`,
+    );
   }
 
   const mtimeMs = statSync(path).mtimeMs;
-  const cacheKey = packCacheKey(cwd, path, mtimeMs);
+  const cacheKey = packCacheKey(packRoots(cwd), path, mtimeMs);
   const cached = packCache.get(cacheKey);
   if (cached) return cached;
 
@@ -700,15 +734,16 @@ export function addPolicyPackFromPackage(name, options = {}) {
 }
 
 /**
- * Compile each rule's `match.path` and `afterMatches` regular expressions
- * once, at pack-load time, storing them as non-enumerable properties on the
- * loaded rule/clause objects. matchClause() runs per change event — for a
- * rule with a path match, once per event per rule — so compiling here instead
- * of inside that loop turns a `new RegExp(...)` call into a property read.
+ * Compile each rule's `match.path`, `afterMatches`, and `afterAnyMatches`
+ * regular expressions once, at pack-load time, storing them as non-enumerable
+ * properties on the loaded rule/clause objects. matchClause() runs per change
+ * event — for a rule with a path match, once per event per rule — so compiling
+ * here instead of inside that loop turns a `new RegExp(...)` call into a
+ * property read.
  *
- * validatePack() has already proven, by this point, that every `match.path`
- * and `afterMatches` string constructs a valid RegExp, so construction here
- * cannot throw a new error the caller hasn't already seen.
+ * validatePack() has already proven, by this point, that every `match.path`,
+ * `afterMatches`, and `afterAnyMatches` string constructs a valid RegExp, so
+ * construction here cannot throw a new error the caller hasn't already seen.
  * @param {PolicyPack} pack
  */
 function compilePackRegexes(pack) {
@@ -733,6 +768,12 @@ function compileClauseRegexes(clause) {
       enumerable: false,
     });
   }
+  if (clause.afterAnyMatches !== undefined) {
+    Object.defineProperty(clause, '_afterAnyMatchesRegex', {
+      value: new RegExp(clause.afterAnyMatches),
+      enumerable: false,
+    });
+  }
 }
 
 /**
@@ -754,6 +795,29 @@ function afterMatchesRegexFor(clause) {
   return clause._afterMatchesRegex ?? new RegExp(clause.afterMatches);
 }
 
+/**
+ * @param {{ afterAnyMatches?: string, _afterAnyMatchesRegex?: RegExp }} clause
+ * @returns {RegExp}
+ */
+function afterAnyMatchesRegexFor(clause) {
+  return clause._afterAnyMatchesRegex ?? new RegExp(clause.afterAnyMatches);
+}
+
+/**
+ * True when `value` is an array carrying at least one string element that
+ * matches. Deliberately a flat scan: it does not descend into nested arrays or
+ * objects, because a rule's text should say what it matches without the reader
+ * having to reason about how deep the walk goes. Non-array values never match,
+ * which is what keeps `afterMatches` and this predicate from overlapping.
+ * @param {unknown} value
+ * @param {RegExp} regex
+ * @returns {boolean}
+ */
+function anyElementMatches(value, regex) {
+  return Array.isArray(value)
+    && value.some((element) => typeof element === 'string' && regex.test(element));
+}
+
 /**
  * @param {PolicyRule} rule
  * @param {import('./differ.js').ChangeEvent} change
@@ -791,6 +855,10 @@ function matchClause(clause, change) {
   if (clause.beforeLooksSecret && !containsSecret(change.before)) return false;
   if (clause.afterLooksSecret && !containsSecret(change.after)) return false;
   if (clause.afterMatches && (typeof change.after !== 'string' || !afterMatchesRegexFor(clause).test(change.after))) return false;
+  // The list counterpart, for the change that turns a scalar into a list in
+  // one edit -- reported as a single `changed` event whose `after` is an array,
+  // which no scalar predicate can see into.
+  if (clause.afterAnyMatches && !anyElementMatches(change.after, afterAnyMatchesRegexFor(clause))) return false;
 
   if (clause.numericJump) {
     const before = change.before;
@@ -1020,10 +1088,15 @@ export async function evaluatePolicies(changes, options = {}) {
   const packIds = options.policies?.length ? options.policies : ['default'];
   const plugins = options.plugins ?? [];
   const severityRemap = options.severityRemap ?? {};
+  // Packs may resolve from additional roots (the fixture harness adds the
+  // invoking project, #114). Plugin resolution deliberately stays anchored to
+  // the single `cwd` below: widening where executable code loads from is not
+  // the same decision as widening where declarative packs load from.
+  const packSearchRoots = options.packRoots?.length ? [cwd, ...options.packRoots] : cwd;
 
   /** @type {PolicyFinding[]} */
   const findings = [];
-  const packs = packIds.map((packId) => loadPack(packId, cwd));
+  const packs = packIds.map((packId) => loadPack(packId, packSearchRoots));
   const knownRuleIds = new Set(packs.flatMap((pack) => pack.rules.map((rule) => String(rule.id))));
   for (const ruleId of Object.keys(severityRemap)) {
     if (!knownRuleIds.has(ruleId)) {

package/src/pr-comment.js

@@ -1,6 +1,8 @@
 import { readFileSync } from 'fs';
 import { isAbsolute, relative } from 'path';
 
+import { PR_PROVIDERS, selectPrProvider } from './pr-providers.js';
+
 /**
  * Hidden marker embedded in every rendered body. Flecto finds its own comment by
  * searching for this string, so repeated runs update one sticky comment instead
@@ -8,21 +10,23 @@ import { isAbsolute, relative } from 'path';
  */
 export const PR_COMMENT_MARKER = '<!-- flecto:pr-comment -->';
 
-const DEFAULT_API_URL = 'https://api.github.com';
 const DEFAULT_TIMEOUT_MS = 10_000;
 /** GitHub rejects comment bodies longer than 65536 characters. */
 const MAX_BODY_CHARS = 60_000;
 const MAX_INLINE_CHANGES = 10;
 const MAX_VALUE_CHARS = 120;
 const MAX_COMMENT_PAGES = 10;
-const COMMENTS_PER_PAGE = 100;
 const SEVERITY_ORDER = ['error', 'warn', 'info'];
 const SEVERITY_HEADINGS = { error: 'Errors', warn: 'Warnings', info: 'Notices' };
 const SEVERITY_NOUNS = { error: 'error', warn: 'warning', info: 'notice' };
 
 /**
  * @typedef {{ file: string, envelope: import('./envelope.js').FlectoEnvelope, policies?: import('./policy.js').PolicyFinding[] }} CiResult
- * @typedef {{ repo: string, prNumber: number, token: string, apiUrl: string }} PrCommentContext
+ * @typedef {{ provider?: string, prNumber: number, token: string, apiUrl: string,
+ *   repo?: string, projectId?: string, webUrl?: string, workspace?: string, repoSlug?: string
+ * }} PrCommentContext The fields a delivery adapter resolved; which ones are
+ *   present depends on the provider. A context built by hand carries no
+ *   `provider` and is treated as GitHub.
  */
 
 /**
@@ -233,70 +237,30 @@ export function renderPrComment(results, options = {}) {
 }
 
 /**
- * @param {Record<string, string | undefined>} env
- * @param {(path: string) => string} readEventFile
- * @returns {number | null}
- */
-function resolvePrNumber(env, readEventFile) {
-  const fromRef = /^refs\/pull\/(\d+)\/(?:merge|head)$/u.exec(env.GITHUB_REF ?? '');
-  if (fromRef) return Number(fromRef[1]);
-
-  const eventPath = env.GITHUB_EVENT_PATH;
-  if (!eventPath) return null;
-
-  let event;
-  try {
-    event = JSON.parse(readEventFile(eventPath));
-  } catch {
-    return null;
-  }
-
-  const candidates = [
-    event?.pull_request?.number,
-    // issue_comment events on a PR carry the PR number under `issue`, but a
-    // plain issue must not be mistaken for one.
-    event?.issue?.pull_request ? event?.issue?.number : undefined,
-    event?.number,
-  ];
-  for (const candidate of candidates) {
-    const value = Number(candidate);
-    if (Number.isInteger(value) && value > 0) return value;
-  }
-  return null;
-}
-
-/**
- * Resolve the GitHub API context needed to post a pull request comment.
+ * Resolve the API context needed to post a merge request comment.
  *
- * Only `GITHUB_TOKEN` is honored — `GH_TOKEN` is deliberately ignored because
- * `gh auth login` exports it on developer machines, where posting would be a
- * surprise.
+ * The provider is detected from CI environment variables, or forced with
+ * `provider`. GitHub is the fallback, so an unrecognized environment reports
+ * the message it always did rather than a new one about detection.
  * @param {Record<string, string | undefined>} [env]
- * @param {{ readEventFile?: (path: string) => string }} [options]
+ * @param {{ readEventFile?: (path: string) => string, provider?: string }} [options]
  * @returns {{ ok: true, context: PrCommentContext } | { ok: false, reason: string }}
  */
 export function resolvePrCommentContext(env = process.env, options = {}) {
   const readEventFile = options.readEventFile ?? ((path) => readFileSync(path, 'utf8'));
-  const token = String(env.GITHUB_TOKEN ?? '').trim();
-  if (!token) {
-    return { ok: false, reason: 'GITHUB_TOKEN is not set' };
-  }
-
-  const repo = String(env.GITHUB_REPOSITORY ?? '').trim();
-  if (!/^[^/\s]+\/[^/\s]+$/u.test(repo)) {
-    return { ok: false, reason: 'GITHUB_REPOSITORY is not set to "owner/repo"' };
-  }
-
-  const prNumber = resolvePrNumber(env, readEventFile);
-  if (!prNumber) {
-    return {
-      ok: false,
-      reason: 'no pull request number in GITHUB_REF or GITHUB_EVENT_PATH (not a pull request run)',
-    };
-  }
+  const selected = selectPrProvider(env, options.provider);
+  if (!selected.ok) return selected;
+  return selected.provider.resolve(env, { readEventFile });
+}
 
-  const apiUrl = String(env.GITHUB_API_URL || DEFAULT_API_URL).replace(/\/+$/u, '');
-  return { ok: true, context: { repo, prNumber, token, apiUrl } };
+/**
+ * The adapter a resolved context belongs to. Contexts built by hand — as tests
+ * and embedders do — carry no provider and are GitHub, which is what they were
+ * before there was a choice.
+ * @param {{ provider?: string }} context
+ */
+function providerFor(context) {
+  return PR_PROVIDERS.find((p) => p.id === context?.provider) ?? PR_PROVIDERS[0];
 }
 
 /**
@@ -333,10 +297,10 @@ async function errorDetail(response, token) {
 }
 
 /**
- * @param {{ fetchImpl: typeof fetch, url: string, method: string, token: string, body?: unknown, timeoutMs: number }} request
+ * @param {{ fetchImpl: typeof fetch, provider: object, url: string, method: string, token: string, body?: unknown, timeoutMs: number }} request
  * @returns {Promise<Response>}
  */
-async function githubRequest({ fetchImpl, url, method, token, body, timeoutMs }) {
+async function apiRequest({ fetchImpl, provider, url, method, token, body, timeoutMs }) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   let response;
@@ -344,11 +308,10 @@ async function githubRequest({ fetchImpl, url, method, token, body, timeoutMs })
     response = await fetchImpl(url, {
       method,
       headers: {
-        Accept: 'application/vnd.github+json',
-        Authorization: `Bearer ${token}`,
+        Accept: provider.accept ?? 'application/json',
         'Content-Type': 'application/json',
         'User-Agent': 'flecto',
-        'X-GitHub-Api-Version': '2022-11-28',
+        ...provider.authHeaders(token),
       },
       body: body === undefined ? undefined : JSON.stringify(body),
       signal: controller.signal,
@@ -357,14 +320,14 @@ async function githubRequest({ fetchImpl, url, method, token, body, timeoutMs })
     const reason = err?.name === 'AbortError'
       ? `timed out after ${timeoutMs}ms`
       : redact(err?.message ?? String(err), token);
-    throw new Error(`GitHub API ${method} failed: ${reason}`);
+    throw new Error(`${provider.label} API ${method} failed: ${reason}`);
   } finally {
     clearTimeout(timer);
   }
 
   if (!response.ok) {
     throw new Error(
-      `GitHub API ${method} returned HTTP ${response.status}${await errorDetail(response, token)}`,
+      `${provider.label} API ${method} returned HTTP ${response.status}${await errorDetail(response, token)}`,
     );
   }
   return response;
@@ -374,20 +337,19 @@ async function githubRequest({ fetchImpl, url, method, token, body, timeoutMs })
  * Find the sticky Flecto comment on a pull request, if one exists.
  * @param {PrCommentContext} context
  * @param {{ fetchImpl: typeof fetch, marker: string, timeoutMs: number }} options
- * @returns {Promise<{ id: number, body?: string, html_url?: string } | null>}
+ * @returns {Promise<{ id: string | number, body?: string, url?: string } | null>}
  */
 async function findStickyComment(context, { fetchImpl, marker, timeoutMs }) {
+  const provider = providerFor(context);
   for (let page = 1; page <= MAX_COMMENT_PAGES; page += 1) {
-    const url = `${context.apiUrl}/repos/${context.repo}/issues/${context.prNumber}`
-      + `/comments?per_page=${COMMENTS_PER_PAGE}&page=${page}`;
-    const response = await githubRequest({
-      fetchImpl, url, method: 'GET', token: context.token, timeoutMs,
+    const response = await apiRequest({
+      fetchImpl, provider, url: provider.listUrl(context, page), method: 'GET', token: context.token, timeoutMs,
     });
-    const comments = await response.json();
-    if (!Array.isArray(comments) || comments.length === 0) return null;
+    const comments = provider.readList(await response.json());
+    if (comments.length === 0) return null;
     const match = comments.find((c) => typeof c?.body === 'string' && c.body.includes(marker));
     if (match) return match;
-    if (comments.length < COMMENTS_PER_PAGE) return null;
+    if (comments.length < provider.perPage) return null;
   }
   return null;
 }
@@ -404,6 +366,7 @@ export async function upsertPrComment(body, context, options = {}) {
   const fetchImpl = options.fetchImpl ?? globalThis.fetch;
   const marker = options.marker ?? PR_COMMENT_MARKER;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const provider = providerFor(context);
   if (typeof fetchImpl !== 'function') {
     throw new Error('Global fetch unavailable. Use Node.js >= 20.19.0.');
   }
@@ -411,39 +374,41 @@ export async function upsertPrComment(body, context, options = {}) {
   const existing = await findStickyComment(context, { fetchImpl, marker, timeoutMs });
 
   if (!existing) {
-    const response = await githubRequest({
+    const response = await apiRequest({
       fetchImpl,
-      url: `${context.apiUrl}/repos/${context.repo}/issues/${context.prNumber}/comments`,
+      provider,
+      url: provider.createUrl(context),
       method: 'POST',
       token: context.token,
-      body: { body },
+      body: provider.payload(body),
       timeoutMs,
     });
     const created = await response.json().catch(() => ({}));
-    return { action: 'created', url: created?.html_url };
+    return { action: 'created', url: provider.readOne(created, context).url };
   }
 
   // Rendering is deterministic, so an identical body means nothing moved since
   // the last run — skip the write and the "edited" noise it creates.
   if (existing.body === body) {
-    return { action: 'unchanged', url: existing.html_url };
+    return { action: 'unchanged', url: existing.url };
   }
 
-  const response = await githubRequest({
+  const response = await apiRequest({
     fetchImpl,
-    url: `${context.apiUrl}/repos/${context.repo}/issues/comments/${existing.id}`,
-    method: 'PATCH',
+    provider,
+    url: provider.updateUrl(context, existing.id),
+    method: provider.updateMethod,
     token: context.token,
-    body: { body },
+    body: provider.payload(body),
     timeoutMs,
   });
   const updated = await response.json().catch(() => ({}));
-  return { action: 'updated', url: updated?.html_url ?? existing.html_url };
+  return { action: 'updated', url: provider.readOne(updated, context).url ?? existing.url };
 }
 
 /**
  * Post the sticky comment when — and only when — posting was explicitly enabled
- * and a complete GitHub pull request context is present.
+ * and a complete merge request context is present.
  *
  * Never throws and never reports the token: a delivery problem must not change
  * the CI exit code, which belongs to the diff and policy result alone.
@@ -454,7 +419,8 @@ export async function upsertPrComment(body, context, options = {}) {
  *   fetchImpl?: typeof fetch,
  *   marker?: string,
  *   timeoutMs?: number,
- *   readEventFile?: (path: string) => string
+ *   readEventFile?: (path: string) => string,
+ *   provider?: string
  * }} [options]
  * @returns {Promise<{ posted: boolean, action?: 'created' | 'updated' | 'unchanged', url?: string, reason?: string }>}
  */