@micelio/eslint-config 0.1.0 → 0.1.2

package/README.md

@@ -22,3 +22,11 @@ list, so a repository that adds selectors spreads `promiseChainRestriction` back
 `@micelio/eslint-config/licenses.json` holds `allowed`, `allowedPrefixes` and
 `allowedGpl2`: the SPDX identifiers a production dependency may carry (ADR 0007). The
 repository's `lint:licenses` script reads it and evaluates SPDX expressions against it.
+
+## `lint:standard`
+
+`micelio-lint-standard` checks that `docs/engineering-standard.md` is the copy published for the
+version `AGENTS.md` pins (`` `standard: X.Y` ``), using the SHA-256 hashes in
+`@micelio/eslint-config/standard-hashes.json`. Add it as `"lint:standard": "micelio-lint-standard"`
+and to `npm run check`. A pinned version newer than the installed package knows fails with a message
+that says to upgrade the package.

package/dist/lint-standard.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/lint-standard.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { lintStandard } from './standard.js';
+// `micelio-lint-standard [root]`: the `lint:standard` script of every Micelio repository.
+const result = lintStandard(process.argv[2] ?? process.cwd());
+if (result.ok) {
+    process.stdout.write(`${result.message}\n`);
+}
+else {
+    console.error(`error: ${result.message}`);
+    process.exitCode = 1;
+}

package/dist/standard.d.ts

@@ -0,0 +1,34 @@
+/** Where every Micelio repository keeps its copy of the standard. */
+export declare const STANDARD_PATH = "docs/engineering-standard.md";
+/** The SHA-256 of each released version of the standard, by `major.minor`. */
+export type StandardHashes = Record<string, string>;
+/** What `lintStandard` found. */
+export interface StandardResult {
+    /** True when the local copy is the one published for the pinned version. */
+    ok: boolean;
+    /** One line for the terminal, naming the pinned version. */
+    message: string;
+}
+/** Hex SHA-256 of the bytes of a file. */
+export declare function hashOf(content: Buffer | string): string;
+/** Reads the version a repository pins in its `AGENTS.md`, or `null` when there is no pin. */
+export declare function readPin(agents: string): string | null;
+/**
+ * Rewrites the pin of an `AGENTS.md`, and the sentence that repeats it, to `version`.
+ *
+ * @returns The new text, or `null` when `agents` has no pin to rewrite.
+ */
+export declare function setPin(agents: string, version: string): string | null;
+/** Reads the version a copy of the standard says it is, or `null` when its header is missing. */
+export declare function standardVersion(standard: string): string | null;
+/** Loads the hashes bundled in this package. */
+export declare function loadHashes(): StandardHashes;
+/**
+ * Checks that the copy of the standard in `root` is the one published for the version its
+ * `AGENTS.md` pins (standard, section 16). A repository may pin an older version on purpose:
+ * the pinned one is checked, not the latest.
+ *
+ * @param root - The repository root.
+ * @param hashes - The published hashes; the ones bundled in this package by default.
+ */
+export declare function lintStandard(root: string, hashes?: StandardHashes): StandardResult;

