@starci/eslint-grammar-offset-pop 0.12.13 → 0.13.0

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

@@ -0,0 +1,157 @@
+// declaration-shape.mjs - the dependency-free hfs.json shape validation used by the HFS slot loader. Semantic checks
+// against a loaded manifest remain in slots.mjs; this module mirrors modules/schemas/hfs-repo.schema.yaml only.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { APP_KIND, connectionShapeProblems, NAME, PACKAGE_NAME, RUNTIME_KIND, SLOT_ID } from './manifest-shape.mjs';
+import { kindShapeProblems, patternShapeProblems } from './declaration-slots.mjs';
+import { byCodeUnit } from '../lib/list.mjs';
+
+/** Shape problems of the optional hfs.json `supabase` block whose auth posture DB_CONFIG_POLICY checks. */
+const isSupabaseStringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.trim());
+
+function supabaseValueProblems(block) {
+  const bad = [];
+  if (block.enableSignup !== undefined && typeof block.enableSignup !== 'boolean') bad.push('supabase.enableSignup must be true or false');
+  if (block.jwtExpiry !== undefined && !(Number.isInteger(block.jwtExpiry) && block.jwtExpiry > 0 && block.jwtExpiry <= 3600)) bad.push('supabase.jwtExpiry must be an integer of seconds, 3600 at most');
+  if (block.siteUrl !== undefined && (typeof block.siteUrl !== 'string' || !block.siteUrl.trim())) bad.push('supabase.siteUrl must be a URL string');
+  for (const key of ['redirectUrls', 'forceRls']) if (block[key] !== undefined && !isSupabaseStringList(block[key])) bad.push(`supabase.${key} must be a list of strings`);
+  return bad;
+}
+
+function supabaseBlockProblems(block) {
+  if (block === undefined) return [];
+  if (!isPlainObject(block)) return ['supabase must be an object'];
+  const bad = [];
+  for (const key of Object.keys(block)) if (!['enableSignup', 'jwtExpiry', 'siteUrl', 'redirectUrls', 'forceRls'].includes(key)) bad.push(`supabase has unknown key ${key}`);
+  bad.push(...supabaseValueProblems(block));
+  return bad;
+}
+
+function appShapeProblems(apps, at, side, names) {
+  const bad = [];
+  if (!Array.isArray(apps) || !apps.length) {
+    bad.push(`${at}.apps must list every ${side}/apps/<name> with its kind`);
+    return bad;
+  }
+  apps.forEach((app, index) => {
+    if (!isPlainObject(app) || !NAME.test(String(app.name)) || !NAME.test(String(app.kind)) || Object.keys(app).some((key) => key !== 'name' && key !== 'kind')) bad.push(`${at}.apps[${index}] must be {name, kind}`);
+    else if (names.has(app.name)) bad.push(`app ${app.name} is declared twice (${names.get(app.name)} and ${side})`);
+    else names.set(app.name, side);
+  });
+  return bad;
+}
+
+function connectionProblems(side, value) {
+  const bad = [];
+  if (side !== 'be') {
+    bad.push('connections belong to the be side');
+    return bad;
+  }
+  const list = Array.isArray(value.connections) ? value.connections : null;
+  const shape = connectionShapeProblems(list, value.apps);
+  if (shape.length) {
+    bad.push(...shape);
+    return bad;
+  }
+  if (new Set(list.map((connection) => connection.name)).size !== list.length) bad.push('connections names must be unique');
+  for (const a of list) for (const b of list) if (a !== b && `${b.envPrefix}_`.startsWith(`${a.envPrefix}_`)) bad.push(`connections ${a.name} and ${b.name} share env keys (${a.envPrefix}_ covers ${b.envPrefix}_)`);
+  return bad;
+}
+
+/** Whether a declared list is present but not a list of distinct entries that all satisfy `valid`. */
+const isBadUniqueList = (list, valid) => list !== undefined && (!Array.isArray(list) || !list.every((entry) => valid(entry)) || new Set(list).size !== list.length);
+
+function validExtraPackage(entry) {
+  return isPlainObject(entry) && Object.keys(entry).every(key => key === 'name' || key === 'reason')
+    && typeof entry.name === 'string' && entry.name.length <= 214 && PACKAGE_NAME.test(entry.name)
+    && typeof entry.reason === 'string' && entry.reason.trim().length > 0;
+}
+
+function extraPackageProblems(side, entries) {
+  if (entries === undefined) return [];
+  if (side !== 'fe') return ['extraPackages belong to the fe side'];
+  if (!Array.isArray(entries) || !entries.every(validExtraPackage)) return ['sides.fe.extraPackages must be a list of {name, reason} with a package name and a nonempty reason'];
+  return [];
+}
+
+/** `sides.be.queueOutbox`: the app's own queue outbox ({table, enqueue, queueParameter}), which a pg_cron tick may enqueue through (R258); it needs the redis backing the relay hands rows to. */
+function queueOutboxProblems(side, value) {
+  const declared = value.queueOutbox;
+  if (declared === undefined) return [];
+  if (side !== 'be') return ['queueOutbox belongs to the be side'];
+  const name = (item) => typeof item === 'string' && /^[a-z_][a-z0-9_]*\.[a-z_][a-z0-9_]*$/.test(item);
+  const bad = [];
+  if (!isPlainObject(declared) || Object.keys(declared).sort().join() !== 'enqueue,queueParameter,table' || !name(declared.table) || !name(declared.enqueue) || !/^[a-z_][a-z0-9_]*$/.test(String(declared.queueParameter))) bad.push('sides.be.queueOutbox must be {table: <schema>.<table>, enqueue: <schema>.<function>, queueParameter: <parameter name>}');
+  if (!(value.backing ?? []).includes('redis')) bad.push('sides.be.queueOutbox needs sides.be.backing to declare redis, which the relay hands its rows to');
+  return bad;
+}
+
+function grammarProblems(side, grammar) {
+  if (grammar === undefined) return [];
+  if (side !== 'fe') return ['grammar belongs to the fe side'];
+  return typeof grammar === 'string' && NAME.test(grammar) ? [] : ['sides.fe.grammar must name a Grammar family'];
+}
+
+function declarationSideProblems(side, value, names) {
+  const bad = [];
+  const at = `sides.${side}`;
+  if (!isPlainObject(value)) return [`${at} must be an object`];
+  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing', 'queueOutbox'].includes(key)) bad.push(`${at} has unknown key ${key}`);
+  bad.push(...appShapeProblems(value.apps, at, side, names));
+  if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot)))) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
+  if (value.backing !== undefined && side !== 'be') bad.push('backing belongs to the be side');
+  else if (isBadUniqueList(value.backing, (name) => NAME.test(String(name)))) bad.push(`${at}.backing must be a unique list of backing service names`);
+  bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
+  if (isBadUniqueList(value.reads, (read) => typeof read === 'string' && read.length > 0)) bad.push(`${at}.reads must be a unique list of paths`);
+  if (value.connections !== undefined) bad.push(...connectionProblems(side, value));
+  bad.push(...extraPackageProblems(side, value.extraPackages), ...grammarProblems(side, value.grammar), ...queueOutboxProblems(side, value));
+  return bad;
+}
+
+/** Product vocabulary is a declaration, never a switch for a rule. */
+function lexiconBlockProblems(lexicon) {
+  if (lexicon === undefined) return [];
+  if (!isPlainObject(lexicon)) return ['lexicon must be an object'];
+  const bad = [];
+  for (const key of Object.keys(lexicon)) if (key !== 'removed') bad.push(`lexicon has unknown key ${key}`);
+  if (isBadUniqueList(lexicon.removed, (word) => typeof word === 'string' && word.trim().length > 0)) bad.push('lexicon.removed must be a unique list of nonempty words');
+  return bad;
+}
+
+/** Front-end error reporting remains optional in both editions. */
+function observeBlockProblems(observe) {
+  if (observe === undefined) return [];
+  if (!isPlainObject(observe)) return ['observe must be an object'];
+  const bad = [];
+  for (const key of Object.keys(observe)) if (key !== 'reporter') bad.push(`observe has unknown key ${key}`);
+  if (observe.reporter !== undefined && (typeof observe.reporter !== 'string' || !observe.reporter.trim())) bad.push('observe.reporter must name the optional error reporter');
+  return bad;
+}
+
+const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'supabase', 'sides', 'browser', 'lexicon', 'observe']);
+const RUNTIME_DECLARATION_KEYS = new Set(['hfs', 'kind', 'project']);
+
+function productDeclarationProblems(declaration, profiles) {
+  const bad = [];
+  for (const key of Object.keys(declaration)) if (!DECLARATION_KEYS.has(key)) bad.push(`unknown key ${key}`);
+  bad.push(...supabaseBlockProblems(declaration.supabase), ...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.kind !== APP_KIND) bad.push(`kind must be ${APP_KIND} (a product is one app repository with a be and an fe side) or ${RUNTIME_KIND} (the StarCi runtime repository)`);
+  if (!isPlainObject(declaration.sides) || Object.keys(declaration.sides).sort(byCodeUnit).join() !== profiles.join()) { bad.push('sides must declare exactly be and fe'); return bad; }
+  const names = new Map();
+  for (const side of profiles) bad.push(...declarationSideProblems(side, declaration.sides[side], names));
+  return bad;
+}
+
+/** Shape problems of a parsed hfs.json, in the words of modules/schemas/hfs-repo.schema.yaml. */
+export function declarationShapeProblems(declaration, profiles) {
+  const bad = [];
+  if (!isPlainObject(declaration)) return ['hfs.json is not an object'];
+  if (!(Number.isInteger(declaration.hfs) && declaration.hfs >= 1)) bad.push('hfs must be the pinned manifest major (an integer, 1 or more)');
+  if (!NAME.test(String(declaration.project))) bad.push('project must be a project name');
+  if (declaration.kind === RUNTIME_KIND) {
+    for (const key of Object.keys(declaration)) if (!RUNTIME_DECLARATION_KEYS.has(key)) bad.push(`unknown key ${key} (a runtime declaration is {hfs, kind, project})`);
+    return bad;
+  }
+  bad.push(...productDeclarationProblems(declaration, profiles));
+  return bad;
+}

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

