@starci/hfs 4.11.18 → 4.11.19

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 4.11.19 - 2026-10-30
+
+- Fixed: `HFS_SCHEDULE_UNDECLARED` (R268) reads an application SQL template whose `${}` sits where Postgres wants an identifier (`LISTEN ${channel}`, `SET x = ${n}`): the template is read with each `${}` as NULL, and when that does not parse, again with each as an identifier (`stacks-release.mjs` `templateObservations`). Such a statement was taken for an undeclared pg_cron job. A bare interpolated function name (`FROM ${fn}(...)`) still fails closed, since it may be `cron.schedule`; the skeleton's `callDbFunction` quotes `"${schema}"."${name}"` and parses as it is.
+- Fixed: SQL named in a same-file `const` before its `query`/`execute` call is judged as if inline (`sqlConstants`); moving the text out of the call no longer hid it from the scanner. Specs: `src/hfs-stacks-release.spec.mjs`.
+
 ## 4.11.18 - 2026-10-30
 
 - Fixed: `HFS_STACKS_SHAPE` (R10) accepts the sealed member `app secret set` writes, `<env>/secrets/<slug>.enc.yaml` (ruling app-secrets-one-standard, `scripts/lib/sealed-member.mjs`), beside the legacy `<slug>.enc`. The `.starcistacks` slot (`knowledge/hfs/slots.yaml`, both editions) allowed only `<slug>.enc`, so every standard member was refused; the messages and `goesTo` name `.enc.yaml`. Spec: `src/hfs-stacks-shape.spec.mjs` holds one of each.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.11.18",
+  "version": "4.11.19",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

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

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.15.30
+    version: 0.15.31
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.8.17
+    version: 3.8.18
     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.5.19
+    version: 9.5.20
     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.15.30
+    version: 0.15.31
     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.15.30
+    version: 0.15.31
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.11.18
+    version: 4.11.19
     group: starci
     install: registry
     side: both

package/runtime/scripts/hfs/rules/stacks-release.mjs

@@ -269,25 +269,61 @@ function sqlObservations(text, file) {
 
 function sourceSqlObservations(source, file) {
   const observations = [];
+  const constants = sqlConstants(source);
   const visit = node => {
     if (ts.isCallExpression(node) && /(?:^|\.)(?:query|execute)$/.test(node.expression.getText())) {
       const argument = unwrap(node.arguments[0]);
-      const text = sqlTemplateText(argument);
-      if (text !== null) observations.push(...sqlObservations(text, file));
+      const text = argument && ts.isIdentifier(argument) ? constants.get(argument.text) : argument;
+      if (text) observations.push(...templateObservations(text, file));
     }
     if (ts.isTaggedTemplateExpression(node) && /(?:^|\.)sql$/.test(node.tag.getText()))
-      observations.push(...sqlObservations(sqlTemplateText(node.template), file));
+      observations.push(...templateObservations(node.template, file));
     ts.forEachChild(node, visit);
   };
   visit(source);
   return observations;
 }
 
-function sqlTemplateText(node) {
-  if (!node) return null;
-  if (ts.isStringLiteralLike(node)) return node.text;
-  if (!ts.isTemplateExpression(node)) return null;
-  return node.head.text + node.templateSpans.map(span => `NULL${span.literal.text}`).join('');
+/** The file's `const NAME = <string or template>` statements, so SQL named before its query call is judged as if inline. */
+function sqlConstants(source) {
+  const constants = new Map();
+  const visit = node => {
+    if (ts.isVariableDeclarationList(node) && (node.flags & ts.NodeFlags.Const)) {
+      for (const declaration of node.declarations) {
+        const value = unwrap(declaration.initializer);
+        if (ts.isIdentifier(declaration.name) && value && (ts.isStringLiteralLike(value) || ts.isTemplateExpression(value)))
+          constants.set(declaration.name.text, value);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return constants;
+}
+
+const DYNAMIC = 'starci_dynamic_sql';
+
+/**
+ * The observations of an application SQL text. A template is read with each `${}` as NULL; when that does not parse (an
+ * interpolated identifier: `LISTEN ${channel}`, `SET x = ${n}`, `FROM ${fn}(...)`), it is read again with each `${}` as an
+ * identifier. A function whose name is interpolated bare may be pg_cron, so it stays an unknown observation; the skeleton's
+ * `callDbFunction` quotes `"${schema}"."${name}"`, which parses as it is.
+ */
+function templateObservations(node, file) {
+  if (ts.isStringLiteralLike(node)) return sqlObservations(node.text, file);
+  if (!ts.isTemplateExpression(node)) return [];
+  const spell = placeholder => node.head.text + node.templateSpans.map(span => `${placeholder}${span.literal.text}`).join('');
+  const nulls = spell('NULL');
+  if (parseSql(nulls)) return sqlObservations(nulls, file);
+  const named = spell(DYNAMIC);
+  const tree = parseSql(named);
+  if (!tree) return [{ id: null, cadence: null, at: file }];
+  let dynamicCall = false;
+  walkSql(tree, value => {
+    if (value.FuncCall && (value.FuncCall.funcname ?? []).some(part => part.String?.sval === DYNAMIC)) dynamicCall = true;
+  });
+  if (dynamicCall) return [{ id: null, cadence: null, at: file }];
+  return sqlObservations(named, file);
 }
 
 function recurringObservations({ doc, repoRoot, files, file, issues }) {