@scientific-method/standard-checker 2.1.0 → 2.2.0

package/README.md

@@ -20,7 +20,9 @@ A pass ends with `spec check passed:` and the counts of entries, parity rows and
 step of the check did not run, it ends with `spec check passed with skipped steps:`, the counts, and
 `Skipped:` followed by each step and why, such as
 `Skipped: Kaitai compilation of 2 definitions (--no-ksy).` A failing run lists the skipped steps
-after its problems.
+after its problems. A `call` or `emit` whose arguments cannot be counted, because the Parameters
+section it is counted against is missing or is not `None.` or a list of parameters, or because its
+argument list is never closed, is a skipped step as well.
 
 Without `--base`, the checker compares the spec with where HEAD forked from `origin/$GITHUB_BASE_REF`,
 or from `origin/main` when that variable is unset. Outside a git repository, in a shallow clone, or

package/dist/checks/arguments.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from "../context.ts";
+/**
+ * The number of parameters a rule's Parameters section lists: 0 for `None.`, otherwise the number
+ * of items of a Markdown list whose items each open with a code span holding a name, or a name, a
+ * colon and a type, followed directly by a colon (`` - `gang: FMT-DATA-005`: the gang ``). An item
+ * may continue on indented lines. Null when the section holds anything else, so its parameters
+ * cannot be counted: `None known.`, prose after the list, or an item that names two parameters
+ * (`` - `x`, `y`: the cell ``) or puts anything between its code span and the colon.
+ */
+export declare function parameterCount(section: string): number | null;
+/**
+ * The number of arguments in the parenthesised list that opens at code[open], counting the commas
+ * outside nested brackets. Null when the list is not closed.
+ */
+export declare function argumentCount(code: string, open: number): number | null;
+/** Checks the argument count of every call, function call and emit in a live rule's procedure. */
+export declare function checkArgumentCounts(ctx: Context): void;

package/dist/checks/arguments.js

