@starci/eslint-canon-fe 9.13.4 → 9.13.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 9.13.6 - 2026-11-04
+
+- Changed: the runtime copies carry the module shape of `be.integrations.passport` in the package slot manifest and the canon pins of `@starci/hfs` 5.8.0.
+
+## 9.13.5 - 2026-11-04
+
+- Changed: the runtime copy of the canon pins names `@starci/hfs` 5.7.1 and the release-7a versions.
+
 ## 9.13.4 - 2026-11-04
 
 - Changed: the runtime copy of the canon pins names the release-6 versions.

package/package.json

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

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.21
+    version: 0.21.23
     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.15.4
+    version: 3.16.0
     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.4
+    version: 9.13.6
     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.21
+    version: 0.21.23
     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.21
+    version: 0.21.23
     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.7.0
+    version: 5.8.0
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -2044,8 +2044,8 @@ slots:
     tracked: tracked
     tier: integrations
     owner: true
-    requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.registration.ts]   # Secrets, no defaults (R44); options and named injectors (R83); the kit and the module over @starci/auth
-    allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.registration.ts, errors/]
+    requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.module-definition.ts, passport.module.ts]   # Secrets, no defaults (R44); options and named injectors (R83); the kit and the module over @starci/auth
+    allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.module-definition.ts, passport.module.ts, errors/]
     logic: [passport.kit.ts]   # the verifier mapping over the package: measured at 100 per file
     tests: unit-beside
     rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_AUTH_JWT_OWN_JWKS, BE_AUTH_REFRESH_COOKIE]

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

@@ -5,6 +5,13 @@ import { kindShapeProblems, patternShapeProblems } from './declaration-slots.mjs
 import { byCodeUnit } from '../lib/list.mjs';
 /** Shape problems of the optional hfs.json `db` block of a lite app: the environment variable naming its database, its image, forced RLS and its application role. */
 const isStringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.trim());
