@starci/hfs 4.11.22 → 4.12.2

package/src/helpers/hfs-arch-fixture.d.mts

@@ -0,0 +1,47 @@
+import type { TestContext } from 'node:test';
+import type { ArchitectureCheckOptions, ArchitectureCheckResult } from '../../runtime/scripts/hfs/architecture/index.mjs';
+export declare const ts: typeof import('typescript');
+export type Side = 'be' | 'fe';
+export interface AppEntry {
+    name: string;
+    kind: string;
+}
+/** Side-relative path to content; null removes a default file. */
+export type FileMap = Record<string, string | null>;
+export declare const DEFAULT_APPS: Record<Side, AppEntry[]>;
+export declare function writeFiles(root: string, files: FileMap): void;
+export declare function gitCommit(root: string, message?: string, env?: NodeJS.ProcessEnv): string;
+/** The app hfs.json of a fixture about one side: `fields` (apps, optionalSlots, connections, reads) for `side`, the smallest other side. */
+export declare function appDeclaration(side: Side, fields: object, project?: string): {
+    hfs: number;
+    kind: string;
+    project: string;
+    sides: {
+        fe: object;
+        be: object;
+    };
+};
+/**
+ * The `side` folder of a fresh temp app (removed after the test): the root a spec writes a side's files under and runs the
+ * machine on. The app root (its parent) holds nothing yet; write `../hfs.json` (appDeclarationText) and `../package.json`.
+ */
+export declare function tempSide(t: Pick<TestContext, 'after'>, prefix: string, side?: Side): string;
+/** appDeclaration as the text of an hfs.json file. */
+export declare const appDeclarationText: (side: Side, fields: object, project?: string) => string;
+/**
+ * A hermetic app whose `profile` side the machine judges: the app root holds hfs.json and the one package.json, the side folder
+ * (`<app>/<profile>`, the returned root) a permissive tsconfig.json and (be) apps/core/src/{main.ts,app.module.ts} or (fe) a Next
+ * app shell. `files` maps side-relative paths to content (null removes a default file); a path that starts with `../` is written
+ * at the app root (`../package.json` replaces the app's manifest). `declaration` overrides parts of the side's declaration. The
+ * app is a git repo with the files staged (not committed): call gitCommit(root) for a base.
+ */
+export interface ArchFixtureOptions {
+    profile?: Side;
+    files?: FileMap;
+    declaration?: object;
+    apps?: AppEntry[];
+}
+export declare function archFixture(t: Pick<TestContext, 'after'>, { profile, files, declaration, apps }?: ArchFixtureOptions): string;
+/** Run the whole machine over a fixture; extra options (base, paths) pass through. */
+export declare function runArch(root: string, options?: Omit<ArchitectureCheckOptions, 'repositoryRoot' | 'injectedTypeScript'>): ArchitectureCheckResult;
+export declare const findings: (report: Pick<ArchitectureCheckResult, "violations">, ruleId: string) => import("../../runtime/scripts/hfs/architecture/index.mjs").Finding[];

package/src/helpers/hfs-cli-fixture.d.mts

