@intellectronica/ruler
Version:
Ruler — apply the same rules to all coding agents
291 lines (290 loc) • 11.8 kB
JavaScript
;
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || (function () {
var ownKeys = function(o) {
ownKeys = Object.getOwnPropertyNames || function (o) {
var ar = [];
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
return ar;
};
return ownKeys(o);
};
return function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
__setModuleDefault(result, mod);
return result;
};
})();
Object.defineProperty(exports, "__esModule", { value: true });
exports.findRulerDir = findRulerDir;
exports.readMarkdownFiles = readMarkdownFiles;
exports.writeGeneratedFile = writeGeneratedFile;
exports.backupFile = backupFile;
exports.ensureDirExists = ensureDirExists;
exports.findGlobalRulerDir = findGlobalRulerDir;
exports.findAllRulerDirs = findAllRulerDirs;
const fs_1 = require("fs");
const path = __importStar(require("path"));
const os = __importStar(require("os"));
const constants_1 = require("../constants");
/**
* Gets the XDG config directory path, falling back to ~/.config if XDG_CONFIG_HOME is not set.
*/
function getXdgConfigDir() {
return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
}
/**
* Searches upwards from startPath to find a directory named .ruler.
* If not found locally and checkGlobal is true, checks for global config at XDG_CONFIG_HOME/ruler.
* Returns the path to the .ruler directory, or null if not found.
*/
async function findRulerDir(startPath, checkGlobal = true) {
// First, search upwards from startPath for local .ruler directory
let current = startPath;
while (current) {
const candidate = path.join(current, '.ruler');
try {
const stat = await fs_1.promises.stat(candidate);
if (stat.isDirectory()) {
return candidate;
}
}
catch {
// ignore errors when checking for .ruler directory
}
const parent = path.dirname(current);
if (parent === current) {
break;
}
current = parent;
}
// If no local .ruler found and checkGlobal is true, check global config directory
if (checkGlobal) {
const globalConfigDir = path.join(getXdgConfigDir(), 'ruler');
try {
const stat = await fs_1.promises.stat(globalConfigDir);
if (stat.isDirectory()) {
return globalConfigDir;
}
}
catch (err) {
console.error(`[ruler] Error checking global config directory ${globalConfigDir}:`, err);
}
}
return null;
}
/**
* Recursively reads all Markdown (.md) files in rulerDir, returning their paths and contents.
* Files are sorted alphabetically by path.
*/
async function readMarkdownFiles(rulerDir) {
const mdFiles = [];
// Gather all markdown files (recursive) first
async function walk(dir) {
const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
for (const entry of entries) {
const fullPath = path.join(dir, entry.name);
// Resolve symlinks to determine actual type
let isDir = entry.isDirectory();
let isFile = entry.isFile();
if (entry.isSymbolicLink()) {
try {
const stat = await fs_1.promises.stat(fullPath);
isDir = stat.isDirectory();
isFile = stat.isFile();
}
catch {
continue; // skip broken symlinks
}
}
if (isDir) {
// Skip .ruler/skills; skills are propagated separately and should not be concatenated
const relativeFromRoot = path.relative(rulerDir, fullPath);
const isSkillsDir = relativeFromRoot === constants_1.SKILLS_DIR ||
relativeFromRoot.startsWith(`${constants_1.SKILLS_DIR}${path.sep}`);
if (isSkillsDir) {
continue;
}
await walk(fullPath);
}
else if (isFile && entry.name.endsWith('.md')) {
const content = await fs_1.promises.readFile(fullPath, 'utf8');
mdFiles.push({ path: fullPath, content });
}
}
}
await walk(rulerDir);
// Prioritisation logic:
// 1. Prefer top-level AGENTS.md if present.
// 2. If AGENTS.md absent but legacy instructions.md present, use it (no longer emits a warning; legacy accepted silently).
// 3. Include any remaining .md files (excluding whichever of the above was used if present) in
// sorted order AFTER the preferred primary file so that new concatenation priority starts with AGENTS.md.
const topLevelAgents = path.join(rulerDir, 'AGENTS.md');
const topLevelLegacy = path.join(rulerDir, 'instructions.md');
// Separate primary candidates from others
let primaryFile = null;
const others = [];
for (const f of mdFiles) {
if (f.path === topLevelAgents) {
primaryFile = f; // Highest priority
}
}
if (!primaryFile) {
for (const f of mdFiles) {
if (f.path === topLevelLegacy) {
primaryFile = f;
break;
}
}
}
for (const f of mdFiles) {
if (primaryFile && f.path === primaryFile.path)
continue;
others.push(f);
}
// Sort the remaining others for stable deterministic concatenation order.
others.sort((a, b) => a.path.localeCompare(b.path));
let ordered = primaryFile ? [primaryFile, ...others] : others;
// NEW: Prepend repository root AGENTS.md (outside .ruler) if it exists and is not identical path.
try {
const repoRoot = path.dirname(rulerDir); // .ruler parent
const rootAgentsPath = path.join(repoRoot, 'AGENTS.md');
if (path.resolve(rootAgentsPath) !== path.resolve(topLevelAgents)) {
const stat = await fs_1.promises.stat(rootAgentsPath);
if (stat.isFile()) {
const content = await fs_1.promises.readFile(rootAgentsPath, 'utf8');
// Check if this is a generated file and we have other .ruler files
const isGenerated = content.startsWith('<!-- Generated by Ruler -->');
const hasRulerFiles = others.length > 0 || primaryFile !== null;
// Additional check: if AGENTS.md contains ruler source comments and we have ruler files,
// it's likely a corrupted generated file that should be skipped
const containsRulerSources = content.includes('<!-- Source: .ruler/') ||
content.includes('<!-- Source: ruler/');
const isProbablyGenerated = isGenerated || (containsRulerSources && hasRulerFiles);
// Skip generated AGENTS.md if we have other files in .ruler
if (!isProbablyGenerated || !hasRulerFiles) {
// Prepend so it has highest precedence
ordered = [{ path: rootAgentsPath, content }, ...ordered];
}
}
}
}
catch {
// ignore if root AGENTS.md not present
}
return ordered;
}
/**
* Writes content to filePath, creating parent directories if necessary.
*/
async function writeGeneratedFile(filePath, content) {
await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
await fs_1.promises.writeFile(filePath, content, 'utf8');
}
/**
* Creates a backup of the given filePath by copying it to filePath.bak if it exists.
*/
async function backupFile(filePath) {
try {
await fs_1.promises.access(filePath);
await fs_1.promises.copyFile(filePath, `${filePath}.bak`);
}
catch {
// ignore if file does not exist
}
}
/**
* Ensures that the given directory exists by creating it recursively.
*/
async function ensureDirExists(dirPath) {
await fs_1.promises.mkdir(dirPath, { recursive: true });
}
/**
* Finds the global ruler configuration directory at XDG_CONFIG_HOME/ruler.
* Returns the path if it exists, null otherwise.
*/
async function findGlobalRulerDir() {
const globalConfigDir = path.join(getXdgConfigDir(), 'ruler');
try {
const stat = await fs_1.promises.stat(globalConfigDir);
if (stat.isDirectory()) {
return globalConfigDir;
}
}
catch {
// ignore if global config doesn't exist
}
return null;
}
/**
* Searches the entire directory tree from startPath to find all .ruler directories.
* Returns an array of .ruler directory paths from most specific to least specific.
*/
async function findAllRulerDirs(startPath) {
const rulerDirs = [];
const rootPath = path.resolve(startPath);
// Search the entire directory tree downwards from startPath
async function findRulerDirs(dir) {
try {
const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
for (const entry of entries) {
const fullPath = path.join(dir, entry.name);
if (entry.isDirectory()) {
if (entry.name === '.ruler') {
rulerDirs.push(fullPath);
}
else {
// Recursively search subdirectories (but skip hidden directories like .git)
if (!entry.name.startsWith('.')) {
// Do not cross git repository boundaries (except the starting root)
const gitDir = path.join(fullPath, '.git');
try {
const gitStat = await fs_1.promises.stat(gitDir);
if (gitStat.isDirectory() &&
path.resolve(fullPath) !== rootPath) {
continue;
}
}
catch {
// no .git boundary, continue traversal
}
await findRulerDirs(fullPath);
}
}
}
}
}
catch {
// ignore errors when reading directories
}
}
// Start searching from the startPath
await findRulerDirs(startPath);
// Sort by depth (most specific first) - deeper paths come first
rulerDirs.sort((a, b) => {
const depthA = a.split(path.sep).length;
const depthB = b.split(path.sep).length;
if (depthA !== depthB) {
return depthB - depthA; // Deeper paths first
}
return a.localeCompare(b); // Alphabetical for same depth
});
return rulerDirs;
}