@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/rules/database-transaction.d.mts

@@ -0,0 +1,3 @@
+import type { Parsed } from './rule-types.mjs';
+/** Transaction control a migration must not carry, one finding per statement with its file:line. */
+export declare function transactionControlFindings(file: string, text: string, stmts: Parsed, lineAt: Parsed): import("./rule-types.mjs").Finding[];

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

@@ -5,41 +5,39 @@
 import { found } from './read.mjs';
 import { databaseSqlTokens } from './database-migrations.mjs';
 import { DB_MIGRATION_SHAPE } from './database-constants.mjs';
-
 const CONTROL_IN_DO = new Set(['commit', 'rollback']);
 // PL/pgSQL words after which a statement starts.
 const STATEMENT_OPENERS = new Set(['begin', 'then', 'else', 'loop']);
-
 /** The line of the first token of the statement starting at byte `location` (leading blanks and comments skipped). */
 function statementLine(text, location, lineAt) {
-  const rest = Buffer.from(text, 'utf8').subarray(Math.max(location, 0), Math.max(location, 0) + 4096).toString('utf8');
-  const first = databaseSqlTokens(rest)[0];
-  return lineAt(Math.max(location, 0)) + (first ? first.line - 1 : 0);
+    const rest = Buffer.from(text, 'utf8').subarray(Math.max(location, 0), Math.max(location, 0) + 4096).toString('utf8');
+    const first = databaseSqlTokens(rest)[0];
+    return lineAt(Math.max(location, 0)) + (first ? first.line - 1 : 0);
 }
-
 const doBody = (node) => (node.args ?? []).find((item) => item.DefElem?.defname === 'as')?.DefElem?.arg?.String?.sval ?? '';
