@jpeakai/prose-gates 0.1.2 → 0.3.0

package/src/cli.ts

@@ -3,13 +3,20 @@
 
 import { readFile, writeFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
-import { checkModel, DEFAULT_MAX_WORDS } from "./check.ts";
-import { fixMarkdown } from "./fix/engine.ts";
+import { checkModel } from "./check.ts";
+import { FlagError, ProseGatesError, UsageError } from "./errors.ts";
+import { fixMarkdownReport } from "./fix/engine.ts";
 import { buildDocModel } from "./model.ts";
+import type { PluginFailure } from "./plugins/index.ts";
+import { setUp } from "./project.ts";
 import { RULES } from "./rules/index.ts";
+import type { LoadedSource, Registry } from "./rules/registry.ts";
 import { CATEGORIES } from "./rules/types.ts";
 
-const USAGE = `usage: prose-gates <file.md> [...more] [--fix] [--json] [--max-words N]
+const USAGE = `usage: prose-gates <file.md> [...more] [--fix] [--json] [--max-words N] [--config FILE]
+                   [--no-plugins | --lenient-plugins]
+       prose-gates --list-rules
+       prose-gates --validate-plugins [--json] [--config FILE]
 
 Deterministic prose gates (* = autofixable):
 ${CATEGORIES.map((c) =>
@@ -25,58 +32,250 @@ markdown templates and their body is audited recursively (check-only).
 
 --fix applies every fix it can prove safe, then reports what remains.
 A fixer that is unsure leaves the text alone and the finding stays.
-Exits 1 when findings remain, 2 on usage error.`;
+--config FILE reads that config instead of prose-gates.config.json or .mjs at the project root.
+Plugins load on their own from .prose-gates/rules and from dependencies named prose-gates-plugin-*.
+--no-plugins runs the built-in rules only, for a baseline or a repo you do not trust.
+--lenient-plugins skips a plugin that fails to load and says so, instead of stopping the run.
+--validate-plugins loads and checks every plugin, reports every failure, and runs no check or fix.
+--list-rules prints every active rule by category, including plugin rules, and where each plugin came from.
+Exits 1 when findings remain or a plugin fails to load, 2 on usage error.`;
 
-export const main = async (argv: string[] = process.argv.slice(2)): Promise<number> => {
-  let values: { fix?: boolean; json?: boolean; help?: boolean; "max-words"?: string };
-  let positionals: string[];
+interface Parsed {
+  values: {
+    fix?: boolean;
+    json?: boolean;
+    help?: boolean;
+    "max-words"?: string;
+    config?: string;
+    "no-plugins"?: boolean;
+    "lenient-plugins"?: boolean;
+    "validate-plugins"?: boolean;
+    "list-rules"?: boolean;
+  };
+  positionals: string[];
+}
+
+const parse = (argv: string[]): Parsed =>
+  parseArgs({
+    args: argv,
+    options: {
+      fix: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      "max-words": { type: "string" },
+      config: { type: "string" },
+      "no-plugins": { type: "boolean", default: false },
+      "lenient-plugins": { type: "boolean", default: false },
+      "validate-plugins": { type: "boolean", default: false },
+      "list-rules": { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+
+const plural = (n: number, word: string): string => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+const namesOf = (sources: LoadedSource[]): string =>
+  sources.map((s) => `${s.namespace} (${plural(s.rules.length, "rule")})`).join(", ");
+
+// The one line every run prints about third-party code, because loading it is
+// automatic. It says what ran, or what was skipped, and prints nothing when the
+// project has no plugins.
+export const loadedLine = (sources: LoadedSource[], skipped: string[]): string | null => {
+  if (skipped.length > 0) return `prose-gates: plugins off; skipped ${skipped.join(", ")}`;
+  if (sources.length === 0) return null;
+  return `prose-gates: loaded ${namesOf(sources)}`;
+};
+
+// One line for each plugin a lenient run left out, with the named reason, and
+// one for each config setting dropped because its plugin did not load.
+export const skippedLines = (failures: PluginFailure[], ignored: string[]): string[] => [
+  ...failures.map((f) => `prose-gates: skipped plugin ${f.source} [${f.error.code}]: ${reasonOf(f)}`),
+  ...ignored.map((id) => `prose-gates: ignored config setting for ${id}, whose plugin did not load`),
+];
+
+// The reason without the "plugin <source>:" the error message begins with.
+const reasonOf = (f: PluginFailure): string => f.error.message.replace(`plugin ${f.source}: `, "");
+
+// A plugin failure as the JSON output and --validate-plugins report it.
+const failureRecord = (f: PluginFailure) => ({
+  source: f.source,
+  kind: f.kind,
+  code: f.error.code,
+  message: reasonOf(f),
+});
+
+// Every active rule under its category, then where each plugin came from.
+// Built-in categories come first, in their fixed order, then plugin ones.
+export const listRules = (registry: Registry): string => {
+  const lines: string[] = [];
+  for (const [category, description] of registry.categories) {
+    const rules = registry.rules.filter((r) => r.category === category);
+    if (rules.length === 0) continue;
+    lines.push(`${category}: ${description}`);
+    for (const r of rules) lines.push(`  ${r.id}${r.fix ? "*" : " "} ${r.summary}`);
+  }
+  if (registry.sources.length > 0) {
+    lines.push("", "plugins:");
+    for (const s of registry.sources) lines.push(`  ${s.namespace} (${s.kind}) ${s.spec}`);
+  }
+  return lines.join("\n");
+};
+
+// The result of --validate-plugins: what loaded, every failure, and the exit
+// code. Nothing here runs a check or a fix.
+const validate = (
+  registry: Registry,
+  failures: PluginFailure[],
+  json: boolean,
+): { code: number; stdout: string | null; stderr: string[] } => {
+  const sources = registry.sources.map((s) => ({ ...s }));
+  const failed = failures.map(failureRecord);
+  const code = failures.length > 0 ? 1 : 0;
+  if (json)
+    return {
+      code,
+      stdout: JSON.stringify({ valid: code === 0, plugins: sources, failures: failed }, null, 2),
+      stderr: [],
+    };
+  if (failures.length > 0) {
+    const total = failures.length + sources.length;
+    return {
+      code,
+      stdout: null,
+      stderr: [
+        `prose-gates: plugin validation failed, ${failures.length} of ${plural(total, "source")}`,
+        ...failed.map((f) => `  [${f.code}] ${f.source}: ${f.message}`),
+      ],
+    };
+  }
+  const line =
+    sources.length === 0 ? "prose-gates: no plugins found" : `prose-gates: plugins valid: ${namesOf(registry.sources)}`;
+  return { code, stdout: line, stderr: [] };
+};
+
+// The flags, or a usage error naming what parseArgs rejected.
+const parseFlags = (argv: string[]): Parsed => {
   try {
-    ({ values, positionals } = parseArgs({
-      args: argv,
-      options: {
-        fix: { type: "boolean", default: false },
-        json: { type: "boolean", default: false },
-        help: { type: "boolean", short: "h", default: false },
-        "max-words": { type: "string" },
-      },
-      allowPositionals: true,
-      strict: true,
-    }));
+    return parse(argv);
   } catch (err) {
-    console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
-    console.error(USAGE);
-    return 2;
+    throw new FlagError("argv", err instanceof Error ? err.message : String(err));
+  }
+};
+
+// Absent means the rule's own option, then the default. Present is a flag
+// that wins for this run.
+const maxWordsOf = (values: Parsed["values"]): number | undefined => {
+  const maxWords = values["max-words"] === undefined ? undefined : Number(values["max-words"]);
+  if (maxWords !== undefined && (Number.isNaN(maxWords) || maxWords < 1)) {
+    throw new FlagError("--max-words", `--max-words must be a number of at least 1, not "${values["max-words"]}"`);
   }
+  return maxWords;
+};
+
+// The flag combinations that contradict each other, or leave nothing to do.
+const checkFlags = ({ values, positionals }: Parsed): void => {
+  const listing = values["list-rules"];
+  const validating = values["validate-plugins"];
+  if (values["no-plugins"] && values["lenient-plugins"]) {
+    throw new FlagError("--lenient-plugins", "--no-plugins and --lenient-plugins contradict each other");
+  }
+  if (validating && (values["no-plugins"] || values.fix || listing)) {
+    throw new FlagError("--validate-plugins", "--validate-plugins takes no --no-plugins, --fix or --list-rules");
+  }
+  if (validating && positionals.length > 0) {
+    throw new FlagError("files", "--validate-plugins runs no check, so it takes no files");
+  }
+  if (positionals.length === 0 && !listing && !validating) throw new FlagError("files", "no files given");
+};
+
+// Prints the --validate-plugins result and returns its exit code.
+const printValidation = (registry: Registry, failures: PluginFailure[], json: boolean): number => {
+  const result = validate(registry, failures, json);
+  for (const line of result.stderr) console.error(line);
+  if (result.stdout) console.log(result.stdout);
+  return result.code;
+};
+
+// One file's findings, fixed first when asked and written back only if changed.
+const checkFile = async (file: string, fix: boolean, maxWords: number | undefined, registry: Registry) => {
+  let src = await readFile(file, "utf8");
+  if (fix) {
+    const fixed = (await fixMarkdownReport(src, registry)).output;
+    if (fixed !== src) {
+      await writeFile(file, fixed);
+      src = fixed;
+    }
+  }
+  return await checkModel(buildDocModel(src, registry.concepts), file, maxWords, registry);
+};
+
+type Finding = Awaited<ReturnType<typeof checkFile>>[number];
+type SetUp = Awaited<ReturnType<typeof setUp>>;
+
+// The findings as JSON or one line each, then the exit code.
+const report = (all: Finding[], files: string[], setup: SetUp, json: boolean): number => {
+  if (json) {
+    const skippedPlugins = setup.failures.map(failureRecord);
+    console.log(
+      JSON.stringify({ findings: all, files: files.length, plugins: setup.registry.sources, skippedPlugins }, null, 2),
+    );
+  } else {
+    for (const f of all) console.log(`${f.file}:${f.line} ${f.rule} ${f.message}`);
+    console.log(`${all.length} finding(s) in ${files.length} file(s)`);
+  }
+  return all.length > 0 ? 1 : 0;
+};
+
+const run = async (argv: string[], cwd: string): Promise<number> => {
+  const parsed = parseFlags(argv);
+  const { values, positionals } = parsed;
   if (values.help) {
     console.log(USAGE);
     return 0;
   }
-  const maxWords = values["max-words"] === undefined ? DEFAULT_MAX_WORDS : Number(values["max-words"]);
-  if (positionals.length === 0 || Number.isNaN(maxWords) || maxWords < 1) {
-    console.error(USAGE);
-    return 2;
-  }
+  const maxWords = maxWordsOf(values);
+  checkFlags(parsed);
+  const validating = values["validate-plugins"];
+
+  const setup = await setUp({
+    cwd,
+    configPath: values.config,
+    noPlugins: values["no-plugins"],
+    lenient: values["lenient-plugins"],
+    collect: validating,
+  });
+  const { registry, skipped, failures } = setup;
+  if (validating) return printValidation(registry, failures, Boolean(values.json));
 
+  const note = loadedLine(registry.sources, skipped);
+  if (note) console.error(note);
+  for (const line of skippedLines(failures, registry.ignoredSettings)) console.error(line);
+  if (values["list-rules"]) {
+    console.log(listRules(registry));
+    return 0;
+  }
   const perFile = await Promise.all(
-    positionals.map(async (file) => {
-      let src = await readFile(file, "utf8");
-      if (values.fix) {
-        const fixed = fixMarkdown(src);
-        if (fixed !== src) {
-          await writeFile(file, fixed);
-          src = fixed;
-        }
-      }
-      return checkModel(buildDocModel(src), file, maxWords);
-    }),
+    positionals.map((file) => checkFile(file, Boolean(values.fix), maxWords, registry)),
   );
-  const all = perFile.flat();
+  return report(perFile.flat(), positionals, setup, Boolean(values.json));
+};
 
-  if (values.json) {
-    console.log(JSON.stringify({ findings: all, files: positionals.length }, null, 2));
-  } else {
-    for (const f of all) console.log(`${f.file}:${f.line} ${f.rule} ${f.message}`);
-    console.log(`${all.length} finding(s) in ${positionals.length} file(s)`);
+// The line printed for a failure: its stable code, then the reason.
+export const describeError = (err: unknown): string =>
+  err instanceof ProseGatesError
+    ? `error[${err.code}]: ${err.message}`
+    : `error: ${err instanceof Error ? err.message : String(err)}`;
+
+// A usage error prints its reason and the usage, and exits 2. Anything else is
+// a runtime failure and propagates to bin.ts, which exits 1.
+export const main = async (argv: string[] = process.argv.slice(2), cwd: string = process.cwd()): Promise<number> => {
+  try {
+    return await run(argv, cwd);
+  } catch (err) {
+    if (!(err instanceof UsageError)) throw err;
+    console.error(describeError(err));
+    console.error(USAGE);
+    return 2;
   }
-  return all.length > 0 ? 1 : 0;
 };

package/src/cohesion.ts

@@ -0,0 +1,70 @@
+// Lexical cohesion between the sentences of one paragraph: which sentences
+// talk about the same thing, and where the topic turns. It reads the language
+// model a paragraph exposes, so the words, tags and lemmas come from
+// src/language.ts. The scoring and the break plan are a guide, not a parse:
+// no JavaScript topic segmenter exists to use instead.
+
+import type { LanguageSentence } from "./language.ts";
+
+const shared = (a: ReadonlySet<string>, b: ReadonlySet<string>): number => [...a].filter((t) => b.has(t)).length;
+
+// How strongly the sentences either side of each gap hold together. Gap i
+// sits between sentence i and sentence i + 1, counted from zero here. A term
+// the two neighbours share counts double. A term shared by sentences two
+// apart across the gap counts once, so a sentence that strays for a moment
+// does not split a topic. A sentence that opens by referring back counts
+// double, and one that opens like its neighbour, in parallel, counts once.
+// Zero means nothing ties the two sides together: the topic turns.
+export const gapCohesion = (sentences: readonly LanguageSentence[]): number[] => {
+  const terms = sentences.map((s) => s.terms);
+  const openers = sentences.map((s) => s.opener);
+  const none: ReadonlySet<string> = new Set();
+  const at = (i: number): ReadonlySet<string> => terms[i] ?? none;
+  return sentences.slice(1).map((next, i) => {
+    const adjacent = shared(at(i), at(i + 1));
+    // A gap at either end has one pair two apart instead of two, so the pairs
+    // it has are scaled up. Otherwise an edge would always look weakest.
+    const pairs = [
+      i - 1 >= 0 ? shared(at(i - 1), at(i + 1)) : null,
+      i + 2 < terms.length ? shared(at(i), at(i + 2)) : null,
+    ];
+    const present = pairs.filter((p): p is number => p !== null);
+    const skips = present.length === 0 ? 0 : (2 * present.reduce((a, b) => a + b, 0)) / present.length;
+    const parallel = openers[i] !== null && openers[i] === openers[i + 1] ? 1 : 0;
+    return 2 * adjacent + skips + (next.refersBack ? 2 : 0) + parallel;
+  });
+};
+
+// Where to break a paragraph: after every sentence whose gap has no cohesion,
+// then inside any group still over the budget, at its weakest gap. A tie goes
+// to the gap nearest the middle of the group, so the halves come out even.
+// Breaks are sentence numbers counted from one: a break of 3 means a new
+// paragraph starts with sentence 4.
+export interface BreakPlan {
+  topics: number;
+  breaks: number[];
+}
+
+export const planBreaks = (cohesion: number[], maxSentences: number): BreakPlan => {
+  const count = cohesion.length + 1;
+  const topicBreaks = cohesion.flatMap((score, i) => (score === 0 ? [i + 1] : []));
+  const breaks = new Set(topicBreaks);
+  const split = (from: number, to: number): void => {
+    // The group holds sentences from + 1 through to.
+    if (to - from <= maxSentences) return;
+    let best = -1;
+    for (let at = from + 1; at < to; at++) {
+      const better =
+        best === -1 ||
+        (cohesion[at - 1] as number) < (cohesion[best - 1] as number) ||
+        (cohesion[at - 1] === cohesion[best - 1] && Math.abs(2 * at - from - to) < Math.abs(2 * best - from - to));
+      if (better) best = at;
+    }
+    breaks.add(best);
+    split(from, best);
+    split(best, to);
+  };
+  const edges = [0, ...topicBreaks, count];
+  for (let i = 0; i + 1 < edges.length; i++) split(edges[i] as number, edges[i + 1] as number);
+  return { topics: topicBreaks.length + 1, breaks: [...breaks].sort((a, b) => a - b) };
+};

package/src/concepts.ts

@@ -0,0 +1,209 @@
+// The concept model: a project's own vocabulary, read from the GLOSSARY.md or
+// CONCEPTS.md at its root. Each H2 heading is a concept, and each Mermaid
+// flowchart in the file relates them: a labelled edge is a relation, a dotted
+// one is a prohibition, and "is a kind of" makes one concept a kind of another.
+// The file is optional, but one that is there must parse, because a rule that
+// reads concepts would otherwise run against half a vocabulary.
+
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import nlp from "compromise";
+import type { Code, Heading, Node, Text } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { AmbiguousConceptsError, ConceptsFileError } from "./errors.ts";
+
+export const CONCEPT_FILES = ["GLOSSARY.md", "CONCEPTS.md"] as const;
+
+// The edge label that makes its source a kind of its target.
+export const KIND_OF = "is a kind of";
+
+// One concept. `kinds` is every concept it is a kind of, nearest first, so a
+// Local Rule that is a kind of Plugin has kinds ["Plugin"].
+export interface Concept {
+  name: string;
+  kinds: readonly string[];
+}
+
+// One edge of a diagram, by concept name. `verb` is the edge label, empty for
+// an unlabelled edge. `never` is true for a dotted edge: the source must never
+// do what the label says to the target.
+export interface ConceptRelation {
+  from: string;
+  verb: string;
+  to: string;
+  never: boolean;
+}
+
+export interface ConceptModel {
+  // The file it came from, relative to the project root. Null when there is none.
+  file: string | null;
+  concepts: readonly Concept[];
+  relations: readonly ConceptRelation[];
+}
+
+export const NO_CONCEPTS: ConceptModel = { file: null, concepts: [], relations: [] };
+
+// --- reading the file ------------------------------------------------------
+
+const textOf = (node: Node): string =>
+  node.type === "text" || node.type === "inlineCode"
+    ? (node as Text).value
+    : ((node as { children?: Node[] }).children ?? []).map(textOf).join("");
+
+const NODE = /^\s*([A-Za-z][\w-]*)\["([^"]+)"\]/;
+const EDGE = /^\s*([A-Za-z][\w-]*)\s+(?:(--|-\.)\s+(.+?)\s+(-->|\.->)|(-->|-\.->))\s+([A-Za-z][\w-]*)\s*$/;
+
+// One diagram's relations. Node ids are local to their diagram, so two
+// diagrams may reuse an id for different concepts.
+const relationsOf = (file: string, diagram: Code, names: ReadonlySet<string>): ConceptRelation[] => {
+  const label = new Map<string, string>();
+  const relations: ConceptRelation[] = [];
+  for (const line of diagram.value.split("\n")) {
+    const node = NODE.exec(line);
+    if (node) {
+      const [, id = "", name = ""] = node;
+      if (!names.has(name)) throw new ConceptsFileError(file, `diagram node "${name}" is not a term heading`);
+      label.set(id, name);
+      continue;
+    }
+    const edge = EDGE.exec(line);
+    if (!edge) continue;
+    const [, from = "", solidOrDotted, verb = "", , bare, to = ""] = edge;
+    const ends = [from, to].map((id) => {
+      const name = label.get(id);
+      if (!name) throw new ConceptsFileError(file, `edge "${line.trim()}" names "${id}", which no node declares`);
+      return name;
+    });
+    const never = solidOrDotted === "-." || bare === "-.->";
+    relations.push({ from: ends[0] as string, verb, to: ends[1] as string, never });
+  }
+  return relations;
+};
+
+// Every concept a concept is a kind of, nearest first. A cycle is an error,
+// because it leaves a concept a kind of itself.
+const kindsOf = (file: string, name: string, parents: ReadonlyMap<string, string[]>): string[] => {
+  const kinds: string[] = [];
+  const queue = [...(parents.get(name) ?? [])];
+  while (queue.length > 0) {
+    const next = queue.shift() as string;
+    if (next === name) throw new ConceptsFileError(file, `"${name}" is a kind of itself`);
+    if (kinds.includes(next)) continue;
+    kinds.push(next);
+    queue.push(...(parents.get(next) ?? []));
+  }
+  return kinds;
+};
+
+export const parseConcepts = (file: string, src: string): ConceptModel => {
+  const root = fromMarkdown(src);
+  const headings = root.children.filter((n): n is Heading => n.type === "heading" && n.depth === 2);
+  const names = headings.map((h) => textOf(h).trim());
+  if (names.length === 0) throw new ConceptsFileError(file, "it has no H2 headings, and each H2 is a term");
+  const repeated = names.find((n, i) => names.indexOf(n) !== i);
+  if (repeated) throw new ConceptsFileError(file, `the term "${repeated}" has two headings`);
+  const known = new Set(names);
+  const diagrams = root.children.filter((n): n is Code => n.type === "code" && n.lang === "mermaid");
+  const relations = diagrams.flatMap((d) => relationsOf(file, d, known));
+  const parents = new Map<string, string[]>();
+  for (const r of relations.filter((x) => x.verb === KIND_OF && !x.never)) {
+    parents.set(r.from, [...(parents.get(r.from) ?? []), r.to]);
+  }
+  return { file, concepts: names.map((name) => ({ name, kinds: kindsOf(file, name, parents) })), relations };
+};
+
+const exists = (path: string): Promise<boolean> =>
+  access(path).then(
+    () => true,
+    () => false,
+  );
+
+// The concept file at the root, or null. Two at once is ambiguous, so it is
+// an error rather than a pick.
+export const findConcepts = async (root: string): Promise<string | null> => {
+  const found: string[] = [];
+  for (const name of CONCEPT_FILES) if (await exists(join(root, name))) found.push(name);
+  if (found.length > 1) throw new AmbiguousConceptsError(root, found);
+  return found[0] ?? null;
+};
+
+export const loadConcepts = async (root: string): Promise<ConceptModel> => {
+  const name = await findConcepts(root);
+  return name ? parseConcepts(name, await readFile(join(root, name), "utf8")) : NO_CONCEPTS;
+};
+
+// --- finding concepts in a sentence ----------------------------------------
+
+// One place a sentence names a concept. `start` and `length` count words of
+// the sentence. `text` is the words as written, so "prose gates" names Prose Gate.
+export interface ConceptMention {
+  concept: string;
+  text: string;
+  start: number;
+  length: number;
+  kinds: readonly string[];
+}
+
+interface Form {
+  concept: Concept;
+  words: readonly string[];
+}
+
+// The word sequences that name each concept, its own and its plural, longest
+// first, keyed by their first word. compromise tokenises each so they line up
+// with the sentence's words, which it tokenised the same way.
+const formsCache = new WeakMap<ConceptModel, Map<string, Form[]>>();
+
+const tokens = (text: string): string[] =>
+  (nlp(text).json() as { terms: { text: string }[] }[]).flatMap((s) => s.terms.map((t) => t.text.toLowerCase()));
+
+const formsOf = (model: ConceptModel): Map<string, Form[]> => {
+  const cached = formsCache.get(model);
+  if (cached) return cached;
+  const byFirst = new Map<string, Form[]>();
+  for (const concept of model.concepts) {
+    const lower = concept.name.toLowerCase();
+    const plural = nlp(lower).nouns().toPlural().text();
+    for (const form of new Set([lower, plural].filter((f) => f.length > 0))) {
+      const words = tokens(form);
+      const first = words[0] as string;
+      byFirst.set(first, [...(byFirst.get(first) ?? []), { concept, words }]);
+    }
+  }
+  for (const forms of byFirst.values()) forms.sort((a, b) => b.words.length - a.words.length);
+  formsCache.set(model, byFirst);
+  return byFirst;
+};
+
+interface MatchWord {
+  text: string;
+  tags: readonly string[];
+}
+
+// A one-word concept must be read as a noun there, so "release the package"
+// names no Release. A longer one is specific enough as it stands.
+const matchAt = (words: readonly MatchWord[], at: number, forms: readonly Form[]): Form | undefined =>
+  forms.find(
+    (f) =>
+      f.words.every((w, i) => words[at + i]?.text.toLowerCase() === w) &&
+      (f.words.length > 1 || (words[at]?.tags.includes("Noun") ?? false)),
+  );
+
+// Every concept the words name, longest match first, never overlapping.
+export const mentionsIn = (words: readonly MatchWord[], model: ConceptModel): ConceptMention[] => {
+  if (model.concepts.length === 0) return [];
+  const byFirst = formsOf(model);
+  const mentions: ConceptMention[] = [];
+  for (let at = 0; at < words.length; at++) {
+    const form = matchAt(words, at, byFirst.get(words[at]?.text.toLowerCase() ?? "") ?? []);
+    if (!form) continue;
+    const length = form.words.length;
+    const text = words
+      .slice(at, at + length)
+      .map((w) => w.text)
+      .join(" ");
+    mentions.push({ concept: form.concept.name, text, start: at, length, kinds: form.concept.kinds });
+    at += length - 1;
+  }
+  return mentions;
+};