@starci/eslint-canon-fe 9.13.16 → 9.14.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 9.14.1 - 2026-11-05
+
+- Changed: the runtime copy of the canon pins names `@starci/hfs` 5.11.1 and the Grammar family 0.21.36.
+
+## 9.14.0 - 2026-11-05
+
+- Added (PROJECT-LINT-3): `starciFeConfig` loads the ESLint rules of the app's rule packs (hfs.json `rulePacks`) for the fe side, one plugin per pack, each rule at its severity; a refused pack throws `HFS_RULE_PACK_INVALID`. The runtime copies carry `scripts/lib/rule-packs.mjs`, the `rulePacks` key of the declaration check and the canon pins of `@starci/hfs` 5.11.0.
+
 ## 9.13.16 - 2026-11-05
 
 - Changed: the runtime copy of the canon pins names `@starci/hfs` 5.10.4 and the Grammar family 0.21.34.

package/dist/index.js

@@ -8,6 +8,7 @@
  * Published IDs identify their owning law. Namespace migrations are explicit in the removed-vocabulary
  * catalog; compatibility aliases cannot create a second owner for a rule.
  */
+import { packEslintConfigs } from "#runtime/scripts/lib/rule-packs.mjs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -238,14 +239,29 @@ export const starciFeConfig = ({ hfs } = {}) => {
         throw new Error(`starciFeConfig: these published rules are not requested at error: ${notRequested.join(", ")}`);
     }
     const reactHooks = loadReactHooks();