+/** One owner ruling on a migration's destructive DDL: the exact file, the exact objects, the reason and the date the owner ruled it. */
+const isDestructiveRuling = (ruling) => isPlainObject(ruling)
+    && typeof ruling.migration === 'string' && /^db\/migrations\/\d{14}_[a-z0-9_-]+\.sql$/.test(ruling.migration)
+    && isStringList(ruling.objects) && ruling.objects.length > 0
+    && typeof ruling.reason === 'string' && ruling.reason.trim() !== ''
+    && typeof ruling.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(ruling.date)
+    && Object.keys(ruling).every((key) => ['migration', 'objects', 'reason', 'date'].includes(key));
 function dbBlockProblems(block) {
     if (block === undefined)
         return [];
@@ -12,7 +19,7 @@ function dbBlockProblems(block) {
         return ['db must be an object'];
     const bad = [];
     for (const key of Object.keys(block))
-        if (!['urlEnv', 'image', 'forceRls', 'forceRlsExemptions', 'appRole'].includes(key))
+        if (!['urlEnv', 'image', 'forceRls', 'forceRlsExemptions', 'appRole', 'destructiveRulings'].includes(key))
             bad.push(`db has unknown key ${key}`);
     if (block.urlEnv !== undefined && (typeof block.urlEnv !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(block.urlEnv)))
         bad.push('db.urlEnv must name an UPPER_CASE environment variable');
@@ -24,6 +31,8 @@ function dbBlockProblems(block) {
         bad.push('db.appRole must name a role');
     if (block.forceRlsExemptions !== undefined && !Array.isArray(block.forceRlsExemptions))
         bad.push('db.forceRlsExemptions must be a list of { table, reason }');
+    if (block.destructiveRulings !== undefined && !(Array.isArray(block.destructiveRulings) && block.destructiveRulings.every(isDestructiveRuling)))
+        bad.push('db.destructiveRulings must be a list of { migration, objects, reason, date } naming one db/migrations file, the objects it destroys, why and the date the owner ruled it (YYYY-MM-DD)');
     return bad;
 }
 function appShapeProblems(apps, at, side, names) {

package/runtime/scripts/hfs/rules/database-constants.mjs

@@ -11,6 +11,8 @@ export const DB_ARCHIVE_MUTATED = 'DB_ARCHIVE_MUTATED';
 export const DB_PGMQ_DECLARED = 'DB_PGMQ_DECLARED';
 export const DB_EXTENSION_ALLOWED = 'DB_EXTENSION_ALLOWED';
 export const DB_MIGRATION_DESTRUCTIVE = 'DB_MIGRATION_DESTRUCTIVE';
+/** An owner ruling (hfs.json db.destructiveRulings) whose destroyed object is still referenced, or that names an object or migration it cannot prove. */
+export const DB_DESTRUCTIVE_RULING_UNPROVEN = 'DB_DESTRUCTIVE_RULING_UNPROVEN';
 export const HFS_SEED_PII = 'HFS_SEED_PII';
 export const DB_VAULT_WRITE = 'DB_VAULT_WRITE';
 

package/runtime/scripts/hfs/rules/database-migrations.mjs

@@ -7,8 +7,8 @@ import { tag } from '../../api/git/tag.mjs';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
 import { eachInOrder, findInOrder } from '../../lib/in-order.mjs';
 import { sameText } from '../../lib/same-text.mjs';
-import { found, readText } from './read.mjs';
-import { DB_MIGRATION_DESTRUCTIVE, DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
+import { found, readJson, readText } from './read.mjs';
+import { DB_DESTRUCTIVE_RULING_UNPROVEN, DB_MIGRATION_DESTRUCTIVE, DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
@@ -579,18 +579,42 @@ function migrationDestructiveObjects(text) {
         return destructiveObjects(statement).filter((object) => !alterOfNewColumn(object, added));
     });
 }
-function destructiveFileFindings(file, text, references) {
-    const contract = /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/.test(file);
+const CONTRACT_MIGRATION = /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/;
+/**
+ * The owner rulings of hfs.json `db.destructiveRulings`, by migration file: the exact objects each may destroy outside a contract migration,
+ * held only while the same proof a contract migration gets finds them unreferenced. The declaration shape judges reason and date.
+ */
+function destructiveRulings(repoRoot) {
+    const listed = readJson(repoRoot, 'hfs.json')?.db?.destructiveRulings;
+    const rulings = new Map();
+    for (const ruling of Array.isArray(listed) ? listed : []) {
+        if (typeof ruling?.migration === 'string' && Array.isArray(ruling.objects))
+            rulings.set(ruling.migration, new Set(ruling.objects.filter((name) => typeof name === 'string')));
+    }
+    return rulings;
+}
+/** A ruled object is accepted while no be/src source references it; a reference makes the ruling unproven. */
+function ruledObjectFinding(file, object, references) {
+    const reference = references.find(({ scopes }) => referencesObject(scopes, object));
+    return reference ? found(DB_DESTRUCTIVE_RULING_UNPROVEN, file, `${file}:${object.line} destroys ${object.name} under hfs.json db.destructiveRulings, but ${reference.file} still references it; the ruling holds only while its targets are unreferenced`, { line: object.line, object: object.name, reference: reference.file }) : null;
+}
+function destructiveFileFindings(file, text, references, ruled = new Set()) {
+    const contract = CONTRACT_MIGRATION.test(file);
     const seen = new Set();
     const objects = migrationDestructiveObjects(text);
-    return objects.flatMap((object) => {
+    const findings = objects.flatMap((object) => {
         const key = `${object.line}:${object.kind}:${object.name}`;
         if (seen.has(key))
             return [];
         seen.add(key);
-        const finding = destructiveObjectFinding(file, object, contract, references);
+        const finding = !contract && ruled.has(object.name) ? ruledObjectFinding(file, object, references) : destructiveObjectFinding(file, object, contract, references);
         return finding ? [finding] : [];
     });
+    for (const name of ruled) {
+        if (!objects.some((object) => object.name === name))
+            findings.push(found(DB_DESTRUCTIVE_RULING_UNPROVEN, file, `hfs.json db.destructiveRulings names ${name} for ${file}, which the migration does not destroy; a ruling names exactly the objects its migration destroys`, { object: name }));
+    }
+    return findings;
 }
 const BE_SQL_SOURCE = /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/;
 /** The tag glob of a release (release.tagPrefix defaults to v). */
@@ -605,7 +629,8 @@ const RELEASE_TAG_GLOB = 'v*';
  * DB_MIGRATION_DESTRUCTIVE (R259), a hard blocker: ship the code change in one release and its contract migration in the next.
  */
 export async function contractReleaseFindings({ repoRoot, migrations, git }) {
-    const contracts = migrations.filter((file) => /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/.test(file));
+    const rulings = destructiveRulings(repoRoot);
+    const contracts = migrations.filter((file) => CONTRACT_MIGRATION.test(file) || rulings.has(file));
     if (!contracts.length)
         return [];
     const previous = await runGit(git, repoRoot, ['previous-release', RELEASE_TAG_GLOB]);
@@ -631,9 +656,11 @@ export async function contractReleaseFindings({ repoRoot, migrations, git }) {
         const text = readText(repoRoot, file);
         if (text === null)
             return [];
-        return migrationDestructiveObjects(text).flatMap((object) => {
+        // a ruled migration is judged here for its ruled objects only: its other objects are refused at HEAD already
+        const ruled = CONTRACT_MIGRATION.test(file) ? undefined : rulings.get(file);
+        return migrationDestructiveObjects(text).filter((object) => ruled === undefined || ruled.has(object.name)).flatMap((object) => {
             const reference = references.find(({ scopes }) => referencesObject(scopes, object));
-            return reference ? [found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
+            return reference ? [found(ruled === undefined ? DB_MIGRATION_DESTRUCTIVE : DB_DESTRUCTIVE_RULING_UNPROVEN, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
         });
     });
 }
@@ -644,8 +671,14 @@ export function destructiveMigrationFindings({ repoRoot, migrations, files }) {
     if (sources.length && !ts)
         return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'destructive migration checks require the TypeScript parser to read be/src references')];
     const references = ts ? sources.map((file) => ({ file, scopes: sourceNameScopes(ts, readText(repoRoot, file) ?? '', file) })) : [];
-    return migrations.flatMap((file) => {
+    const rulings = destructiveRulings(repoRoot);
+    const findings = migrations.flatMap((file) => {
         const text = readText(repoRoot, file);
-        return text === null ? [] : destructiveFileFindings(file, text, references);
+        return text === null ? [] : destructiveFileFindings(file, text, references, rulings.get(file));
     });
+    for (const migration of rulings.keys()) {
+        if (!migrations.includes(migration))
+            findings.push(found(DB_DESTRUCTIVE_RULING_UNPROVEN, 'hfs.json', `hfs.json db.destructiveRulings names ${migration}, which is no active migration; a ruling names the exact file it covers`, { migration }));
+    }
+    return findings;
 }