@micelio/eslint-config 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright (c) 2026 Alejandro Ramirez Garcia and the Micelio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @micelio/eslint-config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The ESLint flat config of the Micelio repositories (sections 4 and 15 of the
+engineering standard) and the licence allowlist that `npm run lint:licenses` reads.
+
+```js
+// eslint.config.js
+import micelio from '@micelio/eslint-config'
+
+export default [...micelio, { ignores: ['generated/**'] }]
+```
+
+It extends `typescript-eslint`'s recommended rules and `eslint-config-prettier`, bans
+promise chains and `console.log` (except in `scripts/`), and in `.ts` files requires
+typed module boundaries (`explicit-module-boundary-types`), valid TSDoc (`tsdoc/syntax`) and a doc
+comment on every public export (`jsdoc/require-jsdoc`). `eslint` and `typescript` are
+peer dependencies. A flat-config override of `no-restricted-syntax` replaces the option
+list, so a repository that adds selectors spreads `promiseChainRestriction` back in.
+
+## Licence allowlist
+
+`@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/index.d.ts

@@ -0,0 +1,32 @@
+import type { Linter } from 'eslint';
+/**
+ * The `no-restricted-syntax` entry that bans `.then()`, `.catch()` and `.finally()` chains.
+ *
+ * @remarks
+ * A flat-config override of `no-restricted-syntax` replaces the whole option list, so a
+ * repository that adds its own selectors spreads this one back in:
+ * `['error', promiseChainRestriction, { selector: '…', message: '…' }]`.
+ */
+export declare const promiseChainRestriction: {
+    readonly selector: "CallExpression[callee.type='MemberExpression'][callee.property.name=/^(then|catch|finally)$/]";
+    readonly message: "No promise chains: use await with try/catch (AGENTS.md, Async code).";
+};
+/**
+ * The ESLint flat config shared by every Micelio repository (standard, sections 4 and 15).
+ *
+ * @remarks
+ * It extends `typescript-eslint`'s recommended rules, turns off the rules Prettier owns,
+ * bans promise chains and `console.log` (outside `scripts/`) and, in `.ts` files, requires
+ * typed module boundaries, valid TSDoc (`tsdoc/syntax`) and a doc comment on every public export
+ * (`jsdoc/require-jsdoc`). Spread it in the repository's
+ * `eslint.config.js` and add the repository's own entries after it.
+ *
+ * @example
+ * ```ts
+ * import micelio from '@micelio/eslint-config';
+ *
+ * export default [...micelio, { ignores: ['generated/**'] }];
+ * ```
+ */
+declare const config: Linter.Config[];
+export default config;

package/dist/index.js

@@ -0,0 +1,79 @@
+import { defineConfig } from 'eslint/config';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import jsdoc from 'eslint-plugin-jsdoc';
+import tsdoc from 'eslint-plugin-tsdoc';
+import tseslint from 'typescript-eslint';
+/** Message shown when code chains a promise instead of awaiting it. */
+const PROMISE_CHAIN_MESSAGE = 'No promise chains: use await with try/catch (AGENTS.md, Async code).';
+/**
+ * The `no-restricted-syntax` entry that bans `.then()`, `.catch()` and `.finally()` chains.
+ *
+ * @remarks
+ * A flat-config override of `no-restricted-syntax` replaces the whole option list, so a
+ * repository that adds its own selectors spreads this one back in:
+ * `['error', promiseChainRestriction, { selector: '…', message: '…' }]`.
+ */
+export const promiseChainRestriction = {
+    selector: "CallExpression[callee.type='MemberExpression'][callee.property.name=/^(then|catch|finally)$/]",
+    message: PROMISE_CHAIN_MESSAGE,
+};
+/** Files that never need a doc comment: declarations, build output and tests. */
+const UNDOCUMENTED_FILES = ['**/*.d.ts', 'dist/**', 'test/**', 'tests/**', 'e2e/**', '**/*.test.ts'];
+/**
+ * The ESLint flat config shared by every Micelio repository (standard, sections 4 and 15).
+ *
+ * @remarks
+ * It extends `typescript-eslint`'s recommended rules, turns off the rules Prettier owns,
+ * bans promise chains and `console.log` (outside `scripts/`) and, in `.ts` files, requires
+ * typed module boundaries, valid TSDoc (`tsdoc/syntax`) and a doc comment on every public export
+ * (`jsdoc/require-jsdoc`). Spread it in the repository's
+ * `eslint.config.js` and add the repository's own entries after it.
+ *
+ * @example
+ * ```ts
+ * import micelio from '@micelio/eslint-config';
+ *
+ * export default [...micelio, { ignores: ['generated/**'] }];
+ * ```
+ */
+const config = defineConfig({
+    ignores: ['dist/', 'build/', 'coverage/', 'node_modules/', '.tmp/', '.cache/'],
+}, tseslint.configs.recommended, eslintConfigPrettier, {
+    files: ['**/*.ts', '**/*.js', '**/*.mjs'],
+    languageOptions: {
+        ecmaVersion: 2023,
+        sourceType: 'module',
+    },
+    rules: {
+        '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+        'no-restricted-syntax': ['error', promiseChainRestriction],
+        'no-console': ['error', { allow: ['warn', 'error'] }],
+    },
+}, {
+    // Scripts talk to the terminal (standard, section 4, "Errors and logging")
+    files: ['scripts/**', '.claude/skills/**/scripts/**'],
+    rules: { 'no-console': 'off' },
+}, {
+    files: ['**/*.ts'],
+    ignores: UNDOCUMENTED_FILES,
+    plugins: { tsdoc, jsdoc },
+    rules: {
+        // Exported functions declare their parameter and return types (standard, section 4)
+        '@typescript-eslint/explicit-module-boundary-types': 'error',
+        'tsdoc/syntax': 'error',
+        'jsdoc/require-jsdoc': [
+            'error',
+            {
+                publicOnly: true,
+                require: { FunctionDeclaration: true, ClassDeclaration: true },
+                contexts: [
+                    'ExportNamedDeclaration > TSInterfaceDeclaration',
+                    'ExportNamedDeclaration > TSTypeAliasDeclaration',
+                    'ExportNamedDeclaration > TSEnumDeclaration',
+                    'ExportNamedDeclaration > VariableDeclaration',
+                ],
+            },
+        ],
+    },
+});
+export default config;

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/licenses.json

@@ -0,0 +1,24 @@
+{
+  "$comment": "Licences a production dependency may carry (ADR 0007, AGPL-3.0-only). SPDX expressions are judged by the repository's lint:licenses script: OR passes if one side is allowed, AND needs all, `X WITH exception` is judged by X. Dev-only dependencies are not distributed and only warn.",
+  "allowed": [
+    "MIT",
+    "ISC",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "0BSD",
+    "Apache-2.0",
+    "MPL-2.0",
+    "CC0-1.0",
+    "MIT-0",
+    "CC-BY-3.0",
+    "CC-BY-4.0",
+    "Unlicense",
+    "BlueOak-1.0.0",
+    "Python-2.0",
+    "Zlib",
+    "OFL-1.1",
+    "WTFPL"
+  ],
+  "allowedPrefixes": ["LGPL-", "GPL-3.0", "AGPL-3.0"],
+  "allowedGpl2": ["GPL-2.0-or-later", "GPL-2.0+"]
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@micelio/eslint-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The ESLint flat config of the Micelio repositories, the licence allowlist behind lint:licenses and lint:standard.",
+  "license": "MIT-0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bogd3v/micelio-engineering.git",
+    "directory": "packages/eslint-config"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./licenses.json": "./licenses.json",
+    "./package.json": "./package.json",
+    "./standard-hashes.json": "./standard-hashes.json"
+  },
+  "files": [
+    "dist",
+    "licenses.json",
+    "standard-hashes.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsdoc": "^65.3.6",
+    "eslint-plugin-tsdoc": "0.5.4",
+    "typescript-eslint": "^8.71.2"
+  },
+  "peerDependencies": {
+    "eslint": "^10.12.0",
+    "typescript": "^5.9.3"
+  },
+  "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,3 @@
+{
+  "1.4": "0f1202bbd02a83f216313b84be4744d66ccbee60bc01b39bfc7f67cefd30e139"
+}