-    return buildFeConfig({
-        hfs,
-        plugin,
-        reactHooks,
-        tsPlugin: loadTsPlugin(),
-        sonar: loadSonarPlugins(),
-        source: { ...recommended, ...reactHooksRules(reactHooks) },
-    });
+    return [
+        ...buildFeConfig({
+            hfs,
+            plugin,
+            reactHooks,
+            tsPlugin: loadTsPlugin(),
+            sonar: loadSonarPlugins(),
+            source: { ...recommended, ...reactHooksRules(reactHooks) },
+        }),
+        ...withPackRules(hfs, "fe"),
+    ];
+};
+/**
+ * The ESLint rules of the app's rule packs (hfs.json `rulePacks`, contexts/project/lint.md PROJECT-LINT-3) for one scope: the one sanctioned way an app adds
+ * a lint law, loaded by this factory so no tool config of the app defines a rule. A refused pack throws (HFS_RULE_PACK_INVALID): a lint run never guesses.
+ *
+ * @param hfs - The HFS view the config was built for (its repoRoot is the folder of the eslint.config.mjs).
+ * @param side - The scope: the fe side (the root packages take theirs from starciBePackagesConfig).
+ * @returns The pack blocks, none when the app declares no pack or the view is missing.
+ */
+const withPackRules = (hfs, side) => {
+    const root = typeof hfs === "object" && hfs !== null && "repoRoot" in hfs && typeof hfs.repoRoot === "string" ? hfs.repoRoot : null;
+    return root === null ? [] : packEslintConfigs(root, side);
 };
 /**
  * The flat config of the front-end subpaths of an app's root workspace packages (`packages/<pkg>/src/workbench/**` and `src/public/**`), for the
@@ -260,6 +276,7 @@ export const starciFePackagesConfig = ({ hfs } = {}) => {
     const reactHooks = loadReactHooks();
     const graph = new Set(Object.keys(projectGraphRecommended));
     const source = { ...Object.fromEntries(Object.entries(recommended).filter(([name]) => !graph.has(name))), ...reactHooksRules(reactHooks) };
+    // The pack rules of the root packages come once, with starciBePackagesConfig of the same root config (one plugin per pack).
     return scopeToPackages(buildFeConfig({ hfs, plugin, reactHooks, tsPlugin: loadTsPlugin(), sonar: loadSonarPlugins(), source }));
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.13.16",
+  "version": "9.14.1",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",

package/runtime/bundle.json

@@ -169,6 +169,7 @@
     "scripts/lib/path-key.mjs",
     "scripts/lib/read-text.mjs",
     "scripts/lib/regex.mjs",
+    "scripts/lib/rule-packs.mjs",
     "scripts/lib/same-text.mjs",
     "scripts/lib/sops-envelope.mjs",
     "scripts/lib/stack-services.mjs",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -38,7 +38,7 @@ pins:
     source: packages/next-data/package.json
     why: 'the SWR data helpers of every front end (fe-stack data, owner:next-data-package): pollingRestart, the viewer and tenant key helpers, viewerSwrConfig and the viewer cache; each operation hook stays in the app and the package holds no component.'
   '@starci/grammar':
-    version: 0.21.34
+    version: 0.21.36
     group: starci
     install: registry
     side: fe
@@ -52,28 +52,28 @@ pins:
     source: packages/next-i18n/package.json
     why: 'the next-intl stack of every front end (fe-stack i18n, owner:next-i18n-package): defineI18n over the locales of the app, the locale-negotiating proxy, the locale-aware navigation, the request config that loads the catalogs of the app and the locale read of the [locale] layout; the app keeps its message catalogs and writes none of the stack.'
   '@starci/eslint-canon-be':
-    version: 3.17.4
+    version: 3.18.1
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.13.16
+    version: 9.14.1
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.21.34
+    version: 0.21.36
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.34
+    version: 0.21.36
     group: starci
     install: registry
     side: fe
@@ -155,7 +155,7 @@ pins:
     source: packages/mail/package.json
     why: 'outgoing mail of a back end: a NestJS module and the Mailer port over SMTP (connect, greeting, socket and total timeouts, STARTTLS required by default, recipient, message and attachment checks, a shared SMTP target policy, coded errors, typed escaping render helpers returning { subject, text, html }), with @starci/mail/testing for its specs; the only importer of nodemailer (R90).'
   '@starci/hfs':
-    version: 5.10.4
+    version: 5.11.1
     group: starci
     install: registry
     side: both

package/runtime/scripts/hfs/declaration-shape.mjs

@@ -149,7 +149,9 @@ function observeBlockProblems(observe) {
         bad.push('observe.reporter must name the optional error reporter');
     return bad;
 }
-const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'modules', 'lexicon', 'observe']);
+const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'modules', 'lexicon', 'observe', 'rulePacks']);
+/** A rule pack hfs.json names (PROJECT-LINT-3): an npm package name, each once. */
+const RULE_PACK_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;
 const RUNTIME_DECLARATION_KEYS = new Set(['hfs', 'kind', 'project']);
 function productDeclarationProblems(declaration, profiles) {
     const bad = [];
@@ -159,6 +161,8 @@ function productDeclarationProblems(declaration, profiles) {
     bad.push(...dbBlockProblems(declaration.db), ...lexiconBlockProblems(declaration.lexicon), ...observeBlockProblems(declaration.observe));
     if (declaration.browser !== undefined && declaration.browser !== true)
         bad.push('browser is `true` when the app has a browser journey (slot app.browser), and is left out otherwise');
+    if (declaration.rulePacks !== undefined && (!Array.isArray(declaration.rulePacks) || declaration.rulePacks.length === 0 || declaration.rulePacks.some((name) => typeof name !== 'string' || !RULE_PACK_NAME.test(name)) || new Set(declaration.rulePacks).size !== declaration.rulePacks.length))
+        bad.push('rulePacks is a non-empty list of the installed rule pack packages the app adds its laws with, each once (PROJECT-LINT-3)');
     if (declaration.modules !== undefined && declaration.modules !== 'data')
         bad.push('modules is `"data"` when the app keeps its modules as data (seeds, no rendered registry package), and is left out otherwise');
     if (declaration.kind !== APP_KIND)

package/runtime/scripts/lib/rule-packs.mjs

@@ -0,0 +1,243 @@
+// rule-packs.mjs - an app's rule packs (PROJECT-LINT-3): the packages hfs.json `rulePacks` names, each adding the app's own laws to the harness's
+// gates without a local rule in a tool config. A pack is an installed package that exports `./rule-pack`, an ES module whose default export is
+//   { schema: 'starci/rule-pack@1', name: '<the package name>', rules: [<rule>, ...] }
+// and every rule carries an id (`NIVO-BLOCK-1`), a finding code (`NIVO_BLOCK_INCOMPLETE`), a severity (error or warning), the spec that proves it
+// (a file of the package) and its doc (a file of the package or an https link), plus exactly one engine:
+//   check   a machine rule `(context) => findings` of the hfs family: `starci app check` runs it over the tracked files (context.files, context.read)
+//   eslint  { name, rule, sides } an ESLint rule the canon factories (eslint-canon-be, eslint-canon-fe, the packages config) load for the sides it names
+// A pack only adds: a rule with any other key (an `off`, `overrides` or `disable`), a code the harness already reports, or an id or code another
+// pack uses is refused (HFS_RULE_PACK_INVALID, R381) and the pack lends nothing. Pack findings go through the same policy as the harness's own:
+// a check rule is an hfs finding (blocking on every branch), an eslint rule a lint finding (report under a branch profile, held by the ratchet).
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+export const RULE_PACK_SCHEMA = 'starci/rule-pack@1';
+/** The subpath a pack exports its manifest at. */
+export const RULE_PACK_ENTRY = 'rule-pack';
+/** The sides an eslint pack rule may name: the two side folders and the root packages. */
+export const PACK_SIDES = Object.freeze(['be', 'fe', 'packages']);
+const RULE_KEYS = new Set(['id', 'code', 'severity', 'spec', 'doc', 'check', 'eslint']);
+const ID = /^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+$/u;
+const CODE = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/u;
+const ESLINT_NAME = /^[a-z][a-z0-9-]*$/u;
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;
+const plain = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : null);
+const FAILURE_CODES = new URL('../../modules/kernel/failure-codes.yaml', import.meta.url);
+let harnessCodes = null;
+/**
+ * Every code the harness reports (the top-level keys of its failure-code catalog), the codes a pack may not take; empty where the catalog is not
+ * shipped (a canon package's runtime copy), where the app check refuses such a pack instead.
+ */
+export function reservedCodes() {
+    if (harnessCodes === null) {
+        let catalog = '';
+        try {
+            catalog = fs.readFileSync(FAILURE_CODES, 'utf8');
+        }
+        catch { /* not shipped beside this copy */ }
+        harnessCodes = new Set([...catalog.matchAll(/^([A-Z][A-Z0-9_]+):\s*$/gmu)].map((match) => match[1]));
+    }
+    return harnessCodes;
+}
+/** The app root above `start` (a side folder or the root itself): the nearest folder whose hfs.json declares kind app; null when there is none. */
+export function appRootOf(start) {
+    for (let dir = path.resolve(start);; dir = path.dirname(dir)) {
+        try {
+            const declared = JSON.parse(fs.readFileSync(path.join(dir, 'hfs.json'), 'utf8'));
+            if (declared.kind === 'app')
+                return dir;
+        }
+        catch { /* no declaration here: one folder up */ }
+        if (path.dirname(dir) === dir)
+            return null;
+    }
+}
+/** The pack names hfs.json `rulePacks` declares (its shape is judged by the declaration check). */
+export function declaredRulePacks(appRoot) {
+    try {
+        const declared = JSON.parse(fs.readFileSync(path.join(appRoot, 'hfs.json'), 'utf8'));
+        return Array.isArray(declared.rulePacks) ? declared.rulePacks.filter((name) => typeof name === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The problems of one rule entry of pack `pack` (whose folder is `root`), or the rule when it is sound. */
+function judgeRule(pack, root, entry, at) {
+    const where = `rule ${String(at)}`;
+    if (!plain(entry))
+        return { problems: [`${where} is not an object`] };
+    const problems = [];
+    const extra = Object.keys(entry).filter((key) => !RULE_KEYS.has(key));
+    if (extra.length > 0)
+        problems.push(`${where} has ${extra.join(', ')}: a pack only adds rules, it never turns one off, overrides or lowers it (keys ${[...RULE_KEYS].join(', ')})`);
+    const id = text(entry['id']), code = text(entry['code']), spec = text(entry['spec']), doc = text(entry['doc']);
+    const label = id ?? where;
+    if (id === null || !ID.test(id))
+        problems.push(`${where}: id must be an upper-case law id such as NIVO-BLOCK-1`);
+    if (code === null || !CODE.test(code))
+        problems.push(`${label}: code must be an upper-case finding code such as NIVO_BLOCK_INCOMPLETE`);
+    const severity = entry['severity'];
+    if (severity !== 'error' && severity !== 'warning')
+        problems.push(`${label}: severity must be error or warning`);
+    const inPack = (file) => { const resolved = path.resolve(root, file); return resolved.startsWith(`${path.resolve(root)}${path.sep}`) && fs.existsSync(resolved); };
+    if (spec === null || !inPack(spec))
+        problems.push(`${label}: spec must name the file of the package that proves the rule (${spec ?? 'none'} is not there)`);
+    if (doc === null || !(/^https:\/\/\S+$/u.test(doc) || inPack(doc)))
+        problems.push(`${label}: doc must be a file of the package or an https link (${doc ?? 'none'})`);
+    const check = entry['check'];
+    const eslint = entry['eslint'];
+    if ((check === undefined) === (eslint === undefined))
+        problems.push(`${label}: a rule has exactly one engine, check (a machine rule of the app check) or eslint (a rule the canon factories load)`);
+    if (check !== undefined && typeof check !== 'function')
+        problems.push(`${label}: check must be a function (context) => findings`);
+    let lint;
+    if (eslint !== undefined) {
+        const name = plain(eslint) ? text(eslint['name']) : null;
+        const rule = plain(eslint) ? eslint['rule'] : undefined;
+        const sides = plain(eslint) && Array.isArray(eslint['sides']) ? eslint['sides'] : [];
+        if (name === null || !ESLINT_NAME.test(name))
+            problems.push(`${label}: eslint.name must be a kebab-case rule name`);
+        if (!plain(rule) || typeof rule['create'] !== 'function')
+            problems.push(`${label}: eslint.rule must be an ESLint rule module with create()`);
+        if (sides.length === 0 || sides.some((side) => !PACK_SIDES.includes(side)))
+            problems.push(`${label}: eslint.sides must name some of ${PACK_SIDES.join(', ')}`);
+        if (name !== null && plain(rule))
+            lint = { name, rule: rule, sides: sides };
+    }
+    if (problems.length > 0)
+        return { problems };
+    return { rule: { pack, id: id, code: code, severity: severity, spec: spec, doc: doc, ...(typeof check === 'function' ? { check: check } : {}), ...(lint === undefined ? {} : { eslint: lint }) }, problems: [] };
+}
+/**
+ * The rule packs of the app at `appRoot`, loaded through the app's own install (a pack is an ES module required synchronously, so a pack has no
+ * top-level await) and judged. `reserved` holds the codes the harness reports: a pack never reuses one.
+ */
+export function loadRulePacks(appRoot, reserved = reservedCodes()) {
+    const result = { rules: [], problems: [] };
+    const names = declaredRulePacks(appRoot);
+    const ids = new Map(), codes = new Map();
+    const requireHere = createRequire(path.join(appRoot, 'package.json'));
+    for (const name of names) {
+        const fail = (message) => { result.problems.push({ pack: name, message }); };
+        if (!PACKAGE_NAME.test(name)) {
+            fail('is not a package name');
+            continue;
+        }
+        let manifest, root;
+        try {
+            root = path.dirname(requireHere.resolve(`${name}/package.json`));
+            const loaded = requireHere(`${name}/${RULE_PACK_ENTRY}`);
+            manifest = loaded.default ?? loaded;
+        }
+        catch (error) {
+            fail(`cannot be loaded from the app's install (${name}/${RULE_PACK_ENTRY}): ${String(error?.message ?? error).split('\n')[0]}`);
+            continue;
+        }
+        if (!plain(manifest) || manifest['schema'] !== RULE_PACK_SCHEMA) {
+            fail(`its ${RULE_PACK_ENTRY} export is not a ${RULE_PACK_SCHEMA} manifest`);
+            continue;
+        }
+        if (manifest['name'] !== name) {
+            fail(`its manifest names ${String(manifest['name'])}, not the package`);
+            continue;
+        }
+        const extra = Object.keys(manifest).filter((key) => !['schema', 'name', 'rules'].includes(key));
+        if (extra.length > 0) {
+            fail(`its manifest has ${extra.join(', ')}: a pack holds only schema, name and the rules it adds`);
+            continue;
+        }
+        const entries = Array.isArray(manifest['rules']) ? manifest['rules'] : [];
+        if (entries.length === 0) {
+            fail('adds no rule');
+            continue;
+        }
+        const judged = entries.map((entry, at) => judgeRule(name, root, entry, at));
+        const problems = judged.flatMap((one) => one.problems);
+        const sound = judged.flatMap((one) => (one.rule === undefined ? [] : [one.rule]));
+        for (const [at, rule] of sound.entries()) {
+            if (sound.findIndex((other) => other.id === rule.id) < at)
+                problems.push(`${rule.id}: the id is also a rule of ${name}`);
+            if (sound.findIndex((other) => other.code === rule.code) < at)
+                problems.push(`${rule.id}: ${rule.code} is also a code of ${name}`);
+            if (reserved.has(rule.code))
+                problems.push(`${rule.id}: ${rule.code} is a code the harness reports; a pack adds its own codes and never stands in for a harness rule`);
+            const otherId = ids.get(rule.id), otherCode = codes.get(rule.code);
+            if (otherId !== undefined)
+                problems.push(`${rule.id}: the id is also a rule of ${otherId}`);
+            if (otherCode !== undefined)
+                problems.push(`${rule.id}: ${rule.code} is also a code of ${otherCode}`);
+        }
+        if (problems.length > 0) {
+            for (const message of problems)
+                fail(message);
+            continue;
+        }
+        for (const rule of sound) {
+            ids.set(rule.id, name);
+            codes.set(rule.code, name);
+            result.rules.push(rule);
+        }
+    }
+    return result;
+}
+/** One plugin object per pack and rule set, so two blocks of one config that name a pack hand ESLint the same plugin. */
+const plugins = new Map();
+const pluginOf = (pack, rules) => {
+    const key = `${pack}|${rules.map((rule) => rule.id).join(',')}`;
+    let made = plugins.get(key);
+    if (made === undefined) {
+        made = { rules: Object.fromEntries(rules.map((rule) => [rule.eslint?.name, rule.eslint?.rule])) };
+        plugins.set(key, made);
+    }
+    return made;
+};
+/**
+ * The flat-config blocks that load the eslint rules of the app's packs for `side`, for a canon factory: one plugin per pack (named by the package)
+ * and each rule at its severity. Throws when a pack is refused: a lint run never guesses which of an app's laws hold.
+ */
+export function packEslintConfigs(start, side, files = ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}']) {
+    const appRoot = appRootOf(start);
+    if (appRoot === null || declaredRulePacks(appRoot).length === 0)
+        return [];
+    const packs = loadRulePacks(appRoot);
+    if (packs.problems.length > 0)
+        throw new Error(`HFS_RULE_PACK_INVALID: ${packs.problems.map((problem) => `${problem.pack} ${problem.message}`).join('; ')} (hfs.json rulePacks, PROJECT-LINT-3)`);
+    const byPack = new Map();
+    for (const rule of packs.rules)
+        if (rule.eslint?.sides.includes(side))
+            byPack.set(rule.pack, [...(byPack.get(rule.pack) ?? []), rule]);
+    return [...byPack].map(([pack, rules]) => ({
+        files: [...files],
+        plugins: { [pack]: pluginOf(pack, rules) },
+        rules: Object.fromEntries(rules.map((rule) => [`${pack}/${rule.eslint?.name}`, rule.severity === 'error' ? 'error' : 'warn'])),
+    }));
+}
+/** The findings of the check rules of the app's packs over `files`, and one HFS_RULE_PACK_INVALID per refused pack or per rule that threw. */
+export function rulePackFindings({ repoRoot, files, reserved, read }) {
+    const packs = loadRulePacks(repoRoot, reserved);
+    const out = packs.problems.map((problem) => ({ code: RULE_PACK_INVALID, level: 'error', path: 'hfs.json', message: `hfs.json rulePacks: ${problem.pack} ${problem.message} (R381, PROJECT-LINT-3)` }));
+    const context = Object.freeze({ repoRoot, files: Object.freeze([...files]), read });
+    for (const rule of packs.rules) {
+        if (rule.check === undefined)
+            continue;
+        let found;
+        try {
+            found = rule.check(context);
+        }
+        catch (error) {
+            out.push({ code: RULE_PACK_INVALID, level: 'error', path: 'hfs.json', message: `hfs.json rulePacks: ${rule.pack} ${rule.id} threw (${String(error?.message ?? error).split('\n')[0]}); a rule that cannot judge is no rule (R381)` });
+            continue;
+        }
+        for (const finding of Array.isArray(found) ? found : []) {
+            if (!plain(finding) || text(finding.path) === null || text(finding.message) === null) {
+                out.push({ code: RULE_PACK_INVALID, level: 'error', path: 'hfs.json', message: `hfs.json rulePacks: ${rule.pack} ${rule.id} returned a finding without a path and a message (R381)` });
+                continue;
+            }
+            out.push({ code: rule.code, level: rule.severity, path: String(finding.path), message: `${String(finding.message)} (${rule.id}, ${rule.doc})`, ...(typeof finding.line === 'number' ? { line: finding.line } : {}), ...(typeof finding.column === 'number' ? { column: finding.column } : {}) });
+        }
+    }
+    return out;
+}
+export const RULE_PACK_INVALID = 'HFS_RULE_PACK_INVALID';