@@ -0,0 +1,65 @@
+interface AppEntry {
+    name: string;
+    kind: string;
+}
+interface SideDeclaration {
+    apps: AppEntry[];
+    [field: string]: unknown;
+}
+/** An hfs.json app declaration; a spec may add fields (edition, kinds) beside the sides. */
+export interface AppDeclaration {
+    hfs: number;
+    kind: string;
+    project: string;
+    sides: {
+        be: SideDeclaration;
+        fe: SideDeclaration;
+    };
+    [field: string]: unknown;
+}
+/** What `starci app sync` would load from the jest preset an app installs for its be side: the Sonar exclusions and the coverage sources. */
+export declare const PRESETS: {
+    sonarExclusions: string;
+};
+/** An app declaration: the be side of `be` and the fe side of `fe` (hfs.json sides.<side>). */
+export declare const appOf: ({ be, fe, project }?: {
+    be?: SideDeclaration;
+    fe?: SideDeclaration;
+    project?: string;
+}) => AppDeclaration;
+/** The clean app of most specs: one api app, one Next app. */
+export declare const APP: AppDeclaration;
+/** An app whose fe side holds two Next apps. */
+export declare const TWO_FE_APPS: AppDeclaration;
+/** The repository's `prettier` for a spec that is not about formatting: it judges every file formatted. */
+export declare const FORMATTED: Readonly<{
+    getFileInfo: () => Promise<{
+        ignored: boolean;
+        inferredParser: string;
+    }>;
+    resolveConfig: () => Promise<null>;
+    check: () => Promise<boolean>;
+}>;
+/** application-stacks.yaml as the standard shape wants it: a Sonar owned by the host. */
+export declare const STACKS_DECLARATION: string;
+/**
+ * A clean app for `declaration`: every managed file of the root and both sides rendered, every other path the manifest requires,
+ * one BE feature and the front end's module entries, clean to the whole check (including the README and the back-end app module).
+ * Not yet a Git repository. `into` places it as <into>/<name> instead of a fresh temporary directory (its README and package.json
+ * name the directory).
+ */
+export declare function writeCleanRepo(declaration?: AppDeclaration, { declare, into, name }?: {
+    declare?: boolean;
+    into?: string;
+    name?: string;
+}): string;
+/**
+ * Makes the app's own `typescript` and the `@starci/tsconfig` preset the side tsconfigs extend resolvable from the app root's
+ * node_modules (the machine loads both through the app's one install) without tracking them.
+ */
+export declare function installTypeScript(dir: string): string;
+export declare function gitAdd(dir: string): string;
+export declare function cleanup(dirs: Iterable<string>): void;
+/** Installs the coverage preset `starci app sync` and `starci app check` load from a checked app (a fresh process has no injected presets), without tracking it. */
+export declare function installPresets(dir: string): string;
+export {};

package/src/helpers/hfs-hfs-docker-rules-fixture.d.mts

@@ -0,0 +1,5 @@
+import { writeCleanRepo } from './hfs-cli-fixture.mjs';
+export declare const DOCKER_RULES_MANIFEST: import("../../runtime/scripts/hfs/manifest-shape.mts").SlotManifest;
+export declare function dockerRuleFixtureFiles(dir: string): string[];
+export declare function dockerRulesRepoOf(declaration: Parameters<typeof writeCleanRepo>[0], mutate?: (dir: string) => void): string;
+export declare function cleanupDockerRuleFixtures(): void;

package/src/helpers/hfs-secret-fixture.d.mts

@@ -0,0 +1,19 @@
+import type { TestContext } from "node:test";
+import type { SecretMainPorts } from "../../runtime/scripts/hfs/secret.mjs";
+type SecretRunOptions = Omit<SecretMainPorts, "stdout" | "stderr">;
+export declare function app(t: Pick<TestContext, "after">, files?: Record<string, string>, environment?: string): {
+    root: string;
+    dir: string;
+    env: NodeJS.ProcessEnv;
+    localDir: string;
+};
+export declare function run(argv: string[], options?: SecretRunOptions): Promise<{
+    code: number;
+    out: string;
+    err: string;
+}>;
+export declare function privateAbsent(result: {
+    out: string;
+    err: string;
+}, values: readonly string[]): void;
+export {};

package/src/helpers/pre-push-fixture.d.mts

@@ -0,0 +1,21 @@
+import type { SpawnSyncReturns } from 'node:child_process';
+import type { TestContext } from 'node:test';
+export type RefLine = readonly [name: string, sha: string, name2: string, remote: string];
+export interface PrePushRepository {
+    root: string;
+    hook: string;
+    head: string;
+    older: string;
+}
+export declare const ZERO: string;
+export declare const git: (cwd: string, ...args: string[]) => string;
+/**
+ * Install a package-resolution wrapper so the rendered hook runs the actual bundled gate in a disposable Git repository, beside a
+ * stand-in for the harness's `starci deps check` that exits with `depsExit`.
+ */
+export declare function repository(t: Pick<TestContext, 'after'>, hookText: string, { depsExit }?: {
+    depsExit?: number;
+}): PrePushRepository;
+/** Execute the generated shell with Git's ref-list input and a bounded child lifetime. */
+export declare function push({ root, hook }: Pick<PrePushRepository, 'root' | 'hook'>, lines: readonly (readonly string[])[]): SpawnSyncReturns<string>;
+export declare const ref: (name: string, sha: string, remote?: string) => RefLine;

package/src/helpers/stack-compose.d.mts

@@ -0,0 +1,6 @@
+export interface ComposeModel {
+    version?: unknown;
+    [key: string]: unknown;
+}
+/** Parse the stack config inputs and refuse mixed versions, treating absent, empty and 3 as Docker's current 3.x default. */
+export declare function stackConfigModels(args: readonly string[]): ComposeModel[];

