@scientific-method/standard-checker 0.1.0 → 0.2.0

package/dist/standard.d.ts

@@ -0,0 +1,65 @@
+import type { Rule } from "./problems.ts";
+import type { Yaml } from "./types.ts";
+/** The kinds of entry, each with its directory under spec/ and the statuses it takes (none for builds and sources). */
+export declare const KINDS: Record<string, {
+    dir: string;
+    statuses: "claim" | "evidence" | null;
+}>;
+/** The statuses of a claim: a format, rule, bug or screen. */
+export declare const CLAIM_STATUSES: string[];
+/** The claim statuses that rank, lowest first. */
+export declare const SCALE: string[];
+/** The statuses of evidence: a finding or experiment. */
+export declare const EVIDENCE_STATUSES: string[];
+/** The statuses a row of a format's tables can have. */
+export declare const ROW_STATUSES: string[];
+/** The `##` sections of each kind of entry, in order. */
+export declare const SECTIONS: Record<string, string[]>;
+/** The link fields every claim has. */
+export declare const CLAIM_LINKS: string[];
+/**
+ * The rules that make the fields every entry, or every claim, has always present. A field of one
+ * kind alone is described under that kind, which has no numbered rules yet.
+ */
+export declare const FIELD_RULES: Record<string, Rule>;
+/** The front matter fields each kind of entry requires. */
+export declare const FIELDS: Record<string, {
+    required: string[];
+}>;
+/** The kinds each kind of claim may name in related. */
+export declare const RELATED_KINDS: Record<string, string[]>;
+/** The columns of the table in each section of a screen that has one. */
+export declare const SCREEN_TABLES: Record<string, string[]>;
+/** The columns of a binary format's layout table. */
+export declare const BINARY_LAYOUT: string[];
+/** The columns of a text format's layout table. */
+export declare const TEXT_LAYOUT: string[];
+/** The columns of an enumeration table. */
+export declare const ENUM_TABLE: string[];
+/** Matches every spec ID (global). */
+export declare const ID_RE: RegExp;
+/** Matches every deviation ID (global). */
+export declare const DEV_RE: RegExp;
+/** Every Markdown file the standard defines, generated or not, is at most this many lines long. */
+export declare const LINE_LIMIT = 1000;
+/**
+ * A list written out in a procedure or a table definition holds at most this many values. A longer
+ * one takes them from a value file.
+ */
+export declare const LIST_LIMIT = 64;
+/** The location rule of each file format that has one, as the comment above describes. */
+export declare const LOCATIONS: Record<string, {
+    address?: RegExp;
+    offset?: boolean;
+}>;
+/** The file formats that have a location rule. */
+export declare const FORMATS: string[];
+/** The location rule of a file format, or undefined when Standard v1 has none. */
+export declare const locationRule: (format: Yaml) => {
+    address?: RegExp;
+    offset?: boolean;
+} | undefined;
+/** The problem text for a file format that has no location rule. */
+export declare const unlistedFormat: (format: Yaml) => string;
+/** Names Windows cannot give a file, whatever the extension, so no glossary term may be one. */
+export declare const RESERVED_NAMES: RegExp;

package/dist/standard.js

