@yegor256/dogent 0.5.1 → 0.6.1

package/README.md

@@ -29,7 +29,7 @@ In short: `agnix` lints the harness, `dogent` lints the prompt.
 Run it on any manifesto file, no installation required:
 
 ```bash
-npx @yegor256/dogent@0.5.0 CLAUDE.md
+npx @yegor256/dogent@0.6.0 CLAUDE.md
 ```
 
 Lint several files at once:
@@ -96,6 +96,15 @@ export OPENAI_API_KEY=...
 npx @yegor256/dogent CLAUDE.md
 ```
 
+Pass `--offline` to keep `dogent` away from the LLM,
+  even when `OPENAI_API_KEY` is present in the environment:
+
+```bash
+npx @yegor256/dogent --offline CLAUDE.md
+```
+
+Pass `--sarif` to print the report as SARIF instead of plain text.
+
 ## GitHub Actions
 
 Because `dogent` runs through `npx`, no extra action is needed.
@@ -141,7 +150,7 @@ Reference `dogent` as a remote hook in `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yegor256/dogent
-    rev: 0.5.0
+    rev: 0.6.0
     hooks:
       - id: dogent
 ```

package/package.json

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

package/src/args.js

@@ -0,0 +1,37 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Args.
+ *
+ * The command-line arguments handed to dogent. It splits the raw argv into
+ * recognized options and the manifesto paths that remain. The `--sarif`
+ * flag switches the report to SARIF, while `--offline` forbids any talk to
+ * the LLM even when a token sits in the environment.
+ */
+class Args {
+  constructor(argv, flags = ['--sarif', '--offline']) {
+    this.argv = argv;
+    this.flags = flags;
+  }
+  sarif() {
+    return this.argv.includes('--sarif');
+  }
+  offline() {
+    return this.argv.includes('--offline');
+  }
+  paths() {
+    return this.argv.filter((arg) => !arg.startsWith('-'));
+  }
+  unknown() {
+    return this.argv.filter(
+      (arg) => arg.startsWith('-') && !this.flags.includes(arg)
+    );
+  }
+}
+
+module.exports = Args;

package/src/dogent.js

@@ -7,6 +7,7 @@
 'use strict';
 
 const fs = require('fs');
+const Args = require('./args');
 const Markdown = require('./markdown');
 const Report = require('./report');
 const Sources = require('./sources');
@@ -14,11 +15,17 @@ const Openai = require('./openai');
 const Oracle = require('./oracle');
 const rules = require('./rules');
 
-const argv = process.argv.slice(2);
-const sarif = argv.indexOf('--sarif') !== -1;
-const paths = argv.filter((arg) => arg !== '--sarif');
+const args = new Args(process.argv.slice(2));
+const sarif = args.sarif();
+const unknown = args.unknown();
+if (unknown.length > 0) {
+  process.stderr.write(`Unknown option: ${unknown[0]}\n`);
+  process.stderr.write('Usage: dogent [--sarif] [--offline] <file.md|dir>...\n');
+  process.exit(2);
+}
+const paths = args.paths();
 if (paths.length === 0) {
-  process.stderr.write('Usage: dogent [--sarif] <file.md|dir>...\n');
+  process.stderr.write('Usage: dogent [--sarif] [--offline] <file.md|dir>...\n');
   process.exit(2);
 }
 const scanned = new Sources(paths).files();
@@ -35,7 +42,7 @@ documents.forEach((document) => {
 });
 const key = process.env.OPENAI_API_KEY;
 (async () => {
-  if (found.length === 0 && key) {
+  if (found.length === 0 && key && !args.offline()) {
     try {
       const oracle = new Oracle(
         rules(),

package/src/rules/dead-import.js

@@ -0,0 +1,66 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+const imports = (line) => {
+  const found = [];
+  const pattern = /(?<lead>^|\s)@(?<file>\S+)/gu;
+  let match = pattern.exec(line);
+  while (match !== null) {
+    found.push({
+      file: match.groups.file.replace(/[.,:;!?]+$/u, ''),
+      column: match.index + match.groups.lead.length + 1
+    });
+    match = pattern.exec(line);
+  }
+  return found;
+};
+
+/**
+ * DeadImport.
+ *
+ * Flags `@path/to/file` imports that point to no file on disk.
+ *
+ * @todo #18:45min Detect circular import chains and depth above five
+ *  levels so deeply nested manifesto imports fail with a clear violation,
+ *  as requested in issue #18.
+ */
+class DeadImport {
+  constructor() {
+    this.id = 'dead-import';
+  }
+  prompt() {
+    return `${this.id}: flag any @path/to/file import that points to no file on disk`;
+  }
+  violations(document) {
+    return document.walk({
+      header: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => [],
+      prose: (line, row) => this.missing(document.uri(), line, row)
+    });
+  }
+  missing(uri, line, row) {
+    const base = path.dirname(uri);
+    return imports(line)
+      .filter((item) => !fs.existsSync(path.resolve(base, item.file)))
+      .map((item) => new Violation(
+        this.id,
+        'error',
+        `@-import target not found: ${item.file}`,
+        new Region(uri, row, item.column)
+      ));
+  }
+}
+
+module.exports = DeadImport;

package/src/rules/empty.js

@@ -15,13 +15,16 @@ const Region = require('../region');
  * A heading is empty when it is immediately followed by another
  * heading or by end-of-file — no prose, bullets, or snippet sits
  * between them.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
  */
 class Empty {
   constructor() {
     this.id = 'empty';
   }
   prompt() {
-    return `${this.id}: flag any section heading that carries no instructions beneath it`;
+    return '';
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/index.js

@@ -14,6 +14,8 @@ const NoArticles = require('./no-articles');
 const Command = require('./command');
 const Punctuation = require('./punctuation');
 const Frontmatter = require('./frontmatter');
+const DeadImport = require('./dead-import');
+const Redundant = require('./redundant');
 
 module.exports = () => [
   new Grouped(),
@@ -24,6 +26,8 @@ module.exports = () => [
   new NoArticles(),
   new Command(),
   new Punctuation(),
+  new DeadImport(),
+  new Redundant(),
   new Frontmatter(
     'SKILL.md',
     ['name', 'description'],

package/src/rules/redundant.js

@@ -0,0 +1,92 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+const PHRASES = [
+  'be helpful',
+  'be helpful and accurate',
+  'be accurate',
+  'be concise',
+  'be clear',
+  'be polite',
+  'be professional',
+  'write clean code',
+  'write good code',
+  'write readable code',
+  'write maintainable code',
+  'follow best practices',
+  'follow industry best practices',
+  'use best practices',
+  'apply best practices',
+  'use meaningful variable names',
+  'use descriptive variable names',
+  'use good variable names',
+  'handle errors properly',
+  'handle errors gracefully',
+  'handle exceptions properly',
+  'avoid bugs',
+  'avoid mistakes',
+  'think step by step',
+  'do your best',
+  'try your best',
+  'pay attention to detail'
+];
+
+/**
+ * Redundant.
+ *
+ * Flags a line that restates default model behavior, like
+ * "Be helpful and accurate" or "Write clean code". Such filler
+ * burns the context budget and drowns the project-specific
+ * guidance the manifesto exists to carry.
+ *
+ * @todo #15:60min Promote the standalone heuristic into a
+ *  proper AI-oracle check when `OPENAI_API_KEY` is present, so
+ *  redundancy detection covers paraphrases beyond the curated
+ *  blacklist below. The hybrid pattern from `src/rules/command.js`
+ *  is the model: keep the deterministic check as the default,
+ *  let the oracle catch the rest.
+ */
+class Redundant {
+  constructor(phrases = PHRASES) {
+    this.id = 'redundant';
+    this.phrases = phrases;
+  }
+  prompt() {
+    return `${this.id}: flag any line that restates default agent behavior already known to the model, not a project-specific instruction`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.judge(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  judge(text, line, uri) {
+    const clean = text
+      .replace(/^\s*(?:[-*+]|\d+\.)\s+/u, '')
+      .replace(/[.!?]+\s*$/u, '')
+      .trim()
+      .toLowerCase();
+    if (!this.phrases.includes(clean)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      'generic instruction, model already knows this',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Redundant;