@@ -0,0 +1,86 @@
+// declaration-slots.mjs - how an app declaration (hfs.json) switches on the opt-in slots of a side: by name (`optionalSlots`), by app kind
+// (a slot with `appKind`) and by declared pattern (a slot with `pattern: <name>` is enabled by `sides.<side>.patterns: [<name>]`, one
+// mechanism for pattern slots). A cross-cutting pattern can instead be owned by the side's canonical proof scenario catalog.
+// slots.mjs asks this file to judge a side's lists and to say whether a slot is enabled for a repository.
+import { judgedInEdition } from './edition-slots.mjs';
+
+/** The problems of a side's `optionalSlots` and `patterns` against the manifest. */
+export function optionalSlotProblems(manifest, side, s) {
+  const bad = [];
+  for (const id of s.optionalSlots ?? []) {
+    const slot = manifest.slots.find((candidate) => candidate.id === id);
+    if (!slot?.profiles.includes(side)) bad.push(`sides.${side}.optionalSlots names ${id}, which is not a ${side} slot`);
+    else if (slot.presence !== 'opt-in') bad.push(`sides.${side}.optionalSlots names ${id}, which is ${slot.presence}, not opt-in`);
+    else if (slot.appKind !== undefined) bad.push(`sides.${side}.optionalSlots names ${id}; an app of kind ${slot.appKind} enables it`);
+  }
+  for (const name of s.patterns ?? []) {
+    const ownsSlot = manifest.slots.some((slot) => slot.profiles.includes(side) && slot.pattern === name);
+    const ownsProof = Object.hasOwn(manifest.ruleParams?.[side]?.patternScenarios ?? {}, name);
+    if (!ownsSlot && !ownsProof) bad.push(`sides.${side}.patterns names ${name}, which neither a ${side} slot nor its proof scenario catalog declares`);
+  }
+  if (s.kinds !== undefined && side !== 'be') bad.push(`sides.${side}.kinds belongs to the be side`);
+  for (const kind of s.kinds ?? []) {
+    if (!(manifest.triggerKinds ?? []).includes(kind)) bad.push(`sides.${side}.kinds names ${kind}, which is not one of triggerKinds (${(manifest.triggerKinds ?? []).join(', ')})`);
+  }
+  return bad;
+}
+
+/** The problems of a side's `backing` list: every name is admitted by ruleParams.be.backing in this edition. */
+export function backingProblems(manifest, side, s, edition = 'full') {
+  const services = Object.entries(manifest.ruleParams?.be?.backing ?? {})
+    .filter(([, entry]) => judgedInEdition(entry, edition)).map(([name]) => name);
+  return (s.backing ?? []).filter((name) => !services.includes(name))
+    .map((name) => `sides.${side}.backing names ${name}, which is not admitted in edition ${edition} by ruleParams.be.backing (${services.join(', ')})`);
+}
+
+/** The problems of the shape of a side's `patterns` list (a unique list of pattern names). */
+export function patternShapeProblems(s, at, namePattern) {
+  const list = s.patterns;
+  if (list === undefined) return [];
+  return Array.isArray(list) && list.every((value) => namePattern.test(String(value))) && new Set(list).size === list.length ? [] : [`${at}.patterns must be a unique list of pattern names`];
+}
+
+/** The problems of the shape of a side's `kinds` list (a unique list of trigger kind names). */
+export function kindShapeProblems(s, at, namePattern) {
+  const list = s.kinds;
+  if (list === undefined) return [];
+  return Array.isArray(list) && list.every((value) => namePattern.test(String(value))) && new Set(list).size === list.length ? [] : [`${at}.kinds must be a unique list of trigger kind names`];
+}
+
+/** The problems of `ruleParams.be.kindPatterns` (trigger kind -> patterns) and `ruleParams.be.addKinds` (starci app add noun -> {topic, variable, patterns, trigger?, needs?, also?, defaults?, wire?}). */
+export function kindParamProblems(be, triggerKinds) {
+  const kebab = /^[a-z][a-z0-9-]*$/;
+  const names = (list) => Array.isArray(list) && list.every((value) => kebab.test(String(value))) && new Set(list).size === list.length;
+  const bad = [];
+  const patterns = be.kindPatterns;
+  if (patterns === null || typeof patterns !== 'object' || Array.isArray(patterns) || !Object.entries(patterns).every(([kind, list]) => (triggerKinds ?? []).includes(kind) && names(list))) bad.push('ruleParams.be.kindPatterns must map a trigger kind to a unique list of pattern names');
+  const nouns = be.addKinds;
+  const nounOk = (spec) => spec !== null && typeof spec === 'object' && kebab.test(String(spec.topic)) && kebab.test(String(spec.variable)) && names(spec.patterns) && (spec.trigger === undefined || kebab.test(String(spec.trigger))) && (spec.needs === undefined || names(spec.needs)) && (spec.also === undefined || names(spec.also)) && (spec.defaults === undefined || (typeof spec.defaults === 'object' && !Array.isArray(spec.defaults))) && (spec.wire === undefined || (spec.wire !== null && typeof spec.wire === 'object' && ['file', 'import', 'symbol'].every((key) => typeof spec.wire[key] === 'string' && spec.wire[key] !== '')));
+  if (nouns === null || typeof nouns !== 'object' || Array.isArray(nouns) || !Object.entries(nouns).every(([noun, spec]) => kebab.test(noun) && nounOk(spec))) bad.push('ruleParams.be.addKinds must map a noun to {topic, variable, patterns, trigger?, needs?, also?, defaults?}');
+  return bad;
+}
+
+/** The problems of `ruleParams.be.patternScenarios`: a pattern name to a non-empty list of unique kebab-case scenario ids. */
+export function scenarioProblem(scenarios) {
+  const kebab = /^[a-z][a-z0-9-]*$/;
+  const ok = scenarios !== null && typeof scenarios === 'object' && !Array.isArray(scenarios) && Object.entries(scenarios).every(([name, list]) => kebab.test(name) && Array.isArray(list) && list.length > 0 && list.every((id) => kebab.test(String(id))) && new Set(list).size === list.length);
+  return ok ? [] : ['ruleParams.be.patternScenarios must map a pattern name to a non-empty list of unique kebab-case scenario ids'];
+}
+
+/** The problems of the `trigger` of a slot against the manifest's `triggerKinds`: a known kind, on a feature-tier slot only. */
+export function triggerProblems(slot, triggerKinds) {
+  if (slot.trigger === undefined) return [];
+  const bad = [];
+  if (!(triggerKinds ?? []).includes(slot.trigger)) bad.push(`slot ${slot.id}: trigger ${slot.trigger} is not one of triggerKinds`);
+  if (slot.tier !== 'feature') bad.push(`slot ${slot.id}: a trigger belongs to a feature-tier slot`);
+  return bad;
+}
+
+/** Whether an opt-in slot is enabled for the repository: by its app kind, by a connection's provider, by name in optionalSlots, or by its declared pattern. */
+export function declaredSlotEnabled(slot, repo) {
+  if (slot.appKind !== undefined) return repo.apps.some((app) => app.kind === slot.appKind);
+  // A provider declared on any connection (be owns them all today) enables the provider slots of every profile: repo.providers
+  // is the app-wide union the declaration resolver computed; a hand-built repo falls back to its own connections.
+  if (slot.provider !== undefined) return (repo.providers ?? (repo.connections ?? []).map((connection) => connection.provider)).includes(slot.provider);
+  return repo.optionalSlots.includes(slot.id) || (slot.pattern !== undefined && (repo.patterns ?? []).includes(slot.pattern));
+}

