rule-loader.mjs

/**
 * Rule Loader — issue #336 glob-scoped rules + #694 rule-activation foundation
 * + #795 `paths:` alias.
 *
 * Reads `.claude/rules/*.md` files, parses optional YAML frontmatter, and
 * returns the subset of rules applicable to a given set of file paths and
 * activation axes.
 *
 * Rules with no `globs:`/`paths:` frontmatter are always-on (loaded for every
 * wave). Rules with `globs:` (or the `paths:` alias — issue #795) load only
 * when at least one `scopePath` matches at least one glob pattern.
 *
 * `paths:` is a same-shape alias for `globs:` (issue #795) — some repos use a
 * `paths:` frontmatter convention instead of `globs:` (e.g. projects-baseline:
 * 26 rule files, all `paths:`, 0 `globs:`). Before #795 these repos'
 * path-scoped rules were silently misclassified as always-on, inflating the
 * `instruction-budget-guard.mjs` (#687) always-on count with a false positive.
 * `paths:` supports the identical inline-array and block-list forms as
 * `globs:`. Precedence when BOTH keys are present on the same rule: `globs:`
 * wins (silently — no merge, no warning) and `paths:` is ignored entirely.
 *
 * A rule file MAY carry a leading single-line provenance header before its
 * frontmatter block — the vendoring pipeline (`scripts/rules-sync.mjs`)
 * requires a first-line `<!-- source: session-orchestrator plugin
 * (canonical: ...) -->` comment on every vendored rule. The frontmatter
 * parser tolerates any leading run of blank lines and/or single-line HTML
 * comments before the opening `---`, so a vendored rule keeps its `globs:`
 * scoping and scalar meta instead of silently falling back to always-on.
 * Only single-line comments are tolerated (no multi-line comment blocks);
 * files with no header, or starting directly with `---`, parse exactly as
 * before.
 *
 * Beyond the `globs:` key (issue #336), the frontmatter parser also captures
 * these scalar activation keys (issue #694), surfaced on each RuleEntry:
 *   - `description`   (string)
 *   - `mode`          (string)   — see mode-gating below
 *   - `host-class`    (string)   — see host-class-gating below; surfaced as `hostClass`
 *   - `alwaysApply`   (boolean)  — DISTINCT from the `alwaysOn` "no globs" flag
 *   - `expires-at`    (string)   — ISO date; see expiry gating below; surfaced as `expiresAt`
 *   - `learning-key`  (string)   — surfaced as `learningKey`
 *   - `auto-generated`(boolean)  — surfaced as `autoGenerated`
 *   - `confidence`    (number)
 * Unknown keys are still ignored without error, and malformed frontmatter still
 * falls back to always-on (a rule is never silently dropped).
 *
 * Deterministic gating (issue #694) runs after a successful frontmatter parse
 * and applies to BOTH always-on and glob-matched candidate rules — a rule must
 * pass ALL active gates to be included:
 *   - Expiry: a rule with a parseable `expires-at` strictly before `now` is
 *     EXCLUDED (with a mandatory stderr WARN). A malformed `expires-at` never
 *     excludes (fail-open).
 *   - Mode-gating: when the `mode` param is non-null and the rule declares a
 *     `mode` that differs, the rule is EXCLUDED. A null `mode` param disables
 *     mode filtering; a rule without a `mode` key always passes.
 *   - Host-class-gating: identical logic against the `hostClass` param vs the
 *     rule's `host-class` value.
 *
 * Parse errors fall back to always-on — a rule is never silently dropped.
 *
 * @module rule-loader
 */

import { readFileSync, readdirSync } from 'node:fs';
import { join, extname } from 'node:path';
import { createRequire } from 'node:module';

// ---------------------------------------------------------------------------
// Picomatch integration (available in the project's node_modules).
// We resolve it dynamically so the module stays loadable in environments where
// picomatch is absent — the inline fallback glob-to-RegExp takes over then.
// ---------------------------------------------------------------------------

let _picomatch = null;

function getPicomatch() {
  if (_picomatch !== null) return _picomatch;
  try {
    const require = createRequire(import.meta.url);
    _picomatch = require('picomatch');
  } catch {
    // picomatch not available — will use inline fallback
    _picomatch = false;
  }
  return _picomatch;
}

/**
 * Minimal glob-to-RegExp fallback used only when picomatch is absent.
 * Handles `**`, `*`, and literal character matching.
 *
 * @param {string} pattern
 * @returns {RegExp}
 */
