@polarpoint/agentsmd-validator 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# @polarpoint/agentsmd-validator
+
+Validates `AGENTS.md` files against a zone-structured schema. Designed for use in CI pipelines across platform engineering repos.
+
+## Usage
+
+```bash
+npx @polarpoint/agentsmd-validator \
+  --schema https://raw.githubusercontent.com/your-org/platform-standards/main/schema.json \
+  --file AGENTS.md
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--file <path>` | Path to the AGENTS.md file to validate (required) |
+| `--schema <url\|path>` | URL or local path to a schema.json (optional) |
+| `--strict` | Treat warnings as errors (non-zero exit) |
+
+## What it checks
+
+1. **Zone markers present** — `<!-- zone:1:start -->` / `<!-- zone:1:end -->` exist
+2. **Zone order** — zones appear in ascending numeric order
+3. **Required Zone 1 sections** — `## Sync model`, `## Forbidden paths`, `## Naming conventions`, `## Running tests` all present
+4. **Running tests is actionable** — the section contains at least one executable command (code block or inline command)
+5. **Zone 1 hash** — if a schema is supplied, warns when Zone 1 content has drifted from the template version
+
+## Zone structure
+
+```markdown
+<!-- zone:1:start -->
+## Sync model
+...
+## Forbidden paths
+...
+## Naming conventions
+...
+## Running tests
+...
+<!-- zone:1:end -->
+
+<!-- zone:2:start -->
+## Team conventions
+...
+<!-- zone:2:end -->
+
+<!-- zone:3:start -->
+## Repo-specific notes
+...
+<!-- zone:3:end -->
+```
+
+## GitHub Actions
+
+Copy `.github/workflows/validate-agents-md.yml` into your repo, update the `--schema` URL to point at your `platform-standards` repo, and the validator runs on every PR that touches `AGENTS.md`.
+
+## Schema format
+
+```json
+{
+  "templateVersion": "1.0.0",
+  "zone1Hash": "98dfe660cbdaf240",
+  "requiredSections": ["Sync model", "Forbidden paths", "Naming conventions", "Running tests"]
+}
+```
+
+After editing your template, regenerate `zone1Hash`:
+
+```bash
+node -e "
+  const c=require('crypto'), f=require('fs');
+  const z=f.readFileSync('templates/default-agents-md.md','utf8')
+    .match(/zone:1:start[\s\S]*?zone:1:end/)[0];
+  console.log(c.createHash('sha256').update(z.replace(/\s+/g,' ').trim()).digest('hex').slice(0,16))
+"
+```