package/runtime/scripts/hfs/edition-slots.mjs

@@ -0,0 +1,77 @@
+// edition.mjs - the one edition filter shared by the HFS slot resolver, declaration validation, rule catalog and
+// edition-specific rule parameters. Full is the default; lite changes data views, never the checks that consume them.
+// Lite uses provider adapters and declares Docker Swarm production infrastructure (owner:lite-production-swarm, ruling:R212/case-4).
+// Its overlays exclude the e2e world, and every slot keeps its own `tests`.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { EDITIONS } from './manifest-shape.mjs';
+
+/** The presence of `slot` under edition lite for `profile`: `litePresence`, else the slot's own presence. */
+export function litePresenceOf(slot, profile) {
+  const lp = slot.litePresence;
+  if (lp === undefined) return slot.presence;
+  return isPlainObject(lp) ? (lp[profile] ?? slot.presence) : lp;
+}
+
+/** Whether `slot` exists under `edition` of `manifest` (default: the manifest's own editions). */
+export function slotInEdition(manifest, slot, edition) {
+  return (slot.editions ?? manifest.editions ?? EDITIONS).includes(edition);
+}
+
+/** The slot as `edition` sees it: lite overlays its data, presence and tracking; `tests` stays the slot's own (lite keeps the unit specs). */
+export function effectiveSlot(slot, profile, edition) {
+  if (edition !== 'lite') return slot;
+  const { lite, litePresence, ...base } = slot;
+  const presence = litePresenceOf(slot, profile);
+  let tracked = slot.tracked;
+  if (presence === 'forbidden') tracked = 'external';
+  else if (tracked === 'external') tracked = 'tracked';
+  return { ...base, ...lite, presence, tracked };
+}
+
+/** The template group starci app sync renders `slot` from under `edition`: `liteManagedBy` (else `managedBy`) in lite, `managedBy` otherwise; undefined when unmanaged. */
+export function managedGroupOf(slot, edition) {
+  return edition === 'lite' ? (slot.liteManagedBy ?? slot.managedBy) : slot.managedBy;
+}
+
+/** The declared edition and the vocabulary against which it is validated. */
+export function declarationEdition(manifest, declaration) {
+  const edition = declaration.edition === undefined ? 'full' : declaration.edition;
+  const known = manifest.editions ?? EDITIONS;
+  return { edition, known, valid: known.includes(edition) };
+}
+
+/** Problems of an optional rule-catalog `editions` list, in the catalog schema's words. */
+export function ruleEditionProblems(rule, label) {
+  if (rule.editions === undefined) return [];
+  const bad = [];
+  if (!Array.isArray(rule.editions) || !rule.editions.length) return [`${label}.editions must be a non-empty list`];
+  for (const value of rule.editions) if (!EDITIONS.includes(value)) bad.push(`${label}.editions has ${JSON.stringify(value)}, not one of ${EDITIONS.join(', ')}`);
+  if (new Set(rule.editions).size !== rule.editions.length) bad.push(`${label}.editions repeats a value`);
+  return bad;
+}
+
+/** Whether a catalogued rule owner judges its finding under `edition`; uncatalogued codes always remain judged. */
+export function judgedInEdition(owner, edition = 'full') {
+  return !owner?.editions || owner.editions.includes(edition);
+}
+
+/** Whether the enforcer `kind:id` of the catalog `rules` runs under `edition`: every rule listing it is judged there, and the enforcer row's own `editions` (a rule with several enforcers where only one is full-only) agrees. A lint rule no rule lists runs everywhere. */
+export function enforcerJudgedInEdition(rules, kind, id, edition = 'full') {
+  const owners = rules.filter((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id));
+  return owners.every((rule) => judgedInEdition(rule, edition) && rule.enforcers.filter((enforcer) => enforcer.kind === kind && enforcer.id === id).every((enforcer) => judgedInEdition(enforcer, edition)));
+}
+
+/**
+ * A frozen copy of one profile's parameters, with its lite overrides applied only in the lite edition. A lite key whose base
+ * value and override are both maps merges one level deep (lite.infraOwners restates only the specifiers whose owner changes);
+ * any other value replaces the base.
+ */
+export function editionRuleParams(params, edition) {
+  const { lite, ...base } = params;
+  const merged = edition === 'lite' && lite ? { ...base } : base;
+  if (edition === 'lite' && lite) {
+    for (const [key, value] of Object.entries(lite)) merged[key] = isPlainObject(value) && isPlainObject(base[key]) ? { ...base[key], ...value } : value;
+  }
+  const deepFreeze = (value) => { if (value && typeof value === 'object') { Object.values(value).forEach(deepFreeze); } return Object.freeze(value); };
+  return deepFreeze(structuredClone(merged));
+}