package/src/helpers/swarm-stack-fixture.d.mts

@@ -0,0 +1,18 @@
+import type { TestContext } from 'node:test';
+import { stacksFindings } from '../../runtime/scripts/hfs/rules/stacks.mjs';
+export type Doc = Record<string, any>;
+export interface SwarmFixture {
+    root: string;
+    files: Set<string>;
+    stackFile: string;
+    declaration: Doc;
+    manifest: Doc;
+    model: Doc;
+    put: (relative: string, content: string) => void;
+    write: () => void;
+    check: () => ReturnType<typeof stacksFindings>;
+    modelFile: string;
+}
+export declare const swarmService: (image?: string) => Doc;
+export declare function swarmFixture(t: Pick<TestContext, 'after'>, edition?: string): SwarmFixture;
+export declare function addScheduledJob(fixture: Pick<SwarmFixture, 'manifest' | 'model' | 'write'>): void;

package/src/helpers/tmpdir.d.mts

@@ -0,0 +1,2 @@
+import type { TestContext } from 'node:test';
+export declare function mkdtemp(t: Pick<TestContext, 'after'>, prefix?: string, before?: (() => unknown) | null): string;

package/src/main.d.mts

@@ -0,0 +1,58 @@
+import { type LockResult } from '../scaffold/app.mjs';
+import type { GhSpawn } from '../ci/github.mjs';
+import type { Prompt } from '../runtime/scripts/hfs/secret-prompt.mjs';
+import type { AgeHost, SecretToolOverrides } from '../runtime/scripts/hfs/secret-init.mjs';
+import type { SecretSops } from '../runtime/scripts/hfs/secret-sops.mjs';
+import type { Prettier } from '../sync/format.mjs';
+import type { LinterRunner } from '../lint/run.mjs';
+import type { Presets } from '../sync/index.mjs';
+type Dynamic = any;
+/** The app IO every verb receives: the working directory, writers, environment and the injectable seams. */
+interface AppIo {
+    cwd: string;
+    harness?: {
+        version?: string;
+        role?: string;
+        openTicket?: (ticket: unknown) => unknown;
+    } | undefined;
+    edition?: string | undefined;
+    stdout: (text: string) => unknown;
+    stderr: (text: string) => unknown;
+    presets?: Presets | undefined;
+    prettier?: Prettier | undefined;
+    lock?: ((root: string) => LockResult) | undefined;
+    run?: unknown;
+    stackMain?: ((argv: string[], io: {
+        cwd: string;
+        out: unknown;
+        err: unknown;
+    }) => unknown) | undefined;
+    env: NodeJS.ProcessEnv;
+    stdin?: (() => string) | undefined;
+    prompt?: Prompt | undefined;
+    hostIdentity?: AgeHost | null | undefined;
+    sops?: SecretSops | null | undefined;
+    tools?: ({
+        spawn?: GhSpawn | undefined;
+    } & SecretToolOverrides) | undefined;
+    platform?: NodeJS.Platform | undefined;
+    stackIo?: Record<string, unknown> | undefined;
+    runLinter?: LinterRunner | undefined;
+    checkApp?: ((args: Dynamic) => Dynamic) | undefined;
+}
+/** The options of main: every seam of the app IO, each optional. */
+type MainOptions = {
+    [K in keyof AppIo]?: AppIo[K] | undefined;
+};
+export declare const VERBS: readonly string[];
+export declare const USAGE: string;
+/** The nearest folder at or above `dir` that holds hfs.json (the app root of a workspace), or `dir` itself when none does (the lint then refuses it). */
+export declare function appRootAbove(dir: string): string;
+/**
+ * `harness` ({ version }) is the CLI that runs this package in-process: its version is the starci-harness an app is judged and
+ * scaffolded at (runtime/scripts/hfs/canon-pins.mjs). `run` injects the database runner, `runLinter` the linter transport, `checkApp`
+ * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
+ * harness CLI's own secret.env SOPS_AGE_KEY, which every verb that opens a sealed member (secret, stack, release, db) reads last for the age identity (decryptionIdentity); `prompt` replaces its masked prompt.
+ */
+export declare function main(argv: string[], { cwd: baseCwd, harness, stdout, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp, }?: MainOptions): Promise<number>;
+export {};