@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/rules/event-tables.mjs

@@ -2,99 +2,101 @@
 import { isDeepStrictEqual } from 'node:util';
 import { nameText } from '../../lib/ts-ast.mjs';
 import { found, readJson, readText } from './read.mjs';
-
 const CODE = 'HFS_EVENT_CONTRACT';
 const TABLE = /^be\/apps\/([^/]+)\/src\/(events|consumes)\.ts$/;
 const SNAPSHOT = /^be\/contracts\/([^/]+)\/events\.json$/;
-
 function literal(ts, node) {
-  if (!node) throw new Error('missing initializer');
-  if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node)) return literal(ts, node.expression);
-  if (ts.isStringLiteralLike(node)) return node.text;
-  if (ts.isNumericLiteral(node)) return Number(node.text);
-  if (!ts.isObjectLiteralExpression(node)) throw new Error('expected a literal object, string or number');
-  return Object.fromEntries(node.properties.map((property) => {
-    const key = nameText(ts, property.name);
-    if (!ts.isPropertyAssignment(property) || key === null) throw new Error('expected a named literal property');
-    return [key, literal(ts, property.initializer)];
-  }));
+    if (!node)
+        throw new Error('missing initializer');
+    if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node))
+        return literal(ts, node.expression);
+    if (ts.isStringLiteralLike(node))
+        return node.text;
+    if (ts.isNumericLiteral(node))
+        return Number(node.text);
+    if (!ts.isObjectLiteralExpression(node))
+        throw new Error('expected a literal object, string or number');
+    return Object.fromEntries(node.properties.map((property) => {
+        const key = nameText(ts, property.name);
+        if (!ts.isPropertyAssignment(property) || key === null)
+            throw new Error('expected a named literal property');
+        return [key, literal(ts, property.initializer)];
+    }));
 }
