@yegor256/dogent 0.6.1 → 0.6.2

package/README.md

@@ -90,6 +90,9 @@ It sends the manifesto together with one instruction per rule,
   then prints any violation the model reports for ambiguity,
   weak phrasing, and instructions that only pretend to be commands.
 The model defaults to `gpt-4o-mini`; override it with `OPENAI_MODEL`.
+After the report, `dogent` prints a one-line usage summary to standard error,
+  naming the model, the tokens sent and received, and an estimated cost,
+  for example `OpenAI: gpt-4o-mini, 1234 sent, 567 received, ~$0.0005`.
 
 ```bash
 export OPENAI_API_KEY=...

package/package.json

@@ -40,5 +40,8 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.6.1"
+  "version": "0.6.2",
+  "dependencies": {
+    "minimist": "^1.2.8"
+  }
 }

package/src/args.js

@@ -5,32 +5,35 @@
 
 'use strict';
 
+const minimist = require('minimist');
+
 /**
  * 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.
+ * The command-line arguments handed to dogent. It leans on minimist to split
+ * 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. Everything
+ * after a `--` separator counts as a path, never as an option.
  */
 class Args {
-  constructor(argv, flags = ['--sarif', '--offline']) {
-    this.argv = argv;
+  constructor(argv, flags = ['sarif', 'offline']) {
     this.flags = flags;
+    this.parsed = minimist(argv, {boolean: flags, '--': true});
   }
   sarif() {
-    return this.argv.includes('--sarif');
+    return this.parsed.sarif === true;
   }
   offline() {
-    return this.argv.includes('--offline');
+    return this.parsed.offline === true;
   }
   paths() {
-    return this.argv.filter((arg) => !arg.startsWith('-'));
+    return this.parsed._.concat(this.parsed['--']).map(String);
   }
   unknown() {
-    return this.argv.filter(
-      (arg) => arg.startsWith('-') && !this.flags.includes(arg)
-    );
+    return Object.keys(this.parsed)
+      .filter((key) => key !== '_' && key !== '--' && !this.flags.includes(key))
+      .map((key) => `${key.length === 1 ? '-' : '--'}${key}`);
   }
 }
 

package/src/dogent.js

@@ -13,6 +13,7 @@ const Report = require('./report');
 const Sources = require('./sources');
 const Openai = require('./openai');
 const Oracle = require('./oracle');
+const Usage = require('./usage');
 const rules = require('./rules');
 
 const args = new Args(process.argv.slice(2));
@@ -41,27 +42,43 @@ documents.forEach((document) => {
   });
 });
 const key = process.env.OPENAI_API_KEY;
+const audit = async (docs) => {
+  const oracle = new Oracle(
+    rules(),
+    new Openai(
+      key,
+      process.env.OPENAI_MODEL || 'gpt-4o-mini',
+      (url, options) => globalThis.fetch(url, options)
+    )
+  );
+  const replies = await Promise.all(docs.map((doc) => oracle.violations(doc)));
+  return replies.reduce(
+    (acc, reply) => ({
+      extra: acc.extra.concat(reply.found),
+      usage: acc.usage.plus(reply.usage)
+    }),
+    {extra: [], usage: new Usage('', 0, 0)}
+  );
+};
+const finish = (usage) => {
+  const report = new Report('dogent', found);
+  process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
+  if (usage !== null) {
+    process.stderr.write(`${usage.text()}\n`);
+  }
+  process.exit(report.count() > 0 ? 1 : 0);
+};
 (async () => {
+  let usage = null;
   if (found.length === 0 && key && !args.offline()) {
     try {
-      const oracle = new Oracle(
-        rules(),
-        new Openai(
-          key,
-          process.env.OPENAI_MODEL || 'gpt-4o-mini',
-          (url, options) => globalThis.fetch(url, options)
-        )
-      );
-      const extra = await Promise.all(
-        documents.map((document) => oracle.violations(document))
-      );
-      extra.forEach((bag) => bag.forEach((violation) => found.push(violation)));
+      const result = await audit(documents);
+      result.extra.forEach((violation) => found.push(violation));
+      ({usage} = result);
     } catch (error) {
       process.stderr.write(`AI verification failed: ${error.message}\n`);
       process.exit(2);
     }
   }
-  const report = new Report('dogent', found);
-  process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
-  process.exit(report.count() > 0 ? 1 : 0);
+  finish(usage);
 })();

package/src/openai.js

@@ -5,11 +5,14 @@
 
 'use strict';
 
+const Usage = require('./usage');
+
 /**
  * Openai.
  *
  * A thin adapter over the OpenAI chat-completions endpoint. Sends one
- * prompt, demands a JSON object back, and returns the assistant text.
+ * prompt, demands a JSON object back, and returns the assistant text
+ * paired with a Usage tally of the model and the tokens it consumed.
  * The transport is injected so the class runs in tests without a socket.
  */
 class Openai {
@@ -38,7 +41,16 @@ class Openai {
     if (!response.ok) {
       throw new Error(`OpenAI request rejected with status ${response.status}`);
     }
-    return (await response.json()).choices[0].message.content;
+    const body = await response.json();
+    const usage = body.usage || {};
+    return {
+      content: body.choices[0].message.content,
+      usage: new Usage(
+        this.model,
+        usage.prompt_tokens || 0,
+        usage.completion_tokens || 0
+      )
+    };
   }
 }
 

package/src/oracle.js

@@ -13,7 +13,8 @@ const Answer = require('./answer');
  *
  * The AI second opinion. Wraps the rules and a chat endpoint, builds one
  * prompt from a document, asks the endpoint, and parses the reply into
- * violations. Mirrors a rule, but consults a model instead of guessing.
+ * violations paired with the token usage the model reported. Mirrors a
+ * rule, but consults a model instead of guessing.
  */
 class Oracle {
   constructor(rules, chat) {
@@ -21,9 +22,11 @@ class Oracle {
     this.chat = chat;
   }
   async violations(document) {
-    return new Answer(
-      await this.chat.answer(new Prompt(this.rules, document).text())
-    ).violations();
+    const reply = await this.chat.answer(new Prompt(this.rules, document).text());
+    return {
+      found: new Answer(reply.content).violations(),
+      usage: reply.usage
+    };
   }
 }
 

package/src/rules/line-length.js

@@ -13,6 +13,9 @@ const Region = require('../region');
  *
  * Demands that every instruction and every heading stay within a
  * maximum width. Code snippets are exempt, since code is not prose.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
  */
 class LineLength {
   constructor(max) {
@@ -20,7 +23,7 @@ class LineLength {
     this.max = max;
   }
   prompt() {
-    return `${this.id}: flag any instruction too wordy to grasp in a single read`;
+    return '';
   }
   violations(document) {
     const uri = document.uri();

package/src/usage.js

@@ -0,0 +1,52 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Price table.
+ *
+ * United States dollars per one million tokens, sent and received, for
+ * every model dogent knows. An unknown model falls back to zero, so the
+ * summary still prints token counts without inventing a price.
+ */
+const PRICES = {
+  'gpt-4o-mini': {input: 0.15, output: 0.6},
+  'gpt-4o': {input: 2.5, output: 10},
+  'gpt-4.1-nano': {input: 0.1, output: 0.4},
+  'gpt-4.1-mini': {input: 0.4, output: 1.6},
+  'gpt-4.1': {input: 2, output: 8}
+};
+
+/**
+ * Usage.
+ *
+ * One immutable tally of an OpenAI exchange: the model, the tokens sent,
+ * and the tokens received. Sums itself with another tally and renders a
+ * single human summary line, complete with an estimated dollar cost.
+ */
+class Usage {
+  constructor(model, sent, received) {
+    this.model = model;
+    this.sent = sent;
+    this.received = received;
+  }
+  plus(other) {
+    return new Usage(
+      this.model || other.model,
+      this.sent + other.sent,
+      this.received + other.received
+    );
+  }
+  cost() {
+    const price = PRICES[this.model] || {input: 0, output: 0};
+    return this.sent / 1e6 * price.input + this.received / 1e6 * price.output;
+  }
+  text() {
+    return `OpenAI: ${this.model}, ${this.sent} sent, ${this.received} received, ~$${this.cost().toFixed(4)}`;
+  }
+}
+
+module.exports = Usage;