package/bin/agentsmd-validator.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs      = require('fs');
+const path    = require('path');
+const https   = require('https');
+const http    = require('http');
+const { validate } = require('../lib/validator');
+
+// ── CLI argument parsing ──────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+let schemaArg = null;
+let fileArg   = null;
+let strict    = false;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--schema' && args[i + 1]) { schemaArg = args[++i]; continue; }
+  if (args[i] === '--file'   && args[i + 1]) { fileArg   = args[++i]; continue; }
+  if (args[i] === '--strict')                { strict = true;          continue; }
+  if (args[i] === '--version' || args[i] === '-v') {
+    const pkg = require('../package.json');
+    console.log(pkg.version);
+    process.exit(0);
+  }
+  if (args[i] === '--help' || args[i] === '-h') {
+    console.log(`
+Usage: agentsmd-validator --file <path> [--schema <url|path>] [--strict]
+
+Options:
+  --file <path>      Path to AGENTS.md file to validate (required)
+  --schema <url>     URL or path to schema.json for drift detection (optional)
+  --strict           Treat warnings as errors (non-zero exit code)
+  --version, -v      Print version
+  --help, -h         Print this help
+
+Examples:
+  npx @polarpoint/agentsmd-validator --file AGENTS.md
+  npx @polarpoint/agentsmd-validator \\
+    --file AGENTS.md \\
+    --schema https://raw.githubusercontent.com/your-org/platform-standards/main/schema.json
+`);
+    process.exit(0);
+  }
+}
+
+if (!fileArg) {
+  console.error('Error: --file is required\n');
+  console.error('Usage: agentsmd-validator --file <path> [--schema <url|path>] [--strict]');
+  console.error('       agentsmd-validator --help');
+  process.exit(1);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function fetchUrl(url) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith('https') ? https : http;
+    client.get(url, res => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchUrl(res.headers.location).then(resolve).catch(reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+      }
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+function loadSchema(schemaArg) {
+  if (!schemaArg) return Promise.resolve(null);
+  if (schemaArg.startsWith('http://') || schemaArg.startsWith('https://')) {
+    return fetchUrl(schemaArg).then(JSON.parse).catch(err => {
+      console.warn(`  ⚠  Could not fetch schema from ${schemaArg}: ${err.message}`);
+      return null;
+    });
+  }
+  try {
+    return Promise.resolve(JSON.parse(fs.readFileSync(path.resolve(schemaArg), 'utf8')));
+  } catch (err) {
+    console.warn(`  ⚠  Could not read schema file ${schemaArg}: ${err.message}`);
+    return Promise.resolve(null);
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+async function main() {
+  const filePath = path.resolve(fileArg);
+  if (!fs.existsSync(filePath)) {
+    console.error(`  ✗  File not found: ${filePath}`);
+    process.exit(1);
+  }
+
+  const content    = fs.readFileSync(filePath, 'utf8');
+  const schemaData = await loadSchema(schemaArg);
+
+  console.log(`\nValidating ${path.basename(filePath)}\n${'─'.repeat(50)}`);
+
+  const { errors, warnings, zone1Hash } = validate(content, schemaData);
+
+  if (zone1Hash) {
+    console.log(`  Zone 1 hash : ${zone1Hash}`);
+  }
+
+  if (warnings.length) {
+    console.log('');
+    warnings.forEach(w => console.log(`  ⚠  ${w}`));
+  }
+
+  if (errors.length) {
+    console.log('');
+    errors.forEach(e => console.error(`  ✗  ${e}`));
+    console.log(`\n${'─'.repeat(50)}`);
+    console.log(`  FAILED  ${errors.length} error(s), ${warnings.length} warning(s)\n`);
+    process.exit(1);
+  }
+
+  console.log(`\n${'─'.repeat(50)}`);
+  if (warnings.length) {
+    console.log(`  PASSED with ${warnings.length} warning(s)\n`);
+    if (strict) {
+      console.log('  (--strict mode: warnings treated as errors)');
+      process.exit(1);
+    }
+  } else {
+    console.log('  PASSED\n');
+  }
+}
+
+main().catch(err => {
+  console.error(`  ✗  Unexpected error: ${err.message}`);
+  process.exit(1);
+});

package/lib/parser.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const ZONE_START = /<!--\s*zone:(\d+):start\s*-->/;
+const ZONE_END   = /<!--\s*zone:(\d+):end\s*-->/;
+
+/**
+ * Parse an AGENTS.md file into its zone segments.
+ * Returns { zones: { 1: string, 2: string, 3: string }, raw: string }
+ */
+function parseZones(content) {
+  const lines = content.split('\n');
+  const zones = {};
+  let currentZone = null;
+  let buffer = [];
+  const order = [];   // track order zones were opened
+
+  for (const line of lines) {
+    const startMatch = line.match(ZONE_START);
+    const endMatch   = line.match(ZONE_END);
+
+    if (startMatch) {
+      currentZone = parseInt(startMatch[1], 10);
+      order.push(currentZone);
+      buffer = [];
+      continue;
+    }
+
+    if (endMatch) {
+      const z = parseInt(endMatch[1], 10);
+      if (currentZone === z) {
+        zones[z] = buffer.join('\n').trim();
+        currentZone = null;
+        buffer = [];
+      }
+      continue;
+    }
+
+    if (currentZone !== null) {
+      buffer.push(line);
+    }
+  }
+
+  return { zones, order, raw: content };
+}
+
+/**
+ * Compute a stable SHA-256 hash of zone content (normalised whitespace).
+ */
+function hashZone(content) {
+  const normalised = content.replace(/\s+/g, ' ').trim();
+  return crypto.createHash('sha256').update(normalised).digest('hex').slice(0, 16);
+}
+
+/**
+ * Extract all headings (## level) from a zone string.
+ */
+function headingsInZone(zoneContent) {
+  return (zoneContent.match(/^##\s+.+/gm) || []).map(h => h.replace(/^##\s+/, '').trim());
+}
+
+/**
+ * Detect whether a block of text contains at least one shell-executable command.
+ * Heuristic: a line inside a fenced code block, or a line starting with common
+ * shell tokens (make, npm, yarn, pnpm, go, cargo, pytest, mvn, gradle, ./...).
+ */
+function hasExecutableCommand(zoneContent) {
+  const codeBlocks = [...zoneContent.matchAll(/```[\s\S]*?```/g)];
+  if (codeBlocks.length > 0) {
+    for (const block of codeBlocks) {
+      const inner = block[0].replace(/^```[^\n]*\n/, '').replace(/```$/, '');
+      if (/\S/.test(inner)) return true;
+    }
+  }
+  // inline code that looks like a command
+  const inlineCode = [...zoneContent.matchAll(/`([^`]+)`/g)].map(m => m[1]);
+  const cmdPattern = /^(make|npm|yarn|pnpm|go\s|cargo|pytest|mvn|gradle|\.\/|python|node|bash|sh\s|docker|kubectl)/;
+  return inlineCode.some(c => cmdPattern.test(c.trim()));
+}
+
+module.exports = { parseZones, hashZone, headingsInZone, hasExecutableCommand };

package/lib/validator.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const { parseZones, hashZone, headingsInZone, hasExecutableCommand } = require('./parser');
+
+const REQUIRED_ZONE1_SECTIONS = [
+  'Sync model',
+  'Forbidden paths',
+  'Naming conventions',
+  'Running tests',
+];
+
+/**
+ * Run all checks against the parsed content.
+ * Returns { errors: string[], warnings: string[], zone1Hash: string }
+ */
+function validate(content, schemaData) {
+  const errors   = [];
+  const warnings = [];
+
+  const { zones, order } = parseZones(content);
+
+  // ── 1. Zone markers present ───────────────────────────────────────────────
+  if (!zones[1]) {
+    errors.push('Zone 1 is missing. Add <!-- zone:1:start --> and <!-- zone:1:end --> markers.');
+  }
+  if (!zones[2]) {
+    warnings.push('Zone 2 markers not found. Guarded section is optional but recommended.');
+  }
+  if (!zones[3]) {
+    warnings.push('Zone 3 markers not found. Free section is optional but recommended.');
+  }
+
+  // ── 2. Zone order ─────────────────────────────────────────────────────────
+  if (order.length > 1) {
+    for (let i = 1; i < order.length; i++) {
+      if (order[i] < order[i - 1]) {
+        errors.push(`Zone markers are out of order: zone ${order[i]} appears after zone ${order[i - 1]}.`);
+      }
+    }
+  }
+
+  // ── 3. Required sections inside Zone 1 ───────────────────────────────────
+  if (zones[1]) {
+    const headings = headingsInZone(zones[1]);
+    for (const section of REQUIRED_ZONE1_SECTIONS) {
+      if (!headings.some(h => h.toLowerCase().includes(section.toLowerCase()))) {
+        errors.push(`Required section "## ${section}" is missing from Zone 1.`);
+      }
+    }
+
+    // ── 4. Running tests must contain an executable command ────────────────
+    const testsIdx = headings.findIndex(h => h.toLowerCase().includes('running tests'));
+    if (testsIdx !== -1) {
+      // extract just the Running tests sub-section
+      const z1Lines   = zones[1].split('\n');
+      let inTests     = false;
+      let testsBuffer = [];
+      for (const line of z1Lines) {
+        if (/^##\s+Running tests/i.test(line)) { inTests = true; continue; }
+        if (inTests && /^##\s+/.test(line)) break;
+        if (inTests) testsBuffer.push(line);
+      }
+      const testsContent = testsBuffer.join('\n');
+      if (!hasExecutableCommand(testsContent)) {
+        errors.push('"## Running tests" in Zone 1 must contain at least one executable command (code block or inline command).');
+      }
+    }
+
+    // ── 5. Zone 1 hash drift check ────────────────────────────────────────
+    const zone1Hash = hashZone(zones[1]);
+    if (schemaData && schemaData.zone1Hash) {
+      if (zone1Hash !== schemaData.zone1Hash) {
+        warnings.push(
+          `Zone 1 content hash (${zone1Hash}) does not match template version ` +
+          `${schemaData.templateVersion || 'unknown'} (${schemaData.zone1Hash}). ` +
+          `Run the sync engine or update Zone 1 from platform-standards.`
+        );
+      }
+    }
+
+    return { errors, warnings, zone1Hash };
+  }
+
+  return { errors, warnings, zone1Hash: null };
+}
+
+module.exports = { validate };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@polarpoint/agentsmd-validator",
+  "version": "1.0.0",
+  "description": "Validate AGENTS.md files against a zone-structured schema",
+  "main": "lib/validator.js",
+  "bin": {
+    "agentsmd-validator": "./bin/agentsmd-validator.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "node bin/agentsmd-validator.js --file bin/agentsmd-validator.js 2>/dev/null || true"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "validation",
+    "platform-engineering",
+    "gitops",
+    "agentsmd"
+  ],
+  "author": "Polarpoint <hello@polarpoint.io>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polarpoint-io/ai-capabilities.git",
+    "directory": "agentsmd-validator"
+  },
+  "homepage": "https://github.com/polarpoint-io/ai-capabilities/tree/main/agentsmd-validator#readme",
+  "bugs": {
+    "url": "https://github.com/polarpoint-io/ai-capabilities/issues"
+  }
+}