@@ -0,0 +1,173 @@
+// The kinds, statuses, sections, fields and limits of version 1 of the documentation standard.
+/** The kinds of entry, each with its directory under spec/ and the statuses it takes (none for builds and sources). */
+export const KINDS = {
+    BLD: { dir: "builds", statuses: null },
+    SRC: { dir: "sources", statuses: null },
+    FMT: { dir: "formats", statuses: "claim" },
+    RULE: { dir: "rules", statuses: "claim" },
+    FND: { dir: "findings", statuses: "evidence" },
+    EXP: { dir: "experiments", statuses: "evidence" },
+    BUG: { dir: "bugs", statuses: "claim" },
+    SCR: { dir: "screens", statuses: "claim" },
+};
+/** The statuses of a claim: a format, rule, bug or screen. */
+export const CLAIM_STATUSES = ["unknown", "sourced", "supported", "established", "disputed", "superseded"];
+/** The claim statuses that rank, lowest first. */
+export const SCALE = ["unknown", "sourced", "supported", "established"];
+/** The statuses of evidence: a finding or experiment. */
+export const EVIDENCE_STATUSES = ["recorded", "reproduced", "superseded"];
+/** The statuses a row of a format's tables can have. */
+export const ROW_STATUSES = ["unknown", "sourced", "supported", "established", "disputed"];
+/** The `##` sections of each kind of entry, in order. */
+export const SECTIONS = {
+    BLD: ["Obtaining", "Compared with other builds", "Other files", "Code ranges"],
+    SRC: ["Use", "Known errors"],
+    FND: ["Observation", "Interpretation", "Alternatives", "How to reproduce"],
+    EXP: ["Question", "Setup", "Procedure", "Observations", "Results", "Conclusion"],
+    FMT: ["Layout", "Enumerations and flags", "Differences between builds", "Coverage", "Open questions"],
+    RULE: [
+        "Summary",
+        "When it runs",
+        "Parameters",
+        "Inputs",
+        "Procedure",
+        "Outputs",
+        "Edge cases",
+        "What the sources say",
+        "Differences between builds",
+        "Open questions",
+    ],
+    BUG: [
+        "Symptom",
+        "Trigger conditions",
+        "Mechanism",
+        "Frequency",
+        "Player reliance",
+        "Fixes elsewhere",
+        "Differences between builds",
+        "Open questions",
+    ],
+    SCR: [
+        "Drawn elements",
+        "Mouse input",
+        "Keyboard input",
+        "Other input",
+        "Sounds",
+        "States",
+        "Timing",
+        "Differences between builds",
+        "Open questions",
+    ],
+};
+const COMMON = ["id", "title", "status", "builds", "superseded_by"];
+/** The link fields every claim has. */
+export const CLAIM_LINKS = ["evidence", "conflicting", "split_with", "related"];
+/**
+ * The rules that make the fields every entry, or every claim, has always present. A field of one
+ * kind alone is described under that kind, which has no numbered rules yet.
+ */
+export const FIELD_RULES = {
+    id: "ENTRY-TYPES-4",
+    title: "ENTRY-TYPES-4",
+    status: "ENTRY-TYPES-4",
+    builds: "ENTRY-TYPES-4",
+    superseded_by: "ENTRY-TYPES-4",
+    evidence: "ENTRY-TYPES-5",
+    conflicting: "ENTRY-TYPES-5",
+    split_with: "ENTRY-TYPES-5",
+    related: "ENTRY-TYPES-6",
+};
+/** The front matter fields each kind of entry requires. */
+export const FIELDS = {
+    BLD: {
+        required: [
+            "id",
+            "title",
+            "superseded_by",
+            "developer",
+            "publisher",
+            "publisher_version",
+            "distribution",
+            "languages",
+            "int_width",
+            "manifest",
+        ],
+    },
+    SRC: { required: ["id", "title", "superseded_by", "author", "date", "location", "xxh3", "licence"] },
+    FND: { required: [...COMMON, "recorded_by", "reproduced_by", "method", "locations", "tool", "environment"] },
+    EXP: {
+        required: [
+            ...COMMON,
+            "recorded_by",
+            "reproduced_by",
+            "environment",
+            "starting_state",
+            "recording",
+            "repetitions",
+            "fixture",
+        ],
+    },
+    FMT: { required: [...COMMON, "files", "byte_order", "size", "text", "definition", ...CLAIM_LINKS] },
+    RULE: { required: [...COMMON, ...CLAIM_LINKS] },
+    BUG: { required: [...COMMON, "impact", "intent", "player_reliance", ...CLAIM_LINKS] },
+    SCR: { required: [...COMMON, "resolution", ...CLAIM_LINKS] },
+};
+/** The kinds each kind of claim may name in related. */
+export const RELATED_KINDS = {
+    RULE: ["RULE", "FMT", "SCR"],
+    FMT: ["RULE"],
+    BUG: ["RULE", "FMT", "SCR"],
+    SCR: ["RULE", "SCR"],
+};
+/** The columns of the table in each section of a screen that has one. */
+export const SCREEN_TABLES = {
+    "Drawn elements": ["Element", "Resource", "Shows", "Position", "Shown when", "Evidence"],
+    "Mouse input": ["Region", "Rectangle", "Enabled when", "Effect", "Evidence"],
+    "Keyboard input": ["Key", "Enabled when", "Effect", "Evidence"],
+    "Other input": ["Device", "Input", "Enabled when", "Effect", "Evidence"],
+    Sounds: ["Sound", "Resource", "Played when", "Evidence"],
+    States: ["State", "Entered when", "Left when", "Evidence"],
+};
+/** The columns of a binary format's layout table. */
+export const BINARY_LAYOUT = ["Offset", "Size", "Type", "Name", "Meaning", "Status", "Evidence"];
+/** The columns of a text format's layout table. */
+export const TEXT_LAYOUT = ["Key", "Type", "Name", "Meaning", "Status", "Evidence"];
+/** The columns of an enumeration table. */
+export const ENUM_TABLE = ["Value", "Name", "Meaning", "Status", "Evidence"];
+/** Matches every spec ID (global). */
+export const ID_RE = /\b(?:(?:FMT|RULE|FND|EXP|BUG|SCR)-[A-Z][A-Z0-9]*-\d{3,}|(?:BLD|SRC)-[A-Z][A-Z0-9.-]*[A-Z0-9])\b/g;
+/** Matches every deviation ID (global). */
+export const DEV_RE = /\bDEV-[A-Z][A-Z0-9]*-\d{3,}\b/g;
+/** Every Markdown file the standard defines, generated or not, is at most this many lines long. */
+export const LINE_LIMIT = 1000;
+/**
+ * A list written out in a procedure or a table definition holds at most this many values. A longer
+ * one takes them from a value file.
+ */
+export const LIST_LIMIT = 64;
+// How a location in each file format is given, per Standard v1. `address` is the notation of a
+// loaded address; `offset` allows a range of the shipped file. Both are judged by the unpacked
+// format when the file is packed. A format not listed here has no rule: the Standard must first decide and document how it
+// is located, and only then is it added here.
+const SEG = /^[0-9A-F]{4}:[0-9A-F]{4}$/;
+const FLAT32 = /^0x[0-9A-F]{8}$/;
+/** The location rule of each file format that has one, as the comment above describes. */
+export const LOCATIONS = {
+    MZ: { address: SEG, offset: true }, // offset only for overlay code outside the load image
+    COM: { address: SEG },
+    NE: { address: SEG },
+    PE: { address: FLAT32 },
+    LE: { address: FLAT32 },
+    LX: { address: FLAT32 },
+    ELF: { address: /^0x(?:[0-9A-F]{8}|[0-9A-F]{16})$/ },
+    data: { offset: true },
+    cdda: { offset: true },
+};
+/** The file formats that have a location rule. */
+export const FORMATS = Object.keys(LOCATIONS);
+/** The location rule of a file format, or undefined when Standard v1 has none. */
+export const locationRule = (format) => (Object.hasOwn(LOCATIONS, format) ? LOCATIONS[format] : undefined);
+/** The problem text for a file format that has no location rule. */
+export const unlistedFormat = (format) => `format ${format} has no location rule in Standard v1 (known: ${FORMATS.join(", ")}); the Standard must document how it is located before it is used`;
+/** Names Windows cannot give a file, whatever the extension, so no glossary term may be one. */
+export const RESERVED_NAMES = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A value read from front matter. Front matter comes from YAML and every check validates the fields
+ * it reads before relying on them, so a value read from it has whatever type the YAML reader produced.
+ */
+export type Yaml = any;
+/** The front matter of an entry, or any other map the YAML reader returns. */
+export type Meta = Record<string, Yaml>;
+/** A `##` section of a Markdown file: its title and the text up to the next `##` heading. */
+export interface Section {
+    /** The heading text, trimmed. */
+    title: string;
+    /** The lines under the heading, joined with `\n`. */
+    text: string;
+}
+/** A Markdown table, or a value file read as one. */
+export interface Table {
+    /** The `###` heading above the table, or null when there is none. */
+    heading: string | null;
+    /** The header cells. */
+    header: string[];
+    /** The body rows, as cells. */
+    rows: string[][];
+    /** The index of the header line within the section text, for a Markdown table. */
+    line?: number;
+    /** The value file the table was read from, for a value file. */
+    file?: string;
+}
+/** A spec entry: one Markdown file with front matter under one of the kind directories of spec/. */
+export interface Entry {
+    /** The absolute path of the entry's file. */
+    file: string;
+    /** The front matter. */
+    meta: Meta;
+    /** Everything after the front matter. */
+    body: string;
+    /** The `##` sections of the body. */
+    sections: Section[];
+    /** The kind the entry's directory stands for, such as `RULE`. */
+    kind: string;
+    /** For a rule, the text of the ```text blocks of its Procedure, set by the rule checks. */
+    code?: string;
+    /** For a format, the enumeration tables it keeps in value files, set by the format checks. */
+    valueTables?: Table[];
+}
+/** What the cited evidence of a claim, or of a row of its tables, covers for the first build. */
+export interface Facts {
+    /** How many sources it cites. */
+    sources: number;
+    /** How many static findings that list the first build it cites. */
+    staticF: number;
+    /** How many dynamic findings and experiments that list the first build it cites. */
+    dynamic: number;
+    /** Whether a complete reading covers it. */
+    completeReading: boolean;
+}
+/** A file of a --code or --references directory, read once. */
+export interface CodeFile {
+    /** True for a --code directory, false for a --references one. */
+    code: boolean;
+    /** The absolute path. */
+    file: string;
+    /** The file's text. */
+    text: string;
+}
+/** One piece of comment on a line of source. */
+export interface Comment {
+    /** The column the piece starts at. */
+    column: number;
+    /** The comment text, delimiters included. */
+    text: string;
+    /** True for the second and later lines of a block comment. */
+    continued: boolean;
+}
+/** One line of a source file as the comment reader sees it. */
+export interface CodeLine {
+    /** Whether the line holds anything other than comments and whitespace. */
+    code: boolean;
+    /** The pieces of comment on the line, in order. */
+    comments: Comment[];
+}
+/** Renders the text of one generated file at path (relative to the generated tree, without .md) for ids. */
+export type Render = (ids: string[], path: string) => string;
+/** A half-open range of a build file that holds code located by offset, from the build's Code ranges section. */
+export interface CodeRange {
+    /** The path of the file in the build's manifest. */
+    file: string;
+    /** The first offset in the range. */
+    start: bigint;
+    /** One past the last offset in the range. */
+    end: bigint;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// The shapes the checker reads a restoration into.
+export {};

package/dist/yaml.d.ts

@@ -0,0 +1,6 @@
+import type { Problem } from "./problems.ts";
+import type { Meta, Yaml } from "./types.ts";
+/** Reads one scalar or flow list. */
+export declare function parseScalar(raw: string): Yaml;
+/** Reads front matter (or a manifest) into a map, reporting each line it cannot read against file. */
+export declare function parseYaml(text: string, file: string, problem: Problem): Meta;

package/dist/yaml.js

@@ -0,0 +1,173 @@
+// The front matter reader. It understands the subset of YAML the standard's front matter uses:
+// scalars, flow lists, and block lists of flat maps.
+/** Reads one scalar or flow list. */
+export function parseScalar(raw) {
+    let v = raw.trim();
+    if (v === "")
+        return "";
+    if (v.startsWith('"')) {
+        const end = v.indexOf('"', 1);
+        return v.slice(1, end);
+    }
+    if (v.startsWith("'")) {
+        const end = v.indexOf("'", 1);
+        return v.slice(1, end);
+    }
+    const hash = v.search(/\s#/);
+    if (hash >= 0)
+        v = v.slice(0, hash).trim();
+    if (v.startsWith("[")) {
+        const inner = v.slice(1, v.lastIndexOf("]")).trim();
+        if (inner === "")
+            return [];
+        return splitFlow(inner).map((x) => parseScalar(x));
+    }
+    if (v === "null" || v === "~")
+        return null;
+    if (v === "true")
+        return true;
+    if (v === "false")
+        return false;
+    if (/^-?\d+$/.test(v))
+        return Number(v);
+    if (/^-?\d+\.\d+$/.test(v))
+        return Number(v);
+    return v;
+}
+function splitFlow(s) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    for (const ch of s) {
+        if (quote) {
+            cur += ch;
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            cur += ch;
+        }
+        else if (ch === ",") {
+            out.push(cur.trim());
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    if (cur.trim() !== "")
+        out.push(cur.trim());
+    return out;
+}
+function stripComment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === "#" && (i === 0 || /\s/.test(line[i - 1])))
+            return line.slice(0, i).replace(/\s+$/, "");
+    }
+    return line.replace(/\s+$/, "");
+}
+/** Reads front matter (or a manifest) into a map, reporting each line it cannot read against file. */
+export function parseYaml(text, file, problem) {
+    const lines = text.split(/\r?\n/).map(stripComment);
+    const obj = {};
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === "") {
+            i++;
+            continue;
+        }
+        const m = /^([A-Za-z_][A-Za-z0-9_]*):(.*)$/.exec(line);
+        if (!m) {
+            problem(file, `unreadable front matter line: ${line}`);
+            i++;
+            continue;
+        }
+        const key = m[1];
+        const rest = m[2];
+        if (key in obj)
+            problem(file, `front matter repeats the field ${key}`);
+        if (rest.trim() !== "") {
+            obj[key] = parseScalar(rest);
+            i++;
+            continue;
+        }
+        // block list
+        const items = [];
+        i++;
+        let current = null;
+        let itemIndent = null;
+        while (i < lines.length && (lines[i].trim() === "" || /^\s/.test(lines[i]))) {
+            const l = lines[i];
+            if (l.trim() === "") {
+                i++;
+                continue;
+            }
+            const dash = /^(\s*)- (.*)$/.exec(l);
+            if (dash && (itemIndent === null || dash[1].length === itemIndent)) {
+                itemIndent = dash[1].length;
+                const body = dash[2];
+                const kv = /^([A-Za-z_][A-Za-z0-9_]*):(.*)$/.exec(body);
+                if (kv) {
+                    current = {};
+                    items.push(current);
+                    if (kv[2].trim() !== "")
+                        current[kv[1]] = parseScalar(kv[2]);
+                    else
+                        current[kv[1]] = parseNested();
+                }
+                else {
+                    current = null;
+                    items.push(parseScalar(body));
+                }
+                i++;
+                continue;
+            }
+            const kv = /^\s+([A-Za-z_][A-Za-z0-9_]*):(.*)$/.exec(l);
+            if (kv && current) {
+                if (kv[2].trim() !== "")
+                    current[kv[1]] = parseScalar(kv[2]);
+                else {
+                    i++;
+                    current[kv[1]] = parseNestedFrom();
+                    continue;
+                }
+                i++;
+                continue;
+            }
+            problem(file, `unreadable front matter line: ${l}`);
+            i++;
+        }
+        obj[key] = items;
+    }
+    return obj;
+    // A nested map under a list item (such as `unpacked:` of a packed file).
+    function parseNestedFrom() {
+        const nested = {};
+        const indent = /^(\s*)/.exec(lines[i])[1].length;
+        while (i < lines.length &&
+            lines[i].trim() !== "" &&
+            /^(\s*)/.exec(lines[i])[1].length >= indent &&
+            !/^\s*- /.test(lines[i])) {
+            const kv = /^\s+([A-Za-z_][A-Za-z0-9_]*):(.*)$/.exec(lines[i]);
+            if (kv)
+                nested[kv[1]] = parseScalar(kv[2]);
+            i++;
+        }
+        return nested;
+    }
+    function parseNested() {
+        i++;
+        const r = parseNestedFrom();
+        i--;
+        return r;
+    }
+}

package/package.json

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