-
 /** Transaction control a migration must not carry, one finding per statement with its file:line. */
 export function transactionControlFindings(file, text, stmts, lineAt) {
-  const findings = [];
-  for (const entry of stmts ?? []) {
-    const line = () => statementLine(text, entry.stmt_location ?? 0, lineAt);
-    if (entry.stmt?.TransactionStmt) {
-      const kind = String(entry.stmt.TransactionStmt.kind ?? '').replace(/^TRANS_STMT_/, '').toLowerCase().replaceAll('_', ' ');
-      const at = line();
-      findings.push(found(DB_MIGRATION_SHAPE, file, `${file}:${at} carries transaction control (${kind}); a migration is applied in one transaction with its history row, so it never begins, commits, rolls back or sets a savepoint`, { line: at }));
-      continue;
+    const findings = [];
+    for (const entry of stmts ?? []) {
+        const line = () => statementLine(text, entry.stmt_location ?? 0, lineAt);
+        if (entry.stmt?.TransactionStmt) {
+            const kind = String(entry.stmt.TransactionStmt.kind ?? '').replace(/^TRANS_STMT_/, '').toLowerCase().replaceAll('_', ' ');
+            const at = line();
+            findings.push(found(DB_MIGRATION_SHAPE, file, `${file}:${at} carries transaction control (${kind}); a migration is applied in one transaction with its history row, so it never begins, commits, rolls back or sets a savepoint`, { line: at }));
+            continue;
+        }
+        if (!entry.stmt?.DoStmt)
+            continue;
+        const body = doBody(entry.stmt.DoStmt);
+        const tokens = databaseSqlTokens(body);
+        tokens.forEach((token, index) => {
+            const before = tokens[index - 1];
+            const leads = !before || before.v === ';' || (before.t === 'word' && STATEMENT_OPENERS.has(before.v));
+            if (token.t !== 'word' || !CONTROL_IN_DO.has(token.v) || !leads)
+                return;
+            const inner = line() + token.line - 1;
+            findings.push(found(DB_MIGRATION_SHAPE, file, `${file}:${inner} carries transaction control (${token.v} inside a DO block); a migration is applied in one transaction with its history row`, { line: inner }));
+        });
     }
-    if (!entry.stmt?.DoStmt) continue;
-    const body = doBody(entry.stmt.DoStmt);
-    const tokens = databaseSqlTokens(body);
-    tokens.forEach((token, index) => {
-      const before = tokens[index - 1];
-      const leads = !before || before.v === ';' || (before.t === 'word' && STATEMENT_OPENERS.has(before.v));
-      if (token.t !== 'word' || !CONTROL_IN_DO.has(token.v) || !leads) return;
-      const inner = line() + token.line - 1;
-      findings.push(found(DB_MIGRATION_SHAPE, file, `${file}:${inner} carries transaction control (${token.v} inside a DO block); a migration is applied in one transaction with its history row`, { line: inner }));
-    });
-  }
-  return findings;
+    return findings;
 }

package/runtime/scripts/hfs/rules/database.d.mts

@@ -0,0 +1,22 @@
+export { migrationStamp } from './database-migrations.mjs';
+export { DB_APP_ROLE, DB_FORCE_RLS_DEFAULT, DB_POLICY_TAUTOLOGY, DB_VIEW_UNSAFE, DB_STORAGE_PREFIX, } from './database-access.mjs';
+export declare const DB_DEFINER_REVOKE = "DB_DEFINER_REVOKE";
+export { DB_DEFINER_SAFE, DB_DYNAMIC_DDL, DB_MIGRATION_SHAPE, DB_POLICY_SHAPE, DB_RLS_REQUIRED, DB_STORAGE_POLICY, LITE_DB_MIGRATION, } from './database-constants.mjs';
+import type { Finding, Parsed } from './rule-types.mjs';
+/**
+ * LITE_DB_MIGRATION: a lite app's schema lives only under db/: no supabase/ tree and no SQL file outside db/ (but a
+ * .starcistacks seed), and every SQL file under db/ is a migration, the archive, the seed or nothing.
+ */
+export declare function liteDbPathFindings(files: string[]): Finding[];
+/**
+ * Judge the db/ tree of one lite app. Git is injected for deterministic specs; this function starts no
+ * database and no Docker process. A full app keeps its TypeORM migrations under be/ and is judged here only for a stray db/ tree.
+ */
+export declare function checkDatabase({ repoRoot, files, base, git, edition, db }: {
+    repoRoot: string;
+    files: string[];
+    base?: Parsed;
+    git?: Parsed;
+    edition?: string;
+    db?: Parsed;
+}): Promise<Finding[]>;

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

@@ -8,81 +8,65 @@ import { databaseAccessFindings } from './database-access.mjs';
 import { DB_DIR, DB_MIGRATION_SHAPE, isActiveMigration, LITE_DB_MIGRATION, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { eachInOrder } from '../../lib/in-order.mjs';
-
 export { migrationStamp } from './database-migrations.mjs';
-export {
-  DB_APP_ROLE, DB_FORCE_RLS_DEFAULT, DB_POLICY_TAUTOLOGY, DB_VIEW_UNSAFE, DB_STORAGE_PREFIX,
-} from './database-access.mjs';
+export { DB_APP_ROLE, DB_FORCE_RLS_DEFAULT, DB_POLICY_TAUTOLOGY, DB_VIEW_UNSAFE, DB_STORAGE_PREFIX, } from './database-access.mjs';
 export const DB_DEFINER_REVOKE = 'DB_DEFINER_REVOKE';
-export {
-  DB_DEFINER_SAFE,
-  DB_DYNAMIC_DDL,
-  DB_MIGRATION_SHAPE,
-  DB_POLICY_SHAPE,
-  DB_RLS_REQUIRED,
-  DB_STORAGE_POLICY,
-  LITE_DB_MIGRATION,
-} from './database-constants.mjs';
-
+export { DB_DEFINER_SAFE, DB_DYNAMIC_DDL, DB_MIGRATION_SHAPE, DB_POLICY_SHAPE, DB_RLS_REQUIRED, DB_STORAGE_POLICY, LITE_DB_MIGRATION, } from './database-constants.mjs';
 /** The schemas the app's tables live in; no schema is exposed to a browser, which reaches data only through the back end. */
 const APP_SCHEMAS = new Set(['public']);
-
 /** A .starcistacks seed is the one SQL file a lite app keeps outside db/. */
 const STACK_SEED = /^\.starcistacks\/[^/]+\/seeds\/.+\.sql$/;
-
 /**
  * LITE_DB_MIGRATION: a lite app's schema lives only under db/: no supabase/ tree and no SQL file outside db/ (but a
  * .starcistacks seed), and every SQL file under db/ is a migration, the archive, the seed or nothing.
  */
 export function liteDbPathFindings(files) {
-  const findings = [];
-  for (const file of files) {
-    if (file === 'supabase' || file.startsWith('supabase/')) {
-      findings.push(found(LITE_DB_MIGRATION, file, `${file} is a Supabase project file; a lite app keeps its schema in ${MIGRATIONS_DIR}/<ts14>_<kebab>.sql (move the migrations, delete supabase/)`, {}));
-      continue;
+    const findings = [];
+    for (const file of files) {
+        if (file === 'supabase' || file.startsWith('supabase/')) {
+            findings.push(found(LITE_DB_MIGRATION, file, `${file} is a Supabase project file; a lite app keeps its schema in ${MIGRATIONS_DIR}/<ts14>_<kebab>.sql (move the migrations, delete supabase/)`, {}));
+            continue;
+        }
+        if (!file.endsWith('.sql') || STACK_SEED.test(file))
+            continue;
+        if (!file.startsWith(`${DB_DIR}/`))
+            findings.push(found(LITE_DB_MIGRATION, file, `${file} is SQL outside ${DB_DIR}/; a schema change is one ${MIGRATIONS_DIR}/<ts14>_<kebab>.sql`, {}));
     }
-    if (!file.endsWith('.sql') || STACK_SEED.test(file)) continue;
-    if (!file.startsWith(`${DB_DIR}/`)) findings.push(found(LITE_DB_MIGRATION, file, `${file} is SQL outside ${DB_DIR}/; a schema change is one ${MIGRATIONS_DIR}/<ts14>_<kebab>.sql`, {}));
-  }
-  return findings;
+    return findings;
 }
-
 async function migrationAnalyses({ repoRoot, migrations, exposed, forceRls, findings }) {
-  const analyses = [];
-  await eachInOrder(migrations, async (file) => {
-    const text = readText(repoRoot, file);
-    if (text === null) {
-      findings.push(found(DB_MIGRATION_SHAPE, file, `${file} is not a readable SQL file`, {}));
-      return;
-    }
-    const analysis = await sqlAnalysis({ file, text, exposed, forceRls });
-    findings.push(...analysis.findings);
-    if (analysis.facts) analyses.push({ file, facts: analysis.facts });
-  });
-  return analyses;
+    const analyses = [];
+    await eachInOrder(migrations, async (file) => {
+        const text = readText(repoRoot, file);
+        if (text === null) {
+            findings.push(found(DB_MIGRATION_SHAPE, file, `${file} is not a readable SQL file`, {}));
+            return;
+        }
+        const analysis = await sqlAnalysis({ file, text, exposed, forceRls });
+        findings.push(...analysis.findings);
+        if (analysis.facts)
+            analyses.push({ file, facts: analysis.facts });
+    });
+    return analyses;
 }
-
 /**
  * Judge the db/ tree of one lite app. Git is injected for deterministic specs; this function starts no
  * database and no Docker process. A full app keeps its TypeORM migrations under be/ and is judged here only for a stray db/ tree.
  */
-export async function checkDatabase({ repoRoot, files, base, git, edition, db } = {}) {
-  const findings = [];
-  const declaration = readJson(repoRoot, 'hfs.json');
-  const lite = (edition ?? declaration?.edition) === 'lite';
-  const migrations = files.filter(isActiveMigration).sort(byCodeUnit);
-  if (!lite && !migrations.length) return findings;
-  const declared = db === undefined ? declaration?.db : db;
-  const archived = files.filter((file) => file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`));
-  if (lite) findings.push(...liteDbPathFindings(files));
-  const forceRls = new Set((declared?.forceRls ?? []).map((name) => (name.includes('.') ? name : `public.${name}`)));
-  findings.push(...await migrationShapeFindings({ repoRoot, migrations, archived, git: git ?? defaultGit, base }));
-
-  const analyses = await migrationAnalyses({ repoRoot, migrations, exposed: APP_SCHEMAS, forceRls, findings });
-  findings.push(
-    ...migrationSetPolicyFindings(analyses),
-    ...migrationSetDefinerFindings(analyses, APP_SCHEMAS),
-    ...await databaseAccessFindings({ analyses, exposed: APP_SCHEMAS, db: declared }),
-  );
-  return findings;
+export async function checkDatabase({ repoRoot, files, base, git, edition, db }) {
+    const findings = [];
+    const declaration = readJson(repoRoot, 'hfs.json');
+    const lite = (edition ?? declaration?.edition) === 'lite';
+    const migrations = files.filter(isActiveMigration).sort(byCodeUnit);
+    if (!lite && !migrations.length)
+        return findings;
+    const declared = db === undefined ? declaration?.db : db;
+    const archived = files.filter((file) => file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`));
+    if (lite)
+        findings.push(...liteDbPathFindings(files));
+    const forceRls = new Set((declared?.forceRls ?? []).map((name) => (name.includes('.') ? name : `public.${name}`)));
+    findings.push(...await migrationShapeFindings({ repoRoot, migrations, archived, git: git ?? defaultGit, base }));
+    const analyses = await migrationAnalyses({ repoRoot, migrations, exposed: APP_SCHEMAS, forceRls, findings });
+    findings.push(...migrationSetPolicyFindings(analyses), ...migrationSetDefinerFindings(analyses, APP_SCHEMAS), ...await databaseAccessFindings({ analyses, exposed: APP_SCHEMAS, db: declared }));
+    return findings;
 }

package/runtime/scripts/hfs/rules/deploy-scan.d.mts

@@ -0,0 +1,10 @@
+import type { Repo } from './rule-types.mjs';
+/** Findings are names and paths only: deployment source snippets and credential values are never reported. */
+export declare function deployScanFindings({ repoRoot, files, all, repo, isRoot, inScope }: {
+    repoRoot: string;
+    files: string[];
+    all?: string[] | undefined;
+    repo?: Repo | undefined;
+    isRoot?: boolean | undefined;
+    inScope?: ((file: string) => boolean) | undefined;
+}): import("./rule-types.mjs").Finding[];