function globToRegExp(pattern) {
  // Normalize Windows separators
  const p = pattern.replace(/\\/g, '/');
  let re = '';
  let i = 0;
  while (i < p.length) {
    const c = p[i];
    if (c === '*' && p[i + 1] === '*') {
      // `**` — match zero or more path segments
      re += '.*';
      i += 2;
      // Consume optional trailing separator
      if (p[i] === '/') i++;
    } else if (c === '*') {
      // `*` — match any characters except separator
      re += '[^/]*';
      i++;
    } else if (c === '?') {
      re += '[^/]';
      i++;
    } else if (c === '.') {
      re += '\\.';
      i++;
    } else {
      // Escape regex-special characters
      re += c.replace(/[$()+[\]^{|}]/g, '\\$&');
      i++;
    }
  }
  return new RegExp(`^${re}$`);
}

/**
 * Returns true when `filePath` matches `globPattern` using picomatch (or the
 * inline fallback when picomatch is absent).
 *
 * @param {string} filePath - path relative to repo root, forward-slash separated
 * @param {string} globPattern
 * @returns {boolean}
 */
function matchGlob(filePath, globPattern) {
  const pm = getPicomatch();
  if (pm) {
    return pm.isMatch(filePath, globPattern, { dot: true });
  }
  return globToRegExp(globPattern).test(filePath);
}

// ---------------------------------------------------------------------------
// Minimal YAML frontmatter parser (matches state-md.mjs style)
// ---------------------------------------------------------------------------

const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;

// A single header line is either blank or a complete single-line HTML
// comment (`<!-- ... -->` on one line). Multi-line comment blocks are
// deliberately NOT supported — the vendoring convention is a single first
// line, and tolerating a few stacked comment lines (each matching this RE)
// is sufficient.
const HEADER_LINE_RE = /^[ \t]*(?:<!--.*-->)?[ \t]*$/;

/**
 * Skips a leading run of blank lines and/or single-line HTML comments
 * (`<!-- ... -->`) at the very start of a rule file's contents, so the
 * frontmatter opener (`---`) can be found even when the vendoring pipeline's
 * mandatory provenance header precedes it. Stops at the first line that is
 * neither blank nor a complete single-line comment.
 *
 * @param {string} contents - raw file contents
 * @returns {string} contents starting at the first non-header line (empty
 *   string when the entire content is header lines)
 */
function stripLeadingProvenanceHeader(contents) {
  const lines = contents.split(/\r?\n/);
  let idx = 0;
  while (idx < lines.length && HEADER_LINE_RE.test(lines[idx])) {
    idx++;
  }
  return lines.slice(idx).join('\n');
}

// Scalar activation keys captured (issue #694 + #692). The `globs` key keeps
// its dedicated sequence/flow handling and is NOT routed through this table.
const SCALAR_META_KEYS = new Set([
  'description',
  'mode',
  'host-class',
  'alwaysApply',
  'expires-at',
  'learning-key',
  'auto-generated',
  'confidence',
  'tier',
]);

/**
 * Parses the YAML frontmatter block for the `globs:` field (issue #336),
 * its `paths:` alias (issue #795), and the scalar activation keys (issue #694).
 *
 * Returns:
 *   - `{ globs: string[] | null, meta: object }` on success
 *   - throws `Error` on malformed frontmatter so the caller can fall back
 *
 * `globs` is `null` when no frontmatter, and neither `globs:` nor `paths:` is
 * present (always-on). `paths:` is parsed with the identical inline-array and
 * block-list forms as `globs:`; when BOTH keys are present on the same rule,
 * `globs:` wins silently and `paths:` is discarded (no merge, no warning —
 * see module doc). The returned shape is unchanged either way — callers never
 * see which key produced the value. `meta` carries only the recognised scalar
 * keys that were present, with type coercion applied:
 *   - `alwaysApply`, `auto-generated` → boolean ('true'/'false')
 *   - `confidence` → number (undefined when NaN)
 *   - all other recognised keys → quote-stripped strings
 * Unknown keys are ignored without error.
 *
 * A leading run of blank lines and/or single-line HTML comments (e.g. the
 * vendoring pipeline's provenance header) is tolerated before the opening
 * `---` — see `stripLeadingProvenanceHeader`. Files with no such header parse
 * identically to before this tolerance was added.
 *
 * @param {string} contents - raw file contents
 * @returns {{ globs: string[] | null, meta: Record<string, unknown> }}
 */