@@ -0,0 +1,195 @@
+// Argument counts: every `call` passes one argument for each item of the called rule's Parameters
+// list, every call to a function a rule defines one for each parameter of its `define`, and every
+// `emit` one for each item of the Parameters list of each handler its glossary entry names. Two
+// `emit`s of one event in rules that share a build pass the same number of arguments, which is the
+// only check an event with no handlers gets.
+//
+// A call to a split rule, and an emit to a split handler, is counted against each entry of the
+// split that lists one of the calling or emitting rule's builds, and a call to a function that a
+// split rule defines against the `define` of each such entry. A Parameters section in any other
+// form than `None.` or the list gives no count, so the calls and emits that depend on it are named
+// as a skipped step and do not fail the check. A call or emit whose argument list is never closed
+// is named as a skipped step too. Only live rules are checked, and only live rules' `define`s are
+// counted against.
+import { asList, idsIn, kindOf } from "../ids.js";
+import { BUILTINS, defines, procedureLocals, withoutCommentsAndStrings } from "./rules.js";
+/**
+ * The number of parameters a rule's Parameters section lists: 0 for `None.`, otherwise the number
+ * of items of a Markdown list whose items each open with a code span holding a name, or a name, a
+ * colon and a type, followed directly by a colon (`` - `gang: FMT-DATA-005`: the gang ``). An item
+ * may continue on indented lines. Null when the section holds anything else, so its parameters
+ * cannot be counted: `None known.`, prose after the list, or an item that names two parameters
+ * (`` - `x`, `y`: the cell ``) or puts anything between its code span and the colon.
+ */
+export function parameterCount(section) {
+    const text = section.trim();
+    if (text === "None.")
+        return 0;
+    let count = 0;
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        if (/^[-*+]\s/.test(line)) {
+            if (!/^[-*+]\s+`[a-z_][a-z0-9_]*(?:\s*:\s*[^`\s][^`]*)?`:/.test(line))
+                return null;
+            count++;
+        }
+        else if (!(count > 0 && /^\s/.test(line)))
+            return null;
+    }
+    return count > 0 ? count : null;
+}
+/**
+ * The number of arguments in the parenthesised list that opens at code[open], counting the commas
+ * outside nested brackets. Null when the list is not closed.
+ */
+export function argumentCount(code, open) {
+    let depth = 0;
+    let commas = 0;
+    let empty = true;
+    for (let i = open + 1; i < code.length; i++) {
+        const c = code[i];
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}") {
+            if (depth === 0)
+                return empty ? 0 : commas + 1;
+            depth--;
+        }
+        else if (c === "," && depth === 0)
+            commas++;
+        if (!/\s/.test(c))
+            empty = false;
+    }
+    return null;
+}
+// The argument count of a call or emit whose name ends at end: 0 when no list follows the name.
+const countAfter = (code, end) => {
+    const opening = /[ \t]*\(/y;
+    opening.lastIndex = end;
+    return opening.test(code) ? argumentCount(code, opening.lastIndex - 1) : 0;
+};
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+/** Checks the argument count of every call, function call and emit in a live rule's procedure. */
+export function checkArgumentCounts(ctx) {
+    const { problem, skip } = ctx;
+    const { entries, glossary } = ctx.spec;
+    const live = [...entries].filter(([, e]) => e.kind === "RULE" && e.meta.status !== "superseded");
+    const builds = (e) => asList(e.meta.builds);
+    const sharesBuild = (a, b) => builds(a).some((x) => builds(b).includes(x));
+    const parametersOf = (id) => entries.get(id).sections.find((s) => s.title === "Parameters")?.text;
+    const counts = new Map();
+    const countOf = (id) => {
+        if (!counts.has(id))
+            counts.set(id, parameterCount(parametersOf(id) ?? ""));
+        return counts.get(id);
+    };
+    // The entries whose Parameters section a call to rule from caller is counted against: each entry
+    // of rule's split that lists one of the caller's builds, or rule itself when none does.
+    const targetsOf = (rule, caller) => {
+        const group = [rule, ...asList(entries.get(rule).meta.split_with)].filter((x) => entries.get(x)?.kind === "RULE");
+        const sharing = [...new Set(group)].filter((x) => sharesBuild(entries.get(x), caller));
+        return sharing.length ? sharing : [rule];
+    };
+    // Rule ID -> what could not be counted against its Parameters section -> how many times.
+    const uncounted = new Map();
+    const cannotCount = (target, what) => {
+        if (!uncounted.has(target))
+            uncounted.set(target, new Map());
+        const m = uncounted.get(target);
+        m.set(what, (m.get(what) ?? 0) + 1);
+    };
+    // What could not be counted because its argument list is never closed.
+    const unclosed = [];
+    // Function name -> the rules that define it, with the parameter count of each define.
+    const defined = new Map();
+    for (const [id, e] of live)
+        for (const { name, params } of defines(withoutCommentsAndStrings(e.code ?? ""))) {
+            if (!defined.has(name))
+                defined.set(name, []);
+            defined.get(name).push({ id, count: params.length });
+        }
+    // Event name -> the argument counts its emits pass, with the rule each comes from.
+    const emitted = new Map();
+    for (const [id, e] of live) {
+        const { file } = e;
+        const code = withoutCommentsAndStrings(e.code ?? "");
+        for (const m of code.matchAll(/\bcall\s+(RULE-[A-Z0-9]+-\d+)/g)) {
+            const called = entries.get(m[1]);
+            if (!called || called.kind !== "RULE")
+                continue;
+            const n = countAfter(code, m.index + m[0].length);
+            if (n === null) {
+                unclosed.push(`call of ${m[1]} in ${id}`);
+                continue;
+            }
+            for (const target of targetsOf(m[1], e)) {
+                const want = countOf(target);
+                if (want === null)
+                    cannotCount(target, `call in ${id}`);
+                else if (want !== n)
+                    problem(file, target === m[1]
+                        ? `calls ${m[1]} with ${plural(n, "argument")}, but its Parameters section lists ${plural(want, "parameter")}`
+                        : `calls ${m[1]} with ${plural(n, "argument")}, but the Parameters section of ${target}, the entry of the split that lists a build of this rule, lists ${plural(want, "parameter")}`);
+            }
+        }
+        // A name the procedure declares itself, or a built-in, is not a function another rule defines.
+        const locals = procedureLocals(code, parametersOf(id) ?? "");
+        for (const m of code.matchAll(/(?<![.\w])(?<!\b(?:define|emit)\s+)([a-z_][a-z0-9_]*)\s*\(/g)) {
+            const owners = defined.get(m[1]);
+            if (!owners || locals.has(m[1]) || BUILTINS.has(m[1]))
+                continue;
+            const n = argumentCount(code, m.index + m[0].length - 1);
+            if (n === null) {
+                unclosed.push(`call of ${m[1]}() in ${id}`);
+                continue;
+            }
+            const near = owners.filter((o) => o.id === id || sharesBuild(entries.get(o.id), e));
+            if (near.length) {
+                for (const { id: owner, count } of near)
+                    if (count !== n)
+                        problem(file, `calls ${m[1]}() with ${plural(n, "argument")}, but its define in ${owner} takes ${plural(count, "parameter")}`);
+            }
+            else if (owners.every((o) => o.count !== n))
+                // No define lists one of this rule's builds, so the call is wrong only if it fits none of them.
+                problem(file, owners.length === 1
+                    ? `calls ${m[1]}() with ${plural(n, "argument")}, but its define in ${owners[0].id} takes ${plural(owners[0].count, "parameter")}`
+                    : `calls ${m[1]}() with ${plural(n, "argument")}, but none of its defines takes that many (${owners.map((o) => `${plural(o.count, "parameter")} in ${o.id}`).join(", ")})`);
+        }
+        for (const m of code.matchAll(/\bemit\s+([A-Za-z_][A-Za-z0-9_]*)/g)) {
+            const event = m[1];
+            const n = countAfter(code, m.index + m[0].length);
+            if (n === null) {
+                unclosed.push(`emit of ${event} in ${id}`);
+                continue;
+            }
+            if (!emitted.has(event))
+                emitted.set(event, []);
+            const others = emitted.get(event);
+            const other = others.find((o) => o.count !== n && (o.id === id || sharesBuild(o.entry, e)));
+            if (other)
+                problem(file, other.id === id
+                    ? `emits ${event} with ${plural(n, "argument")}, but also emits it with ${plural(other.count, "argument")}`
+                    : `emits ${event} with ${plural(n, "argument")}, but ${other.id} emits it with ${plural(other.count, "argument")}`);
+            if (!others.some((o) => o.id === id && o.count === n))
+                others.push({ id, entry: e, count: n });
+            const handlers = idsIn(glossary.get(event)).filter((x) => kindOf(x) === "RULE" && entries.get(x)?.kind === "RULE");
+            for (const handler of new Set(handlers.flatMap((h) => targetsOf(h, e)))) {
+                const want = countOf(handler);
+                if (want === null)
+                    cannotCount(handler, `emit of ${event} in ${id}`);
+                else if (want !== n)
+                    problem(file, `emits ${event} with ${plural(n, "argument")}, but the Parameters section of its handler ${handler} lists ${plural(want, "parameter")}`);
+            }
+        }
+    }
+    for (const [target, whats] of uncounted) {
+        const list = [...whats].map(([what, times]) => (times > 1 ? `${what} (${times} times)` : what)).join(", ");
+        const why = parametersOf(target) === undefined
+            ? "which has no Parameters section"
+            : "whose Parameters section is not None. or a list of parameters";
+        skip(`argument counts against ${target}, ${why} (${list})`);
+    }
+    for (const what of new Set(unclosed))
+        skip(`the argument count of the ${what}, whose argument list is not closed`);
+}

package/dist/checks/fields.js

@@ -21,7 +21,7 @@
 // unchecked. A declaration that writes no type, such as a parameter the Parameters section describes
 // in prose or an untyped parameter of a define, gives none and so differs from no other.
 import { asList } from "../ids.js";
-import { parameterNames, withoutCommentsAndStrings } from "./rules.js";
+import { defines, parameterNames, withoutCommentsAndStrings } from "./rules.js";
 const sameType = (a, b) => !!a && !!b && a.format.join(" ") === b.format.join(" ") && a.pointer === b.pointer && a.list === b.list;
 const FMT_ID = String.raw `FMT-[A-Z][A-Z0-9]*-\d{3,}`;
 // A type in the notation that holds a structure: a format ID, a pointer to one, or a list of either.
@@ -184,9 +184,8 @@ export function checkFieldNames(ctx, { layouts }) {
         for (const name of parameterNames(params))
             declare(name, fixed(typedParams.has(name) ? typedParams.get(name) : undefined, "the Parameters section"));
         for (const line of lines) {
-            const d = /\bdefine\s+[a-z_][a-z0-9_]*\s*\(([^)]*)\)/.exec(line);
-            if (d)
-                for (const p of d[1].split(",")) {
+            for (const d of defines(line))
+                for (const p of d.params) {
                     const [name, type] = p.split(":");
                     if (/^[a-z_][a-z0-9_]*$/.test(name.trim()))
                         declare(name.trim(), fixed(type === undefined ? undefined : typeOf(type), "its define"));

package/dist/checks/rules.d.ts

@@ -7,5 +7,21 @@ import type { FormatNames } from "./formats.ts";
 export declare const withoutCommentsAndStrings: (code: string) => string;
 /** The names a rule's Parameters section declares: each lower-case name that opens a code span, as `n` or `n: type`. */
 export declare const parameterNames: (params: string) => string[];
+/**
+ * Each `define` in a procedure: the function's name and its parameters as written, with their types
+ * (`n: UINT16`). A define with no parameters has an empty list.
+ */
+export declare const defines: (code: string) => {
+    name: string;
+    params: string[];
+}[];
+/**
+ * The names a procedure declares for itself: its `let`s, its loop variables, the parameters of its
+ * `define`s and the names its rule's Parameters section lists. A call to one of these names calls
+ * the local value, not a function another rule defines.
+ */
+export declare function procedureLocals(code: string, params: string): Set<string>;
+/** The functions every procedure may call without a rule defining them. */
+export declare const BUILTINS: Set<string>;
 /** Checks every rule's procedure. Sets Entry.code on every rule entry, superseded ones included. */
 export declare function checkRules(ctx: Context, { enumNames }: FormatNames): void;

package/dist/checks/rules.js

@@ -13,7 +13,37 @@ import { KINDS, LIST_LIMIT } from "../standard.js";
 export const withoutCommentsAndStrings = (code) => code.replace(/"[^"\n]*"/g, '""').replace(/#.*$/gm, "");
 /** The names a rule's Parameters section declares: each lower-case name that opens a code span, as `n` or `n: type`. */
 export const parameterNames = (params) => [...params.matchAll(/`([a-z_][a-z0-9_]*)(?=`|\s*:)/g)].map((m) => m[1]);
-const BUILTINS = new Set([
+/**
+ * Each `define` in a procedure: the function's name and its parameters as written, with their types
+ * (`n: UINT16`). A define with no parameters has an empty list.
+ */
+export const defines = (code) => [...code.matchAll(/\bdefine\s+([a-z_][a-z0-9_]*)\s*\(([^)]*)\)/g)].map((m) => ({
+    name: m[1],
+    params: m[2]
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p !== ""),
+}));
+/**
+ * The names a procedure declares for itself: its `let`s, its loop variables, the parameters of its
+ * `define`s and the names its rule's Parameters section lists. A call to one of these names calls
+ * the local value, not a function another rule defines.
+ */
+export function procedureLocals(code, params) {
+    const locals = new Set();
+    for (const m of code.matchAll(/\blet\s+([a-z_][a-z0-9_]*)/g))
+        locals.add(m[1]);
+    for (const m of code.matchAll(/\bfor\s+(?:each\s+)?([a-z_][a-z0-9_]*)\s+in\b/g))
+        locals.add(m[1]);
+    for (const d of defines(code))
+        for (const p of d.params)
+            locals.add(p.split(":")[0].trim());
+    for (const name of parameterNames(params))
+        locals.add(name);
+    return locals;
+}
+/** The functions every procedure may call without a rule defining them. */
+export const BUILTINS = new Set([
     "min",
     "max",
     "abs",
@@ -191,17 +221,7 @@ export function checkRules(ctx, { enumNames }) {
         if (/\b0x[0-9A-Fa-f]{6,}\b/.test(noNeutral) && /\b0x00[4-9A-F][0-9A-F]{5}\b/.test(noNeutral))
             problem(file, "the procedure contains what looks like an address outside a neutral name");
         // Functions called without `call`
-        const locals = new Set();
-        for (const m of code.matchAll(/\blet\s+([a-z_][a-z0-9_]*)/g))
-            locals.add(m[1]);
-        for (const m of code.matchAll(/\bfor\s+(?:each\s+)?([a-z_][a-z0-9_]*)\s+in\b/g))
-            locals.add(m[1]);
-        for (const m of code.matchAll(/\bdefine\s+[a-z_][a-z0-9_]*\s*\(([^)]*)\)/g))
-            for (const p of m[1].split(","))
-                locals.add(p.split(":")[0].trim());
-        const params = e.sections.find((s) => s.title === "Parameters")?.text ?? "";
-        for (const name of parameterNames(params))
-            locals.add(name);
+        const locals = procedureLocals(code, e.sections.find((s) => s.title === "Parameters")?.text ?? "");
         for (const m of code.matchAll(/(?<![.\w])([a-z_][a-z0-9_]*)\s*\(/g)) {
             const name = m[1];
             if (BUILTINS.has(name) || KEYWORDS.has(name) || locals.has(name))

package/dist/standard-checker.js

@@ -62,6 +62,7 @@
 import { readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { checkArgumentCounts } from "./checks/arguments.js";
 import { checkBase } from "./checks/base.js";
 import { checkCommentAddresses } from "./checks/comment-addresses.js";
 import { checkAcrossEntries } from "./checks/cross-entry.js";
@@ -98,6 +99,7 @@ const spec = loadSpec({ config, problem });
 const ctx = { config, problem, skip, spec, codeFiles: createCodeFiles(config, dirname(selfPath)) };
 const formatNames = checkEntries(ctx);
 checkRules(ctx, formatNames);
+checkArgumentCounts(ctx);
 checkFieldNames(ctx, formatNames);
 checkAcrossEntries(ctx, formatNames);
 compileKaitai(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scientific-method/standard-checker",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Checks a restoration's spec/, parity/ and deviations/ against version 1 of the dinorefurb documentation standard.",
   "type": "module",
   "license": "MIT",