-
 function tableOf(ts, text, name) {
-  const source = ts.createSourceFile('table.ts', text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  if (source.parseDiagnostics.length) throw new Error('invalid TypeScript');
-  for (const statement of source.statements) {
-    if (!ts.isVariableStatement(statement)) continue;
-    const declaration = statement.declarationList.declarations.find((entry) => ts.isIdentifier(entry.name) && entry.name.text === name);
-    if (declaration) {
-      const value = literal(ts, declaration.initializer);
-      if (value === null || typeof value !== 'object') throw new Error('expected a literal table');
-      return value;
+    const source = ts.createSourceFile('table.ts', text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    if (source.parseDiagnostics.length)
+        throw new Error('invalid TypeScript');
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        const declaration = statement.declarationList.declarations.find((entry) => ts.isIdentifier(entry.name) && entry.name.text === name);
+        if (declaration) {
+            const value = literal(ts, declaration.initializer);
+            if (value === null || typeof value !== 'object')
+                throw new Error('expected a literal table');
+            return value;
+        }
     }
-  }
-  throw new Error(`missing ${name} table`);
+    throw new Error(`missing ${name} table`);
 }
-
 function readTables(ts, repoRoot, files) {
-  const tables = [];
-  const findings = [];
-  for (const file of files.filter((candidate) => TABLE.test(candidate))) {
-    const [, service, kind] = TABLE.exec(file);
-    try {
-      const name = kind === 'events' ? 'EVENTS' : 'CONSUMES';
-      tables.push({ file, service, kind, value: tableOf(ts, readText(repoRoot, file) ?? '', name) });
-    } catch (error) {
-      findings.push(found(CODE, file, `${file}: ${error.message}; declare a literal event contract table.`));
+    const tables = [];
+    const findings = [];
+    for (const file of files.filter((candidate) => TABLE.test(candidate))) {
+        const [, service, kind] = TABLE.exec(file);
+        try {
+            const name = kind === 'events' ? 'EVENTS' : 'CONSUMES';
+            tables.push({ file, service, kind, value: tableOf(ts, readText(repoRoot, file) ?? '', name) });
+        }
+        catch (error) {
+            findings.push(found(CODE, file, `${file}: ${error.message}; declare a literal event contract table.`));
+        }
     }
-  }
-  return { tables, findings };
+    return { tables, findings };
 }
-
 function providerFindings(table, snapshots, declared) {
-  const findings = [];
-  const expected = { schema: 'starci/event-contract@1', service: table.service, events: table.value };
-  if (!isDeepStrictEqual(snapshots.get(table.service), expected)) {
-    findings.push(found(CODE, table.file, `${table.file}: be/contracts/${table.service}/events.json is missing or differs from EVENTS; commit the emitted provider snapshot.`));
-  }
-  for (const [name, event] of Object.entries(table.value)) {
-    if (!Number.isInteger(event?.version) || event.version < 1 || !event.payload || typeof event.payload !== 'object') {
-      findings.push(found(CODE, table.file, `${table.file}: ${name} needs a positive integer version and a literal payload.`));
+    const findings = [];
+    const expected = { schema: 'starci/event-contract@1', service: table.service, events: table.value };
+    if (!isDeepStrictEqual(snapshots.get(table.service), expected)) {
+        findings.push(found(CODE, table.file, `${table.file}: be/contracts/${table.service}/events.json is missing or differs from EVENTS; commit the emitted provider snapshot.`));
     }
-    if (event?.compensates !== undefined && !declared.has(event.compensates)) {
-      findings.push(found(CODE, table.file, `${table.file}: ${name} compensates undeclared event ${event.compensates}.`));
+    for (const [name, event] of Object.entries(table.value)) {
+        if (!Number.isInteger(event?.version) || event.version < 1 || !event.payload || typeof event.payload !== 'object') {
+            findings.push(found(CODE, table.file, `${table.file}: ${name} needs a positive integer version and a literal payload.`));
+        }
+        if (event?.compensates !== undefined && !declared.has(event.compensates)) {
+            findings.push(found(CODE, table.file, `${table.file}: ${name} compensates undeclared event ${event.compensates}.`));
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 function consumerFindings(table, snapshots) {
-  const findings = [];
-  for (const [provider, events] of Object.entries(table.value)) {
-    if (events === null || typeof events !== 'object') {
-      findings.push(found(CODE, table.file, `${table.file}: CONSUMES.${provider} must be a literal event/version table.`));
-      continue;
+    const findings = [];
+    for (const [provider, events] of Object.entries(table.value)) {
+        if (events === null || typeof events !== 'object') {
+            findings.push(found(CODE, table.file, `${table.file}: CONSUMES.${provider} must be a literal event/version table.`));
+            continue;
+        }
+        for (const [name, version] of Object.entries(events)) {
+            const snapshot = snapshots.get(provider);
+            const event = snapshot?.events?.[name];
+            if (snapshot?.schema !== 'starci/event-contract@1' || snapshot?.service !== provider || !event || event.version !== version) {
+                findings.push(found(CODE, table.file, `${table.file}: ${provider} event ${name} at version ${version} is not declared by its vendored snapshot.`));
+            }
+        }
     }
-    for (const [name, version] of Object.entries(events)) {
-      const snapshot = snapshots.get(provider);
-      const event = snapshot?.events?.[name];
-      if (snapshot?.schema !== 'starci/event-contract@1' || snapshot?.service !== provider || !event || event.version !== version) {
-        findings.push(found(CODE, table.file, `${table.file}: ${provider} event ${name} at version ${version} is not declared by its vendored snapshot.`));
-      }
-    }
-  }
-  return findings;
+    return findings;
 }
-
 export function eventTableFindings({ ts, repoRoot, files }) {
-  const snapshots = new Map(files.filter((file) => SNAPSHOT.test(file))
-    .map((file) => [SNAPSHOT.exec(file)[1], readJson(repoRoot, file)]));
-  const declared = new Set([...snapshots.values()].flatMap((snapshot) => Object.keys(snapshot?.events ?? {})));
-  const { tables, findings } = readTables(ts, repoRoot, files);
-  for (const table of tables) {
-    findings.push(...(table.kind === 'events' ? providerFindings(table, snapshots, declared) : consumerFindings(table, snapshots)));
-  }
-  return findings;
+    const snapshots = new Map(files.filter((file) => SNAPSHOT.test(file))
+        .map((file) => [SNAPSHOT.exec(file)[1], readJson(repoRoot, file)]));
+    const declared = new Set([...snapshots.values()].flatMap((snapshot) => Object.keys(snapshot?.events ?? {})));
+    const { tables, findings } = readTables(ts, repoRoot, files);
+    for (const table of tables) {
+        findings.push(...(table.kind === 'events' ? providerFindings(table, snapshots, declared) : consumerFindings(table, snapshots)));
+    }
+    return findings;
 }
-
 export const eventTableServices = (files) => files.filter((file) => TABLE.test(file) && TABLE.exec(file)[2] === 'events')
-  .map((file) => TABLE.exec(file)[1]);
+    .map((file) => TABLE.exec(file)[1]);

package/runtime/scripts/hfs/rules/fe-build-args.d.mts

@@ -0,0 +1,10 @@
+import type { Repo } from './rule-types.mjs';
+export declare const FE_PUBLIC_BUILD_ARG_MISSING = "FE_PUBLIC_BUILD_ARG_MISSING";
+/** Judge front-end Dockerfiles at the app root in both editions; only names are read, and sealed members are never opened. */
+export declare function feBuildArgsFindings({ repoRoot, files, all, repo, isRoot }: {
+    repoRoot: string;
+    files?: string[];
+    all?: string[];
+    repo: Repo;
+    isRoot?: boolean;
+}): any;

package/runtime/scripts/hfs/rules/fe-build-args.mjs

@@ -6,137 +6,154 @@ import { parseDockerfile, words } from '../../lib/dockerfile.mjs';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { found, readText } from './read.mjs';
-
 export const FE_PUBLIC_BUILD_ARG_MISSING = 'FE_PUBLIC_BUILD_ARG_MISSING';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PUBLIC = /^NEXT_PUBLIC_[A-Z0-9_]+$/u;
 const SOURCE = /\.[cm]?[jt]sx?$/u;
 const SCHEMA = /(?:^|[/.-])(?:env|schema)(?:[/.-]|$)/u;
 const DECLARATION = '.starcistacks/application-stacks.yaml';
-
 function declarationOf(root) {
-  try { return parseYaml(readText(root, DECLARATION) ?? '') ?? {}; } catch { return {}; }
+    try {
+        return parseYaml(readText(root, DECLARATION) ?? '') ?? {};
+    }
+    catch {
+        return {};
+    }
 }
-
 /** Parentheses and TypeScript assertions do not alter whether a read has a literal fallback. */
 function unwrappedParent(ts, node) {
-  let current = node;
-  while (current.parent && (ts.isParenthesizedExpression(current.parent) || ts.isAsExpression(current.parent) || ts.isNonNullExpression(current.parent))) current = current.parent;
-  return current;
+    let current = node;
+    while (current.parent && (ts.isParenthesizedExpression(current.parent) || ts.isAsExpression(current.parent) || ts.isNonNullExpression(current.parent)))
+        current = current.parent;
+    return current;
 }
-
 function literalFallback(ts, node) {
-  const current = unwrappedParent(ts, node);
-  const parent = current.parent;
-  if (!parent || !ts.isBinaryExpression(parent) || parent.left !== current) return false;
-  const fallback = parent.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken || parent.operatorToken.kind === ts.SyntaxKind.BarBarToken;
-  return fallback && ts.isStringLiteralLike(parent.right);
+    const current = unwrappedParent(ts, node);
+    const parent = current.parent;
+    if (!parent || !ts.isBinaryExpression(parent) || parent.left !== current)
+        return false;
+    const fallback = parent.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken || parent.operatorToken.kind === ts.SyntaxKind.BarBarToken;
+    return fallback && ts.isStringLiteralLike(parent.right);
 }
-
 function publicRead(ts, node) {
-  if (!ts.isPropertyAccessExpression(node) || !PUBLIC.test(node.name.text)) return null;
-  const owner = node.expression;
-  const env = ts.isIdentifier(owner) && owner.text === 'env';
-  const processEnv = ts.isPropertyAccessExpression(owner) && owner.name.text === 'env' && ts.isIdentifier(owner.expression) && owner.expression.text === 'process';
-  return env || processEnv ? node.name.text : null;
+    if (!ts.isPropertyAccessExpression(node) || !PUBLIC.test(node.name.text))
+        return null;
+    const owner = node.expression;
+    const env = ts.isIdentifier(owner) && owner.text === 'env';
+    const processEnv = ts.isPropertyAccessExpression(owner) && owner.name.text === 'env' && ts.isIdentifier(owner.expression) && owner.expression.text === 'process';
+    return env || processEnv ? node.name.text : null;
 }
-
 function optionalSchema(ts, node) {
-  if (!node) return false;
-  if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
-    if (['optional', 'default', 'catch', 'nullish'].includes(node.expression.name.text)) return true;
-    return optionalSchema(ts, node.expression.expression);
-  }
-  return false;
+    if (!node)
+        return false;
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+        if (['optional', 'default', 'catch', 'nullish'].includes(node.expression.name.text))
+            return true;
+        return optionalSchema(ts, node.expression.expression);
+    }
+    return false;
 }
-
 function schemaKey(ts, node) {
-  if (!ts.isPropertyAssignment(node) && !ts.isPropertySignature(node)) return null;
-  const name = node.name?.text;
-  if (!PUBLIC.test(name ?? '') || node.questionToken || optionalSchema(ts, node.initializer)) return null;
-  return name;
+    if (!ts.isPropertyAssignment(node) && !ts.isPropertySignature(node))
+        return null;
+    const prop = node;
+    const name = prop.name?.text;
+    if (!PUBLIC.test(name ?? '') || prop.questionToken || optionalSchema(ts, prop.initializer))
+        return null;
+    return name;
 }
-
 function sourceRequirements(ts, file, text) {
-  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
-  const required = new Set();
-  const schema = SCHEMA.test(file);
-  const visit = node => {
-    const name = publicRead(ts, node);
-    if (name && !literalFallback(ts, node)) required.add(name);
-    const key = schema ? schemaKey(ts, node) : null;
-    if (key) required.add(key);
-    ts.forEachChild(node, visit);
-  };
-  visit(source);
-  return required;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const required = new Set();
+    const schema = SCHEMA.test(file);
+    const visit = (node) => {
+        const name = publicRead(ts, node);
+        if (name && !literalFallback(ts, node))
+            required.add(name);
+        const key = schema ? schemaKey(ts, node) : null;
+        if (key)
+            required.add(key);
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return required;
 }
-
 /** JSON/YAML environment schemas declare required names explicitly; optional properties impose no build requirement. */
 function schemaRequirements(text) {
-  let schema;
-  try { schema = parseYaml(text); } catch { return []; }
-  const names = [];
-  const visit = value => {
-    if (!value || typeof value !== 'object') return;
-    if (Array.isArray(value.required)) names.push(...value.required.filter(name => typeof name === 'string' && PUBLIC.test(name)));
-    Object.values(value).forEach(child => { if (child && typeof child === 'object') visit(child); });
-  };
-  visit(schema);
-  return names;
+    let schema;
+    try {
+        schema = parseYaml(text);
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    const visit = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        if (Array.isArray(value.required))
+            names.push(...value.required.filter((name) => typeof name === 'string' && PUBLIC.test(name)));
+        Object.values(value).forEach(child => { if (child && typeof child === 'object')
+            visit(child); });
+    };
+    visit(schema);
+    return names;
 }
-
 function requiredNames(root, files, app, ts) {
-  const prefix = `fe/apps/${app}/`;
-  const names = new Set();
-  for (const file of files.filter(file => file.startsWith(prefix))) {
-    const local = file.slice(prefix.length);
-    const source = SOURCE.test(local) && (local.startsWith('src/') || local.startsWith('next.config.') || SCHEMA.test(local));
-    const schema = SCHEMA.test(local) && /\.(?:json|ya?ml)$/u.test(local);
-    if (!source && !schema) continue;
-    const text = readText(root, file);
-    if (text === null) continue;
-    const required = source ? sourceRequirements(ts, local, text) : schemaRequirements(text);
-    for (const name of required) names.add(name);
-  }
-  return [...names].sort(byCodeUnit);
+    const prefix = `fe/apps/${app}/`;
+    const names = new Set();
+    for (const file of files.filter((file) => file.startsWith(prefix))) {
+        const local = file.slice(prefix.length);
+        const source = SOURCE.test(local) && (local.startsWith('src/') || local.startsWith('next.config.') || SCHEMA.test(local));
+        const schema = SCHEMA.test(local) && /\.(?:json|ya?ml)$/u.test(local);
+        if (!source && !schema)
+            continue;
+        const text = readText(root, file);
+        if (text === null)
+            continue;
+        const required = source ? sourceRequirements(ts, local, text) : schemaRequirements(text);
+        for (const name of required)
+            names.add(name);
+    }
+    return [...names].sort(byCodeUnit);
 }
-
 function dockerDefaults(text) {
-  return new Set(parseDockerfile(text).instructions.filter(item => item.keyword === 'ARG')
-    .flatMap(item => words(item.text)).filter(word => word.includes('='))
-    .map(word => word.slice(0, word.indexOf('='))));
+    return new Set(parseDockerfile(text).instructions.filter((item) => item.keyword === 'ARG')
+        .flatMap((item) => words(item.text)).filter((word) => word.includes('='))
+        .map((word) => word.slice(0, word.indexOf('='))));
 }
-
 function missingForEnvironment(environment, app, required) {
-  const images = Object.values(environment?.deploy?.images ?? {}).filter(image => image?.app === app);
-  if (!images.length) return [];
-  return required.filter(name => images.some(image => {
-    const args = image.buildArgs ?? {};
-    return !Object.hasOwn(args.values ?? {}, name) && !(args.sealed?.keys ?? []).includes(name);
-  }));
+    const images = Object.values(environment?.deploy?.images ?? {}).filter(image => image?.app === app);
+    if (!images.length)
+        return [];
+    return required.filter((name) => images.some(image => {
+        const args = image.buildArgs ?? {};
+        return !Object.hasOwn(args.values ?? {}, name) && !(args.sealed?.keys ?? []).includes(name);
+    }));
 }
-
 function appFindings(context, app, environments, ts) {
-  const { repoRoot, files } = context;
-  const file = `fe/apps/${app}/Dockerfile`;
-  if (!files.includes(file)) return [];
-  const defaults = dockerDefaults(readText(repoRoot, file) ?? '');
-  const required = requiredNames(repoRoot, files, app, ts).filter(name => !defaults.has(name));
-  const missing = Object.entries(environments).flatMap(([environment, entry]) => {
-    const names = missingForEnvironment(entry, app, required);
-    return names.length ? [{ environment, names }] : [];
-  });
-  if (!missing.length) return [];
-  const detail = missing.map(entry => `${entry.environment}: ${entry.names.join(', ')}`).join('; ');
-  return [found(FE_PUBLIC_BUILD_ARG_MISSING, file, `${FE_PUBLIC_BUILD_ARG_MISSING}: ${file} requires public build values without ARG defaults or deploy image buildArgs (${detail}).`, { missing })];
+    const { repoRoot, files } = context;
+    const file = `fe/apps/${app}/Dockerfile`;
+    if (!files.includes(file))
+        return [];
+    const defaults = dockerDefaults(readText(repoRoot, file) ?? '');
+    const required = requiredNames(repoRoot, files, app, ts).filter(name => !defaults.has(name));
+    const missing = Object.entries(environments).flatMap(([environment, entry]) => {
+        const names = missingForEnvironment(entry, app, required);
+        return names.length ? [{ environment, names }] : [];
+    });
+    if (!missing.length)
+        return [];
+    const detail = missing.map(entry => `${entry.environment}: ${entry.names.join(', ')}`).join('; ');
+    return [found(FE_PUBLIC_BUILD_ARG_MISSING, file, `${FE_PUBLIC_BUILD_ARG_MISSING}: ${file} requires public build values without ARG defaults or deploy image buildArgs (${detail}).`, { missing })];
 }
-
 /** Judge front-end Dockerfiles at the app root in both editions; only names are read, and sealed members are never opened. */
 export function feBuildArgsFindings({ repoRoot, files = [], all = files, repo, isRoot = true }) {
-  if (!repoRoot || !isRoot || !repo?.sides?.fe) return [];
-  const ts = loadTypescript(repoRoot, HERE);
-  if (!ts) return [];
-  const environments = declarationOf(repoRoot).environments ?? {};
-  return repo.sides.fe.apps.flatMap(app => appFindings({ repoRoot, files: all }, app.name, environments, ts));
+    if (!repoRoot || !isRoot || !repo?.sides?.fe)
+        return [];
+    const ts = loadTypescript(repoRoot, HERE);
+    if (!ts)
+        return [];
+    const environments = declarationOf(repoRoot).environments ?? {};
+    return repo.sides.fe.apps.flatMap((app) => appFindings({ repoRoot, files: all }, app.name, environments, ts));
 }

package/runtime/scripts/hfs/rules/fe-contract-documents.d.mts

@@ -0,0 +1,7 @@
+import type { Finding } from './rule-types.mjs';
+export declare const FE_GRAPHQL_CONTRACT = "FE_GRAPHQL_CONTRACT";
+/** The findings of R113 over the tracked paths `files` of the app at `repoRoot`. */
+export declare function feContractFindings({ repoRoot, files }: {
+    repoRoot: string;
+    files: string[];
+}): Finding[];