export function parseGlobsFrontmatter(contents) {
  const match = FRONTMATTER_RE.exec(stripLeadingProvenanceHeader(contents));
  if (!match) return { globs: null, meta: {} };

  const fmText = match[1];
  const lines = fmText.split(/\r?\n/);

  let globsValue = null;
  let pathsValue = null;
  // Which sequence-value key ('globs' | 'paths') is currently accumulating
  // block-style `  - value` lines, or null when not inside either block.
  let activeSeqKey = null;
  /** @type {Record<string, unknown>} */
  const meta = {};

  for (const line of lines) {
    const rstripped = line.replace(/\s+$/, '');

    // Skip blank lines and comments
    if (rstripped === '' || /^\s*#/.test(rstripped)) {
      // If inside a `globs:`/`paths:` block, a blank line ends the sequence
      // only if the next non-blank line is at col 0 (a new key). We just keep
      // activeSeqKey set until we hit a non-indented non-blank line.
      continue;
    }

    if (activeSeqKey) {
      // Inside a `globs:`/`paths:` block — expect `  - value` indented lines
      const seqMatch = rstripped.match(/^(\s+)-\s+(.*)/);
      if (seqMatch) {
        const raw = seqMatch[2].trim().replace(/^["']|["']$/g, '');
        if (activeSeqKey === 'globs') {
          if (!Array.isArray(globsValue)) globsValue = [];
          globsValue.push(raw);
        } else {
          if (!Array.isArray(pathsValue)) pathsValue = [];
          pathsValue.push(raw);
        }
        continue;
      }
      // Non-indented line — end of the sequence block
      activeSeqKey = null;
    }

    // Top-level key detection
    if (/^\s/.test(rstripped)) {
      // Indented but not in a known block — skip (another block's continuation)
      continue;
    }

    const colonIdx = rstripped.indexOf(':');
    if (colonIdx === -1) {
      throw new Error(`Malformed frontmatter line: ${JSON.stringify(rstripped)}`);
    }

    const key = rstripped.slice(0, colonIdx).trim();
    const valuePart = rstripped.slice(colonIdx + 1).trim();

    if (key === 'globs' || key === 'paths') {
      let parsedValue;
      if (valuePart === '') {
        // Block-style list follows
        activeSeqKey = key;
        parsedValue = [];
      } else if (valuePart.startsWith('[') && valuePart.endsWith(']')) {
        // Flow-style: globs: ["src/**", "lib/**"] (or paths: [...])
        const inner = valuePart.slice(1, -1).trim();
        parsedValue = inner === ''
          ? []
          : inner.split(',').map((s) => s.trim().replace(/^["']|["']$/g, ''));
      } else {
        // Single inline value (unusual but handle gracefully)
        parsedValue = [valuePart.replace(/^["']|["']$/g, '')];
      }
      if (key === 'globs') globsValue = parsedValue;
      else pathsValue = parsedValue;
    } else if (SCALAR_META_KEYS.has(key)) {
      // Scalar activation key (issue #694). Strip surrounding quotes, then
      // apply per-key coercion. Empty values are skipped (key not present).
      const stripped = valuePart.replace(/^["']|["']$/g, '');
      if (stripped === '') continue;
      if (key === 'alwaysApply' || key === 'auto-generated') {
        if (stripped === 'true') meta[key] = true;
        else if (stripped === 'false') meta[key] = false;
        // Any other value: leave undefined (not a recognised boolean)
      } else if (key === 'confidence') {
        const n = Number(stripped);
        if (!Number.isNaN(n)) meta[key] = n;
      } else {
        meta[key] = stripped;
      }
    }
    // Ignore all other keys
  }

  // Precedence (issue #795): `globs:` wins silently when both keys are present.
  const globs = globsValue !== null ? globsValue : pathsValue;

  return { globs, meta };
}

/**
 * Maps the raw (hyphenated) frontmatter meta keys onto the camelCase RuleEntry
 * field names, including only keys that were actually present.
 *
 * @param {Record<string, unknown>} meta
 * @returns {Record<string, unknown>}
 */
function metaToEntryFields(meta) {
  /** @type {Record<string, unknown>} */
  const out = {};
  if (Object.prototype.hasOwnProperty.call(meta, 'description')) out.description = meta.description;
  if (Object.prototype.hasOwnProperty.call(meta, 'mode')) out.mode = meta.mode;
  if (Object.prototype.hasOwnProperty.call(meta, 'host-class')) out.hostClass = meta['host-class'];
  if (Object.prototype.hasOwnProperty.call(meta, 'alwaysApply')) out.alwaysApply = meta.alwaysApply;
  if (Object.prototype.hasOwnProperty.call(meta, 'expires-at')) out.expiresAt = meta['expires-at'];
  if (Object.prototype.hasOwnProperty.call(meta, 'learning-key')) out.learningKey = meta['learning-key'];
  if (Object.prototype.hasOwnProperty.call(meta, 'auto-generated')) out.autoGenerated = meta['auto-generated'];
  if (Object.prototype.hasOwnProperty.call(meta, 'confidence')) out.confidence = meta.confidence;
  if (Object.prototype.hasOwnProperty.call(meta, 'tier')) out.tier = meta.tier;
  return out;
}

/**
 * Deterministic gating check (issue #694 + #692). Returns `{ excluded: boolean,
 * reason?: string }`. Applied to BOTH always-on and glob-matched rules.
 *
 * @param {Record<string, unknown>} meta - raw parsed meta (hyphenated keys)
 * @param {string} filePath - absolute path (for WARN messages)
 * @param {string|null} mode
 * @param {string|null} hostClass
 * @param {number} now - epoch ms
 * @param {string|null} [context] - 'wave' | 'coordinator' | null (null = no tier gating)
 * @returns {{ excluded: boolean }}
 */
function applyGates(meta, filePath, mode, hostClass, now, context = null) {
  // Expiry gate — fail-open on a malformed `expires-at`.
  if (Object.prototype.hasOwnProperty.call(meta, 'expires-at')) {
    const rawExpiry = meta['expires-at'];
    const ts = Date.parse(String(rawExpiry));
    if (Number.isNaN(ts)) {
      process.stderr.write(
        `[rule-loader] Rule ${filePath} has unparseable expires-at ${JSON.stringify(rawExpiry)} — ignoring expiry\n`,
      );
    } else if (ts < now) {
      process.stderr.write(
        `[rule-loader] Rule ${filePath} expired at ${rawExpiry} — excluded\n`,
      );
      return { excluded: true };
    }
  }

  // Mode gate — only active when a non-null `mode` param is supplied AND the
  // rule declares a differing `mode`.
  if (mode !== null && Object.prototype.hasOwnProperty.call(meta, 'mode') && meta.mode !== mode) {
    return { excluded: true };
  }

  // Host-class gate — symmetric to the mode gate.
  if (
    hostClass !== null &&
    Object.prototype.hasOwnProperty.call(meta, 'host-class') &&
    meta['host-class'] !== hostClass
  ) {
    return { excluded: true };
  }

  // Tier gate (issue #692) — only active when context is non-null.
  // BACKWARD-COMPAT: context === null → no tier gating whatsoever.
  if (context !== null && Object.prototype.hasOwnProperty.call(meta, 'tier')) {
    const tier = meta.tier;
    if (context === 'wave' && tier === 'coordinator-only') {
      return { excluded: true };
    }
    if (context === 'coordinator' && tier === 'wave-only') {
      return { excluded: true };
    }
  }

  return { excluded: false };
}

// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------

/**
 * @typedef {object} RuleEntry
 * @property {string} path - absolute path to the rule file
 * @property {string} content - raw file contents (byte-identical to disk)
 * @property {boolean} alwaysOn - true when neither `globs:` nor its `paths:`
 *   alias (issue #795) frontmatter is present (UNCHANGED semantics; DISTINCT
 *   from the `alwaysApply` frontmatter key)
 * @property {string[]} matchedGlobs - globs that matched; empty when alwaysOn
 * @property {true} [_parseError] - present only on frontmatter parse-error entries
 * @property {string} [description] - frontmatter `description` (issue #694), when present
 * @property {string} [mode] - frontmatter `mode` (issue #694), when present
 * @property {string} [hostClass] - frontmatter `host-class` (issue #694), when present
 * @property {boolean} [alwaysApply] - frontmatter `alwaysApply` (issue #694), when present
 * @property {string} [expiresAt] - frontmatter `expires-at` ISO date (issue #694), when present
 * @property {string} [learningKey] - frontmatter `learning-key` (issue #694), when present
 * @property {boolean} [autoGenerated] - frontmatter `auto-generated` (issue #694), when present
 * @property {number} [confidence] - frontmatter `confidence` (issue #694), when present
 * @property {string} [tier] - frontmatter `tier` (issue #692): 'coordinator-only' | 'wave-only' | 'always', when present
 */

/**
 * Loads rule files from `rulesDir` and returns those applicable to the given
 * `scopePaths` and activation axes.
 *
 * Rules without `globs:` (or its `paths:` alias — issue #795) frontmatter are
 * always included (alwaysOn: true). Rules with `globs:`/`paths:` are included
 * only when at least one scopePath matches at least one glob pattern.
 *
 * After a successful frontmatter parse, deterministic gates (issue #694) are
 * applied to BOTH always-on and glob-matched rules — a rule must pass ALL
 * active gates (expiry + mode + host-class) to be included. The new params are
 * strictly optional and default to "no gating", so the issue #336 two-key call
 * shape stays 100% backward-compatible.
 *
 * On frontmatter parse error, the rule is treated as always-on and a warning
 * is emitted to stderr — rules are never silently dropped. (Parse-error rules
 * carry no meta, so they pass every gate.)
 *
 * @param {object} opts
 * @param {string} opts.rulesDir - absolute path to the directory containing rule *.md files
 * @param {string[]} [opts.scopePaths] - paths (relative to repo root) to match against globs
 * @param {string|null} [opts.mode] - when non-null, exclude rules whose `mode` differs
 * @param {string|null} [opts.hostClass] - when non-null, exclude rules whose `host-class` differs
 * @param {number} [opts.now] - epoch ms used for expiry gating (injectable for tests)
 * @param {string|null} [opts.context] - 'wave' | 'coordinator' | null; when non-null, applies
 *   tier gating: 'wave' excludes coordinator-only rules, 'coordinator' excludes wave-only rules.
 *   null (default) disables tier gating entirely — backward-compatible with all existing callers.
 * @returns {RuleEntry[]}
 */
export function loadApplicableRules({
  rulesDir,
  scopePaths = [],
  mode = null,
  hostClass = null,
  now = Date.now(),
  context = null,
}) {
  /** @type {string[]} */
  let entries;
  try {
    entries = readdirSync(rulesDir);
  } catch (err) {
    process.stderr.write(`[rule-loader] Cannot read rulesDir ${rulesDir}: ${err.message}\n`);
    return [];
  }

  // Normalize scopePaths to forward slashes for consistent matching
  const normalizedScope = scopePaths.map((p) => p.replace(/\\/g, '/'));

  /** @type {RuleEntry[]} */
  const results = [];

  for (const entry of entries) {
    if (extname(entry) !== '.md') continue;

    const filePath = join(rulesDir, entry);
    let content;

    try {
      content = readFileSync(filePath, 'utf8');
    } catch (err) {
      process.stderr.write(`[rule-loader] Cannot read ${filePath}: ${err.message}\n`);
      continue;
    }

    let globs;
    let meta;
    let parseError = false;

    try {
      ({ globs, meta } = parseGlobsFrontmatter(content));
    } catch (err) {
      process.stderr.write(
        `[rule-loader] Frontmatter parse error in ${filePath}: ${err.message} — treating as always-on\n`,
      );
      globs = null;
      meta = {};
      parseError = true;
    }

    // Deterministic gating (issue #694 + #692) — applies to BOTH always-on and
    // glob-matched candidates. Parse-error rules carry empty meta, so they pass
    // every gate (preserving fail-open behavior).
    if (!parseError && applyGates(meta, filePath, mode, hostClass, now, context).excluded) {
      continue;
    }

    // Camel-cased meta fields surfaced on the entry (only present keys).
    const metaFields = metaToEntryFields(meta);

    if (globs === null) {
      // No globs frontmatter (or parse error) → always-on
      results.push({
        path: filePath,
        content,
        alwaysOn: true,
        matchedGlobs: [],
        ...metaFields,
        ...(parseError ? { _parseError: true } : {}),
      });
      continue;
    }

    if (globs.length === 0) {
      // Empty globs array: matches nothing (intentionally scoped out)
      continue;
    }

    // Check whether any scopePath matches any glob
    const matchedGlobs = [];
    for (const glob of globs) {
      const matched = normalizedScope.some((sp) => matchGlob(sp, glob));
      if (matched) {
        matchedGlobs.push(glob);
      }
    }

    if (matchedGlobs.length > 0) {
      results.push({
        path: filePath,
        content,
        alwaysOn: false,
        matchedGlobs,
        ...metaFields,
      });
    }
  }

  return results;
}