1#!/usr/bin/env npx ts-node
2 
3/**
4 * Build script for generating AGENTS.md from individual rule files
5 *
6 * Usage: npx ts-node scripts/build-agents.ts
7 *
8 * This script:
9 * 1. Reads all rule files from the rules/ directory
10 * 2. Parses YAML frontmatter for metadata
11 * 3. Groups rules by category based on filename prefix
12 * 4. Generates a consolidated AGENTS.md file
13 */
14 
15import * as fs from 'fs';
16import * as path from 'path';
17import { fileURLToPath } from 'url';
18import { dirname } from 'path';
19 
20const __filename = fileURLToPath(import.meta.url);
21const __dirname = dirname(__filename);
22 
23// Category definitions with ordering and metadata
24const CATEGORIES = [
25  { prefix: 'arch-', name: 'Architecture', impact: 'CRITICAL', section: 1 },
26  { prefix: 'di-', name: 'Dependency Injection', impact: 'CRITICAL', section: 2 },
27  { prefix: 'error-', name: 'Error Handling', impact: 'HIGH', section: 3 },
28  { prefix: 'security-', name: 'Security', impact: 'HIGH', section: 4 },
29  { prefix: 'perf-', name: 'Performance', impact: 'HIGH', section: 5 },
30  { prefix: 'test-', name: 'Testing', impact: 'MEDIUM-HIGH', section: 6 },
31  { prefix: 'db-', name: 'Database & ORM', impact: 'MEDIUM-HIGH', section: 7 },
32  { prefix: 'api-', name: 'API Design', impact: 'MEDIUM', section: 8 },
33  { prefix: 'micro-', name: 'Microservices', impact: 'MEDIUM', section: 9 },
34  { prefix: 'devops-', name: 'DevOps & Deployment', impact: 'LOW-MEDIUM', section: 10 },
35];
36 
37interface RuleFrontmatter {
38  title: string;
39  impact: string;
40  impactDescription: string;
41  tags: string[];
42}
43 
44interface Rule {
45  filename: string;
46  frontmatter: RuleFrontmatter;
47  content: string;
48  category: string;
49  categorySection: number;
50}
51 
52function parseFrontmatter(content: string): { frontmatter: RuleFrontmatter | null; body: string } {
53  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
54  const match = content.match(frontmatterRegex);
55 
56  if (!match) {
57    return { frontmatter: null, body: content };
58  }
59 
60  const frontmatterStr = match[1];
61  const body = match[2];
62 
63  // Simple YAML parsing for our expected format
64  const frontmatter: Partial<RuleFrontmatter> = {};
65  const lines = frontmatterStr.split('\n');
66  let currentKey = '';
67  let inArray = false;
68  const arrayItems: string[] = [];
69 
70  for (const line of lines) {
71    if (line.match(/^[a-zA-Z]+:/)) {
72      // Save previous array if we were collecting one
73      if (inArray && currentKey === 'tags') {
74        frontmatter.tags = arrayItems;
75      }
76      inArray = false;
77      arrayItems.length = 0;
78 
79      const [key, ...valueParts] = line.split(':');
80      const value = valueParts.join(':').trim();
81      currentKey = key.trim();
82 
83      if (value === '') {
84        // Might be start of array
85        inArray = true;
86      } else {
87        (frontmatter as any)[currentKey] = value;
88      }
89    } else if (inArray && line.trim().startsWith('-')) {
90      arrayItems.push(line.trim().replace(/^-\s*/, ''));
91    }
92  }
93 
94  // Save final array if needed
95  if (inArray && currentKey === 'tags') {
96    frontmatter.tags = arrayItems;
97  }
98 
99  return {
100    frontmatter: frontmatter as RuleFrontmatter,
101    body: body.trim()
102  };
103}
104 
105function getCategoryForFile(filename: string): { name: string; section: number } | null {
106  for (const cat of CATEGORIES) {
107    if (filename.startsWith(cat.prefix)) {
108      return { name: cat.name, section: cat.section };
109    }
110  }
111  return null;
112}
113 
114function readMetadata(): any {
115  const metadataPath = path.join(__dirname, '..', 'metadata.json');
116  return JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
117}
118 
119function readRules(): Rule[] {
120  const rulesDir = path.join(__dirname, '..', 'rules');
121  const files = fs.readdirSync(rulesDir)
122    .filter(f => f.endsWith('.md') && !f.startsWith('_'));
123 
124  const rules: Rule[] = [];
125 
126  for (const file of files) {
127    const filePath = path.join(rulesDir, file);
128    const content = fs.readFileSync(filePath, 'utf-8');
129    const { frontmatter, body } = parseFrontmatter(content);
130 
131    if (!frontmatter) {
132      console.warn(`Warning: No frontmatter found in ${file}`);
133      continue;
134    }
135 
136    const category = getCategoryForFile(file);
137    if (!category) {
138      console.warn(`Warning: Unknown category for ${file}`);
139      continue;
140    }
141 
142    rules.push({
143      filename: file,
144      frontmatter,
145      content: body,
146      category: category.name,
147      categorySection: category.section
148    });
149  }
150 
151  return rules;
152}
153 
154function generateTableOfContents(rulesByCategory: Map<string, Rule[]>): string {
155  let toc = '## Table of Contents\n\n';
156 
157  for (const cat of CATEGORIES) {
158    const rules = rulesByCategory.get(cat.name);
159    if (!rules || rules.length === 0) continue;
160 
161    // Section anchor format: #1-architecture
162    const sectionAnchor = `${cat.section}-${cat.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
163    toc += `${cat.section}. [${cat.name}](#${sectionAnchor}) — **${cat.impact}**\n`;
164 
165    for (let i = 0; i < rules.length; i++) {
166      const rule = rules[i];
167      // Rule anchor format: #11-rule-title
168      const ruleNum = `${cat.section}${i + 1}`;
169      const anchor = `${ruleNum}-${rule.frontmatter.title.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
170      toc += `   - ${cat.section}.${i + 1} [${rule.frontmatter.title}](#${anchor})\n`;
171    }
172  }
173 
174  return toc;
175}
176 
177function generateAgentsMd(rules: Rule[], metadata: any): string {
178  // Group rules by category
179  const rulesByCategory = new Map<string, Rule[]>();
180 
181  for (const rule of rules) {
182    if (!rulesByCategory.has(rule.category)) {
183      rulesByCategory.set(rule.category, []);
184    }
185    rulesByCategory.get(rule.category)!.push(rule);
186  }
187 
188  // Sort rules within each category alphabetically
189  for (const [category, categoryRules] of rulesByCategory) {
190    categoryRules.sort((a, b) => a.filename.localeCompare(b.filename));
191  }
192 
193  // Build document
194  let doc = `# NestJS Best Practices
195 
196**Version ${metadata.version}**
197${metadata.organization}
198${metadata.date}
199 
200> **Note:**
201> This document is mainly for agents and LLMs to follow when maintaining,
202> generating, or refactoring NestJS codebases. Humans may also find it
203> useful, but guidance here is optimized for automation and consistency
204> by AI-assisted workflows.
205 
206---
207 
208## Abstract
209 
210${metadata.abstract}
211 
212---
213 
214`;
215 
216  // Add table of contents
217  doc += generateTableOfContents(rulesByCategory);
218  doc += '\n---\n\n';
219 
220  // Add rules by category
221  for (const cat of CATEGORIES) {
222    const categoryRules = rulesByCategory.get(cat.name);
223    if (!categoryRules || categoryRules.length === 0) continue;
224 
225    doc += `## ${cat.section}. ${cat.name}\n\n`;
226    doc += `**Section Impact: ${cat.impact}**\n\n`;
227 
228    for (let i = 0; i < categoryRules.length; i++) {
229      const rule = categoryRules[i];
230      const ruleNumber = `${cat.section}.${i + 1}`;
231 
232      // Add rule header with number (anchor will be auto-generated as #11-title)
233      doc += `### ${ruleNumber} ${rule.frontmatter.title}\n\n`;
234      doc += `**Impact: ${rule.frontmatter.impact}** — ${rule.frontmatter.impactDescription}\n\n`;
235 
236      // Add rule content (skip the first header since we already added it)
237      let ruleContent = rule.content;
238      // Remove the first h1 or h2 header if it matches the title
239      ruleContent = ruleContent.replace(/^#{1,2}\s+.*\n+/, '');
240      // Remove the impact line if present (we already added it)
241      ruleContent = ruleContent.replace(/^\*\*Impact:.*\*\*.*\n+/, '');
242 
243      doc += ruleContent;
244      doc += '\n\n---\n\n';
245    }
246  }
247 
248  // Add references footer
249  doc += `## References
250 
251`;
252  for (const ref of metadata.references) {
253    doc += `- ${ref}\n`;
254  }
255 
256  doc += `
257---
258 
259*Generated by build-agents.ts on ${new Date().toISOString().split('T')[0]}*
260`;
261 
262  return doc;
263}
264 
265function main() {
266  console.log('Building AGENTS.md...\n');
267 
268  const metadata = readMetadata();
269  console.log(`Version: ${metadata.version}`);
270  console.log(`Organization: ${metadata.organization}\n`);
271 
272  const rules = readRules();
273  console.log(`Found ${rules.length} rules\n`);
274 
275  // Count by category
276  const counts = new Map<string, number>();
277  for (const rule of rules) {
278    counts.set(rule.category, (counts.get(rule.category) || 0) + 1);
279  }
280 
281  console.log('Rules by category:');
282  for (const cat of CATEGORIES) {
283    const count = counts.get(cat.name) || 0;
284    if (count > 0) {
285      console.log(`  ${cat.name}: ${count}`);
286    }
287  }
288  console.log('');
289 
290  const agentsMd = generateAgentsMd(rules, metadata);
291 
292  const outputPath = path.join(__dirname, '..', 'AGENTS.md');
293  fs.writeFileSync(outputPath, agentsMd);
294 
295  console.log(`Generated AGENTS.md (${agentsMd.length} bytes)`);
296  console.log(`Output: ${outputPath}`);
297}
298 
299main();
300