package/dist/standard.js

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where every Micelio repository keeps its copy of the standard. */
+export const STANDARD_PATH = 'docs/engineering-standard.md';
+/** The machine-readable pin in `AGENTS.md`: the version in backticks after `standard:`. */
+const PIN = /(`standard:\s*)(\d+\.\d+)(`)/;
+/** The sentence of `AGENTS.md` that says the same in words, kept in step with the pin. */
+const PIN_IN_WORDS = /(follows standard version )(\d+\.\d+)/;
+/** The version line of the standard itself: `Version 1.4 (2026-10-20).` */
+const HEADER = /^Version (\d+\.\d+) /m;
+/** Hex SHA-256 of the bytes of a file. */
+export function hashOf(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** Reads the version a repository pins in its `AGENTS.md`, or `null` when there is no pin. */
+export function readPin(agents) {
+    return PIN.exec(agents)?.[2] ?? null;
+}
+/**
+ * Rewrites the pin of an `AGENTS.md`, and the sentence that repeats it, to `version`.
+ *
+ * @returns The new text, or `null` when `agents` has no pin to rewrite.
+ */
+export function setPin(agents, version) {
+    if (!PIN.test(agents))
+        return null;
+    return agents.replace(PIN, `$1${version}$3`).replace(PIN_IN_WORDS, `$1${version}`);
+}
+/** Reads the version a copy of the standard says it is, or `null` when its header is missing. */
+export function standardVersion(standard) {
+    return HEADER.exec(standard)?.[1] ?? null;
+}
+/** Loads the hashes bundled in this package. */
+export function loadHashes() {
+    const file = new URL('../standard-hashes.json', import.meta.url);
+    return JSON.parse(readFileSync(file, 'utf8'));
+}
+/**
+ * Checks that the copy of the standard in `root` is the one published for the version its
+ * `AGENTS.md` pins (standard, section 16). A repository may pin an older version on purpose:
+ * the pinned one is checked, not the latest.
+ *
+ * @param root - The repository root.
+ * @param hashes - The published hashes; the ones bundled in this package by default.
+ */
+export function lintStandard(root, hashes = loadHashes()) {
+    const agentsPath = join(root, 'AGENTS.md');
+    if (!existsSync(agentsPath)) {
+        return {
+            ok: false,
+            message: 'AGENTS.md is missing: it pins the standard version (`standard: X.Y`).',
+        };
+    }
+    const pin = readPin(readFileSync(agentsPath, 'utf8'));
+    if (!pin) {
+        return {
+            ok: false,
+            message: 'AGENTS.md pins no standard version: add `standard: X.Y` (section 16).',
+        };
+    }
+    const copyPath = join(root, STANDARD_PATH);
+    if (!existsSync(copyPath)) {
+        return { ok: false, message: `${STANDARD_PATH} is missing; AGENTS.md pins standard ${pin}.` };
+    }
+    const expected = hashes[pin];
+    if (!expected) {
+        const known = Object.keys(hashes).join(', ');
+        return {
+            ok: false,
+            message: `Standard ${pin}, pinned in AGENTS.md, is unknown to this version of @micelio/eslint-config (it knows ${known}): upgrade the package or fix the pin.`,
+        };
+    }
+    const actual = hashOf(readFileSync(copyPath));
+    if (actual !== expected) {
+        return {
+            ok: false,
+            message: `${STANDARD_PATH} does not match standard ${pin}, the version AGENTS.md pins (sha256 ${actual}, published ${expected}). Restore it, or sync it from bogd3v/micelio-engineering.`,
+        };
+    }
+    return { ok: true, message: `Standard ${pin}: ${STANDARD_PATH} matches the published copy.` };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@micelio/eslint-config",
-  "version": "0.1.0",
-  "description": "The ESLint flat config of the Micelio repositories, and the licence allowlist behind lint:licenses.",
+  "version": "0.1.2",
+  "description": "The ESLint flat config of the Micelio repositories, the licence allowlist behind lint:licenses and lint:standard.",
   "license": "MIT-0",
   "repository": {
     "type": "git",
@@ -17,11 +17,13 @@
       "default": "./dist/index.js"
     },
     "./licenses.json": "./licenses.json",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./standard-hashes.json": "./standard-hashes.json"
   },
   "files": [
     "dist",
     "licenses.json",
+    "standard-hashes.json",
     "README.md",
     "LICENSE"
   ],
@@ -41,5 +43,11 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "bin": {
+    "micelio-lint-standard": "./dist/lint-standard.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5"
   }
 }

package/standard-hashes.json

@@ -0,0 +1,4 @@
+{
+  "1.4": "0f1202bbd02a83f216313b84be4744d66ccbee60bc01b39bfc7f67cefd30e139",
+  "1.5": "c3ee8aa9a13945e073dedeecbb7ba3a9587ec0ef6878e426eb4be7a0398d93a1"
+}