@hajimism/dek 0.5.1 → 0.6.0

package/src/plugins/words/list.ts

@@ -0,0 +1,288 @@
+import { ALLOW_FILE, LIST_PATH } from "./manifest.ts";
+import { parseYaml, YamlError } from "./yaml.ts";
+
+/** How a verb's forms are found: by its stem and each kana of its row, or by its stem alone. */
+type Verb = "godan" | "ichidan";
+
+/** One word on the project's list. */
+export type Entry = {
+  word: string;
+  /** A regular expression looked for instead of `word`. */
+  pattern?: string;
+  verb?: Verb;
+  /** Longer words that hold the word and are not it. */
+  except: string[];
+  /** What to write instead. */
+  use?: string;
+  /** Where to look, when only one of them. */
+  in?: "slides" | "script";
+  /** Where the entry starts in the list. */
+  line: number;
+};
+
+/** What is wrong with a file, and the line to look at. */
+export type Problem = { message: string; line: number };
+
+const VERSION = 1;
+const ENTRY_KEYS = new Set(["word", "pattern", "verb", "except", "use", "in"]);
+
+/** The last kana of a godan verb's dictionary form. */
+const GODAN_ENDINGS = ["う", "く", "ぐ", "す", "つ", "ぬ", "ぶ", "む", "る"];
+
+/** What YAML made of words written without quotes, when it made them something other than text. */
+function unquoted(value: unknown): string | undefined {
+  if (typeof value === "number") {
+    return `the number ${value}`;
+  }
+  return typeof value === "boolean" ? String(value) : undefined;
+}
+
+type Read = {
+  /** The top mapping's fields, or why the file gives none. */
+  fields?: Record<string, unknown>;
+  problem?: Problem;
+  lineOf: (mapping: object) => number | undefined;
+  /** The line of the first line matching `pattern`, or of the top. */
+  lineWith: (pattern: RegExp) => number;
+};
+
+/** A file of this plugin, read as far as its version: a mapping of version 1, or a problem. */
+function readFile(source: string, name: string, keys: string[]): Read {
+  const lines = source.split(/\r?\n/);
+  const lineWith = (pattern: RegExp) => {
+    const index = lines.findIndex((text) => pattern.test(text));
+    return index === -1 ? 1 : index + 1;
+  };
+  let parsed: ReturnType<typeof parseYaml>;
+  try {
+    parsed = parseYaml(source);
+  } catch (error) {
+    if (error instanceof YamlError) {
+      const problem = {
+        message: `${name} is not YAML dek-words reads: ${error.message}`,
+        line: error.line,
+      };
+      return { problem, lineOf: () => undefined, lineWith };
+    }
+    throw error;
+  }
+  const { value, lineOf } = parsed;
+  if (value === null) {
+    return { lineOf, lineWith };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return { problem: { message: `${name} is not a mapping`, line: 1 }, lineOf, lineWith };
+  }
+  const fields = value as Record<string, unknown>;
+  if (fields.version !== VERSION) {
+    const message = `${name} is version ${String(fields.version)}; this dek-words reads version ${VERSION}`;
+    return { problem: { message, line: lineWith(/^version\s*:/) }, lineOf, lineWith };
+  }
+  const extra = Object.keys(fields).find((key) => key !== "version" && !keys.includes(key));
+  if (extra !== undefined) {
+    const hint = keys.length === 1 ? `; write \`${keys[0]}\`` : "";
+    const message = `${name} has \`${extra}\`, which it does not take${hint}`;
+    return { problem: { message, line: lineWith(new RegExp(`^${extra}\\s*:`)) }, lineOf, lineWith };
+  }
+  return { fields, lineOf, lineWith };
+}
+
+/**
+ * The entries of the project's list, and what keeps the rest from being used. An entry with a
+ * problem is left out, so every entry that reads is still checked.
+ */
+export function readList(source: string): { entries: Entry[]; problems: Problem[] } {
+  const file = readFile(source, LIST_PATH, ["words"]);
+  if (file.problem) {
+    return { entries: [], problems: [file.problem] };
+  }
+  const words = file.fields?.words;
+  if (words === undefined || words === null) {
+    return { entries: [], problems: [] };
+  }
+  if (!Array.isArray(words)) {
+    return {
+      entries: [],
+      problems: [{ message: "`words` is not a list", line: file.lineWith(/^words\s*:/) }],
+    };
+  }
+  const entries: Entry[] = [];
+  const problems: Problem[] = [];
+  const seen = new Set<string>();
+  words.forEach((item: unknown, index) => {
+    const fields =
+      typeof item === "object" && item !== null && !Array.isArray(item)
+        ? (item as Record<string, unknown>)
+        : undefined;
+    const line = (fields && file.lineOf(fields)) ?? file.lineWith(/^words\s*:/);
+    const read = readEntry(fields, `#${index + 1}`, line);
+    if ("problem" in read) {
+      problems.push({ message: read.problem, line });
+      return;
+    }
+    if (seen.has(read.entry.word)) {
+      problems.push({ message: `entry ${read.entry.word} is on the list twice; keep one`, line });
+      return;
+    }
+    seen.add(read.entry.word);
+    entries.push(read.entry);
+  });
+  return { entries, problems };
+}
+
+/** Every `word` the list names, entries that do not read included, so an allow of one is no mistake. */
+export function listedWords(source: string): Set<string> {
+  const { fields } = readFile(source, LIST_PATH, ["words"]);
+  const words = Array.isArray(fields?.words) ? fields.words : [];
+  return new Set(
+    words.flatMap((item: unknown) => {
+      const word = (item as { word?: unknown } | null)?.word;
+      return typeof word === "string" && word !== "" ? [word] : [];
+    }),
+  );
+}
+
+function readEntry(
+  fields: Record<string, unknown> | undefined,
+  position: string,
+  line: number,
+): { entry: Entry } | { problem: string } {
+  if (fields === undefined) {
+    return { problem: `entry ${position} is not a mapping of \`word\` and the rest` };
+  }
+  const word = typeof fields.word === "string" && fields.word !== "" ? fields.word : undefined;
+  const name = word ?? position;
+  for (const key of ["word", "pattern", "use"] as const) {
+    const made = unquoted(fields[key]);
+    if (made !== undefined) {
+      return { problem: `entry ${name}: YAML reads its \`${key}\` as ${made}; put it in quotes` };
+    }
+  }
+  if (word === undefined) {
+    return { problem: `entry ${name} has no \`word\`` };
+  }
+  const extra = Object.keys(fields).find((key) => !ENTRY_KEYS.has(key));
+  if (extra !== undefined) {
+    return { problem: `entry ${word} has \`${extra}\`, which the list does not take` };
+  }
+  const { pattern, verb, except = [], use, in: where } = fields;
+  if (pattern !== undefined && verb !== undefined) {
+    return { problem: `entry ${word} has both \`verb\` and \`pattern\`; keep one` };
+  }
+  if (pattern !== undefined) {
+    const problem = patternProblem(pattern);
+    if (problem) {
+      return { problem: `entry ${word}: ${problem}` };
+    }
+  }
+  if (verb !== undefined) {
+    const problem = verbProblem(word, verb);
+    if (problem) {
+      return { problem: `entry ${word}: ${problem}` };
+    }
+  }
+  if (!Array.isArray(except) || except.some((item) => typeof item !== "string" || item === "")) {
+    return { problem: `entry ${word}: \`except\` is a list of words` };
+  }
+  if (use !== undefined && typeof use !== "string") {
+    return { problem: `entry ${word}: \`use\` is text` };
+  }
+  if (where !== undefined && where !== "slides" && where !== "script") {
+    return { problem: `entry ${word}: \`in\` is slides or script, not ${String(where)}` };
+  }
+  return {
+    entry: {
+      word,
+      ...(typeof pattern === "string" ? { pattern } : {}),
+      ...(verb === "godan" || verb === "ichidan" ? { verb } : {}),
+      except: except as string[],
+      ...(typeof use === "string" && use !== "" ? { use } : {}),
+      ...(where === "slides" || where === "script" ? { in: where } : {}),
+      line,
+    },
+  };
+}
+
+function patternProblem(pattern: unknown): string | undefined {
+  if (typeof pattern !== "string" || pattern === "") {
+    return "`pattern` is a regular expression, written as text";
+  }
+  let compiled: RegExp;
+  try {
+    compiled = new RegExp(pattern, "iu");
+  } catch {
+    return `\`pattern\` is not a regular expression: ${pattern}`;
+  }
+  return compiled.test("") ? "`pattern` matches where there is no text" : undefined;
+}
+
+function verbProblem(word: string, verb: unknown): string | undefined {
+  if (verb !== "godan" && verb !== "ichidan") {
+    return `\`verb\` is godan or ichidan, not ${String(verb)}`;
+  }
+  const letters = [...word];
+  const last = letters.at(-1) ?? "";
+  if (verb === "godan" && (letters.length < 2 || !GODAN_ENDINGS.includes(last))) {
+    return `a godan verb ends in ${GODAN_ENDINGS.slice(0, -1).join(", ")}, or る`;
+  }
+  if (verb === "ichidan" && (letters.length < 2 || last !== "る")) {
+    return "an ichidan verb ends in る";
+  }
+  // An ichidan verb is found by its stem alone, and 見 alone is in 意見 and 見解.
+  if (verb === "ichidan" && letters.length === 2) {
+    return `its stem ${letters[0]} is one letter, which too many words hold; write a \`pattern\` for its forms`;
+  }
+  return undefined;
+}
+
+/** The words a deck allows, each an entry's `word`, and what is wrong with the file. */
+export function readAllows(
+  source: string,
+  listed: Set<string>,
+): { allows: Set<string>; problems: Problem[] } {
+  const file = readFile(source, ALLOW_FILE, ["allow"]);
+  if (file.problem) {
+    return { allows: new Set(), problems: [file.problem] };
+  }
+  const allow = file.fields?.allow;
+  if (allow === undefined || allow === null) {
+    return { allows: new Set(), problems: [] };
+  }
+  const listLine = file.lineWith(/^allow\s*:/);
+  if (!Array.isArray(allow)) {
+    return {
+      allows: new Set(),
+      problems: [{ message: "`allow` is a list of words", line: listLine }],
+    };
+  }
+  const allows = new Set<string>();
+  const problems: Problem[] = [];
+  const lines = source.split(/\r?\n/);
+  for (const item of allow) {
+    const word = typeof item === "string" ? item : String(item);
+    const index = lines.findIndex(
+      (text, at) =>
+        at >= listLine && new RegExp(`^\\s*-\\s*['"]?${literal(word)}['"]?\\s*(#.*)?$`).test(text),
+    );
+    const line = index === -1 ? listLine : index + 1;
+    if (typeof item !== "string") {
+      problems.push({
+        message: `${ALLOW_FILE}: YAML reads an allow as ${unquoted(item) ?? "no text"}; put it in quotes`,
+        line,
+      });
+    } else if (!listed.has(item)) {
+      problems.push({
+        message: `${ALLOW_FILE} allows ${item}, which is no entry on ${LIST_PATH}`,
+        line,
+      });
+    } else {
+      allows.add(item);
+    }
+  }
+  return { allows, problems };
+}
+
+/** `text` as a regular expression that matches it as written. */
+export function literal(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/plugins/words/main.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env bun
+/**
+ * dek-words, the second plugin dek ships (ADR 36). dek runs it as any plugin (ADR 32), in a bun of its
+ * own: `manifest` to pin what it promises, and `check --protocol 1` in a deck's folder, with the
+ * deck on stdin, for SARIF. It shares only the types in plugin-api.ts with dek, never its code.
+ */
+import { readFileSync } from "node:fs";
+import type { CheckInput } from "../../plugin-api.ts";
+import { check } from "./check.ts";
+import { MANIFEST } from "./manifest.ts";
+import { toSarif } from "./sarif.ts";
+
+const USAGE = "usage: dek-words manifest | dek-words check --protocol 1  (dek runs both)";
+
+async function main(args: string[]): Promise<number> {
+  switch (args[0]) {
+    case "manifest":
+      process.stdout.write(`${JSON.stringify(MANIFEST)}\n`);
+      return 0;
+    case "check": {
+      if (args[1] !== "--protocol" || args[2] !== "1") {
+        process.stderr.write(
+          `dek-words speaks check protocol 1; dek asked for ${args.slice(1).join(" ")}\n`,
+        );
+        return 2;
+      }
+      const input = JSON.parse(await Bun.stdin.text()) as CheckInput;
+      const findings = await check(input, async (path) => readIfThere(path));
+      process.stdout.write(`${JSON.stringify(toSarif(findings))}\n`);
+      return 0;
+    }
+    default:
+      process.stderr.write(`${USAGE}\n`);
+      return 2;
+  }
+}
+
+/**
+ * A file of the deck, relative to its folder, which is where dek runs the check, or the project's
+ * list by its absolute path.
+ */
+function readIfThere(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+process.exit(await main(process.argv.slice(2)));

package/src/plugins/words/manifest.ts

@@ -0,0 +1,36 @@
+import type { PluginManifest, PluginRules } from "../../plugin-api.ts";
+
+/**
+ * The one place each rule is declared: the manifest prints it, and a finding can name only a rule
+ * here, so dek-words cannot report an id its manifest does not declare.
+ */
+const RULES = {
+  WORDS001: { severity: "warning", summary: "a word on the project's word list is in the deck" },
+  WORDS002: { severity: "error", summary: "the word list or a deck's allows cannot be read" },
+} as const satisfies PluginRules<"WORDS">;
+
+export type RuleId = keyof typeof RULES;
+
+/** The project's list, in `plugins/words/` (ADR 35). */
+export const LIST_FILE = "words.yaml";
+
+/** The list as an agent finds it, from the project's root. */
+export const LIST_PATH = `plugins/words/${LIST_FILE}`;
+
+/** The words a deck allows, in its folder. */
+export const ALLOW_FILE = "words.yaml";
+
+/**
+ * dek-words' own version, apart from dek's: a project accepts a change to what it promises, and
+ * a dek release that leaves the rules as they were must not ask for that.
+ */
+const VERSION = "0.1.0";
+
+/** What `dek-words manifest` prints: the same every time, since dek pins it. */
+export const MANIFEST = {
+  schema: 1,
+  name: "words",
+  version: VERSION,
+  check: { protocol: 1, rules: RULES },
+  data: [{ path: LIST_FILE, in: "project" }, { path: ALLOW_FILE }],
+} as const satisfies PluginManifest<"WORDS">;

package/src/plugins/words/match.ts

@@ -0,0 +1,60 @@
+import { type Entry, literal } from "./list.ts";
+
+/** One place an entry is found: where it starts in the block's text, and the text found. */
+export type Found = { index: number; text: string };
+
+/**
+ * The kana after a godan verb's stem, by the kana its dictionary form ends in: the five of its
+ * row, and the euphonic form before て and た (効い, 待っ, 読ん). す has none of its own.
+ */
+const GODAN_FORMS: Record<string, string> = {
+  う: "わいうえおっ",
+  く: "かきくけこい",
+  ぐ: "がぎぐげごい",
+  す: "さしすせそ",
+  つ: "たちつてとっ",
+  ぬ: "なにぬねのん",
+  ぶ: "ばびぶべぼん",
+  む: "まみむめもん",
+  る: "らりるれろっ",
+};
+
+/** Letters of a script written with spaces between words, where a word is matched whole. */
+const SPACED = /[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}\p{Nd}]/u;
+
+/** What an entry looks for, as a regular expression with the `u` and `i` flags. */
+function source(entry: Entry): string {
+  if (entry.pattern !== undefined) {
+    return entry.pattern;
+  }
+  const stem = literal(entry.word.slice(0, -1));
+  if (entry.verb === "godan") {
+    return `${stem}[${GODAN_FORMS[entry.word.at(-1) ?? ""] ?? ""}]`;
+  }
+  if (entry.verb === "ichidan") {
+    return stem;
+  }
+  const word = literal(entry.word);
+  const opens = SPACED.test(entry.word[0] ?? "") ? `(?<!${SPACED.source})` : "";
+  const closes = SPACED.test(entry.word.at(-1) ?? "") ? `(?!${SPACED.source})` : "";
+  return `${opens}${word}${closes}`;
+}
+
+/** Where `entry` is in a block's text, leaving out each place inside a word it excepts. */
+export function finder(entry: Entry): (text: string) => Found[] {
+  const pattern = new RegExp(source(entry), "giu");
+  const excepts = entry.except.map((word) => new RegExp(literal(word), "giu"));
+  return (text) => {
+    const excepted = excepts.flatMap((except) =>
+      [...text.matchAll(except)].map((match) => [match.index, match.index + match[0].length]),
+    );
+    return [...text.matchAll(pattern)].flatMap((match): Found[] => {
+      const start = match.index;
+      const end = start + match[0].length;
+      if (match[0] === "" || excepted.some(([from = 0, to = 0]) => from <= start && end <= to)) {
+        return [];
+      }
+      return [{ index: start, text: match[0] }];
+    });
+  };
+}

package/src/plugins/words/sarif.ts

@@ -0,0 +1,37 @@
+import type { CheckOutput } from "../../plugin-api.ts";
+import type { Finding } from "./check.ts";
+import type { RuleId } from "./manifest.ts";
+import { MANIFEST } from "./manifest.ts";
+
+/** Findings as the SARIF dek reads: the rule, the message, the place, and the hint. */
+export function toSarif(findings: Finding[]): CheckOutput<RuleId> {
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [
+      {
+        tool: { driver: { name: "dek-words", version: MANIFEST.version } },
+        results: findings.map((finding) => ({
+          ruleId: finding.rule,
+          message: { text: finding.message },
+          locations: [
+            {
+              physicalLocation: {
+                artifactLocation: { uri: finding.path },
+                ...(finding.line === undefined
+                  ? {}
+                  : {
+                      region: {
+                        startLine: finding.line,
+                        ...(finding.column === undefined ? {} : { startColumn: finding.column }),
+                      },
+                    }),
+              },
+            },
+          ],
+          properties: { hint: finding.hint },
+        })),
+      },
+    ],
+  };
+}