@yegor256/dogent 0.1.0 → 0.3.0

package/README.md

@@ -23,7 +23,7 @@ We respect [agent-sh/agnix](https://github.com/agent-sh/agnix)
 Run it on any manifesto file, no installation required:
 
 ```bash
-npx @yegor256/dogent@0.0.1 CLAUDE.md
+npx @yegor256/dogent@0.1.0 CLAUDE.md
 ```
 
 Lint several files at once:
@@ -32,6 +32,13 @@ Lint several files at once:
 npx @yegor256/dogent SKILL.md CLAUDE.md AGENTS.md
 ```
 
+Point it at a directory to lint the default manifestos it holds
+  (`AGENTS.md`, `CLAUDE.md`, `SKILL.md`, `SKILLS.md`):
+
+```bash
+npx @yegor256/dogent .
+```
+
 Sample output:
 
 ```text
@@ -58,6 +65,8 @@ The command exits with a non-zero status when problems are found,
 - Every line must sound like a command.
 - No articles, no noise, no bloated text.
 - Simple grammar, no ambiguity.
+- `SKILL.md` must open with valid frontmatter.
+- Frontmatter must declare only allowed keys.
 
 ## AI verification
 
@@ -117,7 +126,7 @@ Reference `dogent` as a remote hook in `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yegor256/dogent
-    rev: 0.0.1
+    rev: 0.1.0
     hooks:
       - id: dogent
 ```

package/package.json

@@ -40,5 +40,5 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.1.0"
+  "version": "0.3.0"
 }

package/src/dogent.js

@@ -9,17 +9,18 @@
 const fs = require('fs');
 const Markdown = require('./markdown');
 const Report = require('./report');
+const Sources = require('./sources');
 const rules = require('./rules');
 
 const argv = process.argv.slice(2);
 const sarif = argv.indexOf('--sarif') !== -1;
