doctrina-cli 0.15.1 → 0.17.0

package/src/commands/ci.js

@@ -0,0 +1,182 @@
+// @ts-check
+import process from "node:process";
+import { flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+import { sequence } from "../lib/gates.js";
+
+// The CI surface, GENERATED from the gate declaration (audit finding F1).
+//
+// `action.yml` used to be a fourth hand-maintained list of gates, beside
+// `close`'s array and `doctor`'s rows. Nothing noticed when they diverged,
+// so a gate could be in the close and absent from CI for a release — which
+// is exactly what happened to the runtime checks.
+//
+// The action stays VERSIONED rather than generated on demand: a project that
+// writes `uses: GCarin1/Doctrina@v1` has no CLI to generate it with, and a
+// composite action that only exists after an npm install is not an action.
+// So this command emits it, and a drift test holds the committed file to
+// what this emits — the same pattern the AGENTS.md surface block uses.
+
+const TARGETS = ["github"];
+
+// Flags this command accepts. Declared HERE, with the command, so
+// adding a command never requires editing the entrypoint.
+export const flags = { boolean: ["json"], string: ["emit"] };
+
+export async function run(_positional, flags) {
+  const target = flagString(flags, "emit", "");
+  if (!target) {
+    console.error(c.red("error:") + " ci requires --emit <target>");
+    console.error(c.gray("hint: ") + `available targets: ${TARGETS.join(", ")}`);
+    return 2;
+  }
+  if (!TARGETS.includes(target)) {
+    console.error(c.red("error:") + ` unknown CI target "${target}"`);
+    const guess = suggest(target, TARGETS);
+    console.error(c.gray("hint: ") + (guess ? `did you mean --emit ${guess}?` : `available: ${TARGETS.join(", ")}`));
+    return 2;
+  }
+  process.stdout.write(emitGithub());
+  return 0;
+}
+
+/**
+ * The composite action, rendered from SEQUENCES.ci.
+ *
+ * Takes the sequence as a parameter so a test can prove the surface follows
+ * the DECLARATION rather than a copy of it: add a step to the array passed
+ * in, and it appears in the YAML with no edit here.
+ */
+export function emitGithub(steps = sequence("ci")) {
+  // Two renderings of the same list: the file header says what each gate
+  // checks, the action's description just names them.
+  const gateSummaries = steps.map((s) => s.summary ?? s.label.replace(/^doctrina /, ""));
+  const gateNames = steps.map((s) => s.short ?? s.label.replace(/^doctrina /, "")).join(", ");
+  const out = [];
+
+  out.push("# Reusable composite action: run the Doctrina gates in CI.");
+  out.push("#");
+  out.push("#   - uses: GCarin1/Doctrina@main        # or a released tag");
+  out.push("#     with:");
+  out.push("#       strict: \"true\"                   # coverage/trace as hard gates");
+  out.push("#");
+  out.push("# GENERATED by `doctrina ci --emit github` from SEQUENCES.ci in");
+  out.push("# packages/doctrina-cli/src/lib/gates.js — the one declaration `close` and");
+  out.push("# `doctor` also read. Edit the declaration, re-emit, and commit; a drift");
+  out.push("# test fails when this file and the declaration disagree.");
+  out.push("#");
+  for (const line of wrapComment(`The gates: ${gateSummaries.join(", ")}.`, 74)) out.push(`# ${line}`);
+  out.push("#");
+  out.push("# `run-prefix` exists so this repository can dogfood the action against its");
+  out.push("# own working tree instead of the published package.");
+  out.push("name: \"Doctrina gates\"");
+  out.push(`description: "Run the Doctrina gates (${gateNames}) against a project's .doctrina/ tree."`);
+  out.push("branding:");
+  out.push("  icon: \"check-circle\"");
+  out.push("  color: \"purple\"");
+  out.push("");
+  out.push("inputs:");
+  out.push("  strict:");
+  out.push("    description: \"Run coverage and trace with --strict (fail on any gap). Set to 'false' for report-only.\"");
+  out.push("    required: false");
+  out.push("    default: \"true\"");
+  out.push("  version:");
+  out.push("    description: \"doctrina-cli version to run via npx (ignored when run-prefix is set).\"");
+  out.push("    required: false");
+  out.push("    default: \"latest\"");
+  out.push("  working-directory:");
+  out.push("    description: \"Directory holding the .doctrina/ tree.\"");
+  out.push("    required: false");
+  out.push("    default: \".\"");
+  out.push("  run-prefix:");
+  out.push("    description: \"Override the command used to invoke the CLI (e.g. 'node packages/doctrina-cli/src/index.js' for this repo's own CI).\"");
+  out.push("    required: false");
+  out.push("    default: \"\"");
+  out.push("");
+  out.push("runs:");
+  out.push("  using: \"composite\"");
+  out.push("  steps:");
+  out.push("    - name: Resolve CLI invocation");
+  out.push("      id: cli");
+  out.push("      shell: bash");
+  out.push("      working-directory: ${{ inputs.working-directory }}");
+  out.push("      run: |");
+  out.push("        PREFIX=\"${{ inputs.run-prefix }}\"");
+  out.push("        if [ -z \"$PREFIX\" ]; then PREFIX=\"npx --yes doctrina-cli@${{ inputs.version }}\"; fi");
+  out.push("        echo \"prefix=$PREFIX\" >> \"$GITHUB_OUTPUT\"");
+
+  const prefix = "${{ steps.cli.outputs.prefix }}";
+  for (const step of steps) {
+    out.push("");
+    if (step.why) {
+      for (const line of step.why.split("\n")) out.push(`    # ${line}`.trimEnd());
+    }
+    out.push(`    - name: ${step.label}`);
+    out.push("      shell: bash");
+    out.push("      working-directory: ${{ inputs.working-directory }}");
+
+    const command = `${prefix} ${(step.argv ?? []).join(" ")}`.trim();
+    if (step.script) {
+      out.push("      run: |");
+      for (const line of step.script.replaceAll("{{PREFIX}}", prefix).split("\n")) {
+        out.push(`        ${line}`.trimEnd());
+      }
+    } else if (step.strict) {
+      // The one shape the declaration cannot flatten to a single line: the
+      // action's `strict` input decides whether the gate fails on a gap or
+      // only reports it, and an adopting project in its backfill phase needs
+      // the report-only half.
+      out.push("      run: |");
+      out.push("        if [ \"${{ inputs.strict }}\" = \"true\" ]; then");
+      out.push(`          ${command} --strict`);
+      out.push("        else");
+      out.push(`          ${command}`);
+      out.push("        fi");
+    } else {
+      out.push(`      run: ${command}`);
+    }
+  }
+  out.push("");
+  return out.join("\n");
+}
+
+// Wrap prose to a column so the emitted comments read like hand-written ones
+// rather than one very long line the reader has to scroll.
+function wrapComment(text, width) {
+  const out = [];
+  let line = "";
+  for (const word of text.split(/\s+/)) {
+    if (line && (line + " " + word).length > width) {
+      out.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) out.push(line);
+  return out;
+}
+
+export const help = `
+Usage: doctrina ci --emit <target>
+
+Emit the CI pipeline for the declared gate sequence, on stdout.
+
+The gates a pipeline runs are declared once, in SEQUENCES.ci
+(packages/doctrina-cli/src/lib/gates.js) — the same declaration \`close\`
+executes and \`doctor\` reports. This command renders that declaration as CI
+configuration, so the pipeline cannot fall behind the sequence the way a
+hand-maintained YAML file did.
+
+Targets:
+  github    A composite GitHub Action (the repository's own action.yml).
+
+The action stays versioned in the repository: a project that writes
+\`uses: <owner>/<repo>@v1\` has no CLI to generate it with. Re-emit after
+changing the declaration and commit the result; the drift test compares the
+committed file against this output.
+
+Read-only — it writes nothing, so redirect it yourself:
+  doctrina ci --emit github > action.yml
+`;

package/src/commands/clarify.js

@@ -5,7 +5,9 @@ import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { detectLanguage } from "../lib/lexicon.js";
+import { loadConfig } from "../lib/config.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Two lexicons, one linter (0.11.0 field review item 3: an English-only
 // clarify is permanently red on a PT-BR project — "some" is the verb *sumir*,
@@ -26,7 +28,23 @@ const RULES_EN = [
   },
   {
     name: "vague",
-    re: /\b(many|few|some|several)\b(?!\s+\d)/gi,
+    // Two exclusions, both structural rather than a vocabulary loosening.
+    // The lookahead was already here: `many 5` quantifies. The lookbehind is
+    // change 0079: `how many` is INTERROGATIVE, and a requirement that says
+    // "shall report how many contracts declared no rows" names exactly the
+    // number the command must print — the opposite of vague. Five of this
+    // repository's seventeen smells were that phrase, and the noise is what
+    // hid the one real finding among them ("name some of them", which said
+    // nothing about how many). A gate that cries wolf teaches people to
+    // ignore it.
+    //
+    // The quality adjectives sit here for the same reason the quantifiers do:
+    // "robust" names no threshold, so it cannot be met or missed. They were
+    // in the Portuguese lexicon and nowhere in this one, so the SAME sentence
+    // translated came back with three smells in one language and none in the
+    // other — and this project keeps its own pages in both. A smell test that
+    // answers differently per language is not testing the writing.
+    re: /(?<!\bhow\s+)\b(many|few|some|several|adequate|robust|scalable)\b(?!\s+\d)/gi,
     hint: "quantify (use a number or a precise scope)",
   },
   {
@@ -36,6 +54,10 @@ const RULES_EN = [
   },
 ];
 
+// How much of the previous line a rule may look back into. Long enough for
+// a wrapped two-word phrase, short enough that the probe stays cheap.
+const LOOKBEHIND_TAIL = 40;
+
 const RULES_PT = [
   {
     name: "weasel",
@@ -59,30 +81,34 @@ const RULES_PT = [
 // Language for a file: the project-declared `.doctrina/config.json`
 // ("language": "pt-BR" / "pt" / "en") wins; otherwise a deterministic
 // stopword count over the file text decides. Never semantic (ADR 0005).
-const PT_STOPWORDS = /\b(que|n[aã]o|para|uma|como|mais|ser|quando|est[aá]|s[aã]o|pela|pelo|dos|das|ou seja|deve)\b/gi;
-const EN_STOPWORDS = /\b(the|and|that|with|shall|when|this|from|are|not|for|must)\b/gi;
 
 function projectLanguage(projectRoot) {
-  const cfgPath = path.join(projectRoot, ".doctrina", "config.json");
-  if (isFile(cfgPath)) {
-    try {
-      const lang = String(JSON.parse(read(cfgPath))?.language ?? "").toLowerCase();
-      if (lang.startsWith("pt")) return "pt";
-      if (lang.startsWith("en")) return "en";
-    } catch { /* fall through to detection */ }
-  }
-  return null;
+  // One configuration reader (lib/config.js, change 0047): the key still
+  // lives in .doctrina/config.json, but `doctor` can now show what it
+  // resolved to, which is what a pt-BR project sitting red needed.
+  return loadConfig(projectRoot).language;
 }
 
+// Which lexicon a document is written in — the shared detector (change
+// 0040), so `clarify` and any future consumer count the same grammar words.
 function detectLang(text) {
-  const pt = (text.match(PT_STOPWORDS) ?? []).length;
-  const en = (text.match(EN_STOPWORDS) ?? []).length;
-  return pt > en ? "pt" : "en";
+  return detectLanguage(text);
 }
 
 function rulesFor(projectRoot, text, forcedLang = null) {
-  const lang = forcedLang ?? projectLanguage(projectRoot) ?? detectLang(text);
-  return lang === "pt" ? RULES_PT : RULES_EN;
+  const lang = forcedLang ?? projectLanguage(projectRoot);
+  if (lang) return lang === "pt" ? RULES_PT : RULES_EN;
+  // Detected per file, the document is scanned with BOTH lexicons (change
+  // 0107). A bilingual spec — Portuguese purpose, English EARS, or the
+  // reverse — detected as one language hid every smell written in the
+  // other: `clarify --all` found nothing where `--lang pt` found two. The
+  // two vocabularies do not overlap, so a smell in either is a smell; the
+  // detected language only decides which hint text the reader gets first.
+  const detected = detectLang(text);
+  const [first, second] = detected === "pt" ? [RULES_PT, RULES_EN] : [RULES_EN, RULES_PT];
+  // The `placeholder` rule is language-neutral and lives in both lists:
+  // one copy, or TBD is reported twice.
+  return [...first, ...second.filter((r) => r.name !== "placeholder")];
 }
 
 // --lang pt|en wins over the project config and the per-file heuristic
@@ -117,8 +143,15 @@ export async function run(positional, flags) {
   }
   const fullPath = path.resolve(projectRoot, target);
   if (!isFile(fullPath)) {
+    // USAGE, not GATE (third audit, finding 9). A path that does not exist
+    // is a wrong invocation: retrying it unchanged never succeeds, and an
+    // agent branching on the exit code reads 1 as "the work is not ready"
+    // and iterates forever (ADR 0018). Every sibling that takes a path —
+    // `intake --file`, `init --intake-file`, `templates check --path` —
+    // already exits 2 here; `clarify` was the straggler.
     console.error(c.red("error:") + ` file not found: ${target}`);
-    return 1;
+    console.error(c.gray("hint: ") + "pass a path to an existing Markdown file, or `--all` for the tree");
+    return EXIT.USAGE;
   }
 
   console.log(`clarify ${relPath(projectRoot, fullPath)}`);
@@ -208,11 +241,22 @@ function scanFile(fullPath, projectRoot = process.cwd(), lang = null) {
       cursor = lineEnd + 1;
       continue;
     }
+    // A rule reads the previous line as CONTEXT, never as content: a match
+    // is only reported when it starts inside this line. Prose wraps, and
+    // "report per spec how / many criteria..." split the interrogative
+    // across a line break — which a line-at-a-time scanner cannot see, so
+    // the phrase came back as a smell on one line of the same document and
+    // not on the next (change 0079). The prefix is trimmed to the tail of
+    // the previous line: enough for a lookbehind, cheap on every line.
+    const prev = i > 0 ? lines[i - 1].slice(-LOOKBEHIND_TAIL) : "";
+    const probe = prev === "" ? line : `${prev}\n${line}`;
+    const offset = probe.length - line.length;
     for (const rule of rules) {
       rule.re.lastIndex = 0;
       let m;
-      while ((m = rule.re.exec(line))) {
-        const absoluteStart = lineStart + m.index;
+      while ((m = rule.re.exec(probe))) {
+        if (m.index < offset) continue;   // the match belongs to the previous line
+        const absoluteStart = lineStart + m.index - offset;
         if (isInSkippedRange(absoluteStart, skippedRanges)) continue;
         smells.push({
           line: i + 1,