-const files = argv.filter((arg) => arg !== '--sarif');
-if (files.length === 0) {
-  process.stderr.write('Usage: dogent [--sarif] <file.md>...\n');
+const paths = argv.filter((arg) => arg !== '--sarif');
+if (paths.length === 0) {
+  process.stderr.write('Usage: dogent [--sarif] <file.md|dir>...\n');
   process.exit(2);
 }
 const found = [];
-files.forEach((file) => {
+new Sources(paths).files().forEach((file) => {
   const document = new Markdown(file, fs.readFileSync(file, 'utf8')).document();
   rules().forEach((rule) => {
     rule.violations(document).forEach((violation) => found.push(violation));

package/src/fragments/frontmatter.js

@@ -0,0 +1,25 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Frontmatter.
+ *
+ * The leading YAML block of a manifesto, already parsed into an ordered
+ * list of key pairs, carrying the line where the opening fence sits.
+ * Stands apart from prose so no prose rule ever sees its keys.
+ */
+class Frontmatter {
+  constructor(pairs, line) {
+    this.keys = pairs;
+    this.row = line;
+  }
+  accept(visitor) {
+    return visitor.frontmatter(this.keys, this.row);
+  }
+}
+
+module.exports = Frontmatter;

package/src/markdown.js

@@ -10,6 +10,8 @@ const Header = require('./fragments/header');
 const Prose = require('./fragments/prose');
 const Bullets = require('./fragments/bullets');
 const Snippet = require('./fragments/snippet');
+const Frontmatter = require('./fragments/frontmatter');
+const Yaml = require('./yaml');
 
 /**
  * Markdown.
@@ -40,7 +42,21 @@ class Markdown {
         items = [];
       }
     };
-    this.content.split('\n').forEach((line, index) => {
+    const lines = this.content.split('\n');
+    let skip = 0;
+    if (lines[0].trim() === '---') {
+      const rest = lines.slice(1);
+      const close = rest.findIndex((line) => line.trim() === '---');
+      if (close !== -1) {
+        const front = rest.slice(0, close).join('\n');
+        pieces.push(new Frontmatter(new Yaml(front, 2).pairs(), 1));
+        skip = close + 2;
+      }
+    }
+    lines.forEach((line, index) => {
+      if (index < skip) {
+        return;
+      }
       const row = index + 1;
       const mark = line.match(/^\s*(?<fence>```|~~~)/u);
       if (fence !== '') {

package/src/rules/command.js

@@ -28,7 +28,8 @@ class Command {
       header: () => [],
       prose: (text, line) => this.judge(text, line, uri),
       snippet: () => [],
-      bullets: () => []
+      bullets: () => [],
+      frontmatter: () => []
     });
   }
   judge(text, line, uri) {

package/src/rules/frontmatter.js

@@ -0,0 +1,70 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Frontmatter.
+ *
+ * Demands that a skill file open with a YAML frontmatter block, declare
+ * every required key, and carry no key outside the allowed set. The
+ * block is mandatory for the named file and ignored for every other.
+ */
+class Frontmatter {
+  constructor(name, required, allowed) {
+    this.id = 'frontmatter';
+    this.name = name;
+    this.required = required;
+    this.allowed = allowed;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== this.name) {
+      return [];
+    }
+    const blocks = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (pairs) => [pairs]
+    });
+    if (blocks.length === 0) {
+      return [new Violation(
+        this.id,
+        'error',
+        'skill must open with frontmatter',
+        new Region(uri, 1, 1)
+      )];
+    }
+    return this.missing(blocks[0], uri).concat(this.extra(blocks[0], uri));
+  }
+  missing(pairs, uri) {
+    const present = pairs.map((pair) => pair.key);
+    return this.required
+      .filter((key) => !present.includes(key))
+      .map((key) => new Violation(
+        this.id,
+        'error',
+        `frontmatter must declare "${key}"`,
+        new Region(uri, 1, 1)
+      ));
+  }
+  extra(pairs, uri) {
+    return pairs
+      .filter((pair) => !this.allowed.includes(pair.key))
+      .map((pair) => new Violation(
+        this.id,
+        'error',
+        `frontmatter key "${pair.key}" forbidden`,
+        new Region(uri, pair.row, 1)
+      ));
+  }
+}
+
+module.exports = Frontmatter;

package/src/rules/grouped.js

@@ -24,7 +24,8 @@ class Grouped {
       header: (text, line) => [{header: true, line}],
       prose: (text, line) => [{header: false, line}],
       snippet: () => [],
-      bullets: () => []
+      bullets: () => [],
+      frontmatter: () => []
     });
     let first = Infinity;
     marks.forEach((mark) => {

package/src/rules/index.js

@@ -10,11 +10,17 @@ const ShortSections = require('./short-sections');
 const Grouped = require('./grouped');
 const NoArticles = require('./no-articles');
 const Command = require('./command');
+const Frontmatter = require('./frontmatter');
 
 module.exports = () => [
   new Grouped(),
   new ShortSections(),
   new LineLength(80),
   new NoArticles(),
-  new Command()
+  new Command(),
+  new Frontmatter(
+    'SKILL.md',
+    ['name', 'description'],
+    ['name', 'description', 'license', 'allowed-tools']
+  )
 ];

package/src/rules/line-length.js

@@ -25,7 +25,8 @@ class LineLength {
       header: (text, line) => this.over(text, line, uri),
       prose: (text, line) => this.over(text, line, uri),
       snippet: () => [],
-      bullets: () => []
+      bullets: () => [],
+      frontmatter: () => []
     });
   }
   over(text, line, uri) {

package/src/rules/no-articles.js

@@ -24,7 +24,8 @@ class NoArticles {
       header: () => [],
       prose: (text, line) => this.scan(text, line, uri),
       snippet: () => [],
-      bullets: () => []
+      bullets: () => [],
+      frontmatter: () => []
     });
   }
   scan(text, line, uri) {

package/src/rules/short-sections.js

@@ -24,7 +24,8 @@ class ShortSections {
       header: (text, line) => this.named(text, line, uri),
       prose: () => [],
       snippet: () => [],
-      bullets: () => []
+      bullets: () => [],
+      frontmatter: () => []
     });
   }
   named(text, line, uri) {

package/src/sources.js

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Sources.
+ *
+ * The paths passed on the command line. Each path names either one
+ * manifesto file or one directory. A directory expands into the default
+ * manifesto files it actually contains, so `dogent .` lints every known
+ * manifesto in the current folder.
+ */
+class Sources {
+  constructor(paths, defaults = ['AGENTS.md', 'CLAUDE.md', 'SKILL.md', 'SKILLS.md']) {
+    this.paths = paths;
+    this.defaults = defaults;
+  }
+  files() {
+    const found = [];
+    this.paths.forEach((entry) => {
+      if (fs.statSync(entry).isDirectory()) {
+        this.defaults.forEach((name) => {
+          const file = path.join(entry, name);
+          if (fs.existsSync(file)) {
+            found.push(file);
+          }
+        });
+      } else {
+        found.push(entry);
+      }
+    });
+    return found;
+  }
+}
+
+module.exports = Sources;

package/src/yaml.js

@@ -0,0 +1,37 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Yaml.
+ *
+ * A frontmatter block read as a flat YAML mapping. Splits itself line by
+ * line and emits one pair per top-level "key: value", carrying the key,
+ * the value, and the absolute line the key sits on. Nested mappings,
+ * blank lines, and comments hold no keys and yield nothing.
+ */
+class Yaml {
+  constructor(text, base) {
+    this.text = text;
+    this.base = base;
+  }
+  pairs() {
+    return this.text
+      .split('\n')
+      .map((line, index) => ({line, row: this.base + index}))
+      .filter((spot) => /^[^\s#][^:]*:/u.test(spot.line))
+      .map((spot) => {
+        const colon = spot.line.indexOf(':');
+        return {
+          key: spot.line.slice(0, colon).trim(),
+          value: spot.line.slice(colon + 1).trim(),
+          row: spot.row
+        };
+      });
+  }
+}
+
+module.exports = Yaml;