@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/manifest-shape.d.mts

@@ -0,0 +1,216 @@
+export type Parsed = any;
+export type SlotPresence = 'required' | 'optional' | 'opt-in' | 'forbidden';
+export type SlotTracking = 'tracked' | 'ignored' | 'external' | 'generated';
+export type SlotTests = 'unit-beside' | 'e2e' | 'none';
+export type SlotCoverage = 'required' | 'none';
+/** A reference to the file that exemplifies a slot: a path, or a path limited to one edition or a few. */
+export type SlotEvidenceRef = string | {
+    path: string;
+    edition?: string;
+    editions?: string[];
+};
+/** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
+export interface SlotLiteOverlay {
+    path?: string;
+    requires?: string[];
+    allows?: string[];
+    forbids?: string[];
+    minInstances?: number;
+    requiredInstances?: Record<string, string[]>;
+    why?: string;
+}
+/** One slot of the manifest (knowledge/hfs/slots.yaml, or runtime-slots.yaml for kind runtime), as the loader validated it. */
+export interface Slot {
+    id: string;
+    profiles: string[];
+    path: string;
+    presence: SlotPresence;
+    tracked: SlotTracking;
+    tier: string;
+    tests: SlotTests;
+    owner?: boolean;
+    appKind?: string;
+    minInstances?: number;
+    requiredWhen?: string;
+    requiredInstances?: Record<string, string[]>;
+    requires?: string[];
+    pattern?: string;
+    trigger?: string;
+    allows?: string[];
+    forbids?: string[];
+    layers?: string[];
+    kinds?: string[];
+    roles?: Record<string, string>;
+    composedBy?: string[];
+    budget?: Record<string, number>;
+    managedBy?: string;
+    liteManagedBy?: string;
+    rules?: string[];
+    goesTo?: string;
+    why?: string;
+    since?: string;
+    perConnection?: string[];
+    parent?: string;
+    editions?: string[];
+    editionWhy?: string;
+    litePresence?: SlotPresence | Record<string, SlotPresence>;
+    lite?: SlotLiteOverlay;
+    provider?: string;
+    coverage?: SlotCoverage;
+    entries?: string[];
+    outcomeHome?: boolean;
+    templateNa?: string;
+    exemplifiedBy?: SlotEvidenceRef[];
+    role?: string;
+    importedBy?: string[];
+    rewrittenBy?: string;
+    logic?: string[];
+    generatedBy?: string;
+}
+/** One tier of the direction matrix of a profile. */
+export interface TierDef {
+    mayImport: string[];
+    mayImportKinds?: Record<string, {
+        from: string[];
+        to: string[];
+    }>;
+    mayImportSlots?: Record<string, {
+        from: string[];
+    }>;
+    acyclic?: boolean;
+    lowerLayerOnly?: boolean;
+}
+/** A unit-tested role of a back end (ruleParams.be.unitRoles). */
+export interface UnitRole {
+    role: string;
+    spec: string;
+    slot?: string;
+    exempt?: string[];
+}
+/** A database function an app or the canon lists (ruleParams.be.dbFunctions, hfs.json sides.be.dbFunctions). */
+export interface DbFunction {
+    name: string;
+    reason: string;
+}
+/** The rule parameters of one profile (ruleParams.common merged with ruleParams.<profile>); the keys not named here are parsed manifest data. */
+export interface RuleParams {
+    [key: string]: Parsed;
+    fileLines?: {
+        soft: number;
+        hardGrowth: boolean;
+    };
+    duplicateBlock?: {
+        lines: number;
+        tokens: number;
+    };
+    logicRoles?: string[];
+    suffixes?: string[];
+    bannedSuffixes?: string[];
+    dbFunctions?: DbFunction[];
+}
+/** ruleParams.be: the back end's own parameters, which the validators of this folder require. */
+export interface BeRuleParams extends RuleParams {
+    unitRoles: UnitRole[];
+    logicRoles: string[];
+    suffixes: string[];
+    bannedSuffixes: string[];
+}
+/** The `ruleParams` of a manifest, by profile; `common` is shared and `lite` overrides live inside each profile. */
+export interface ManifestRuleParams {
+    [profile: string]: RuleParams | undefined;
+    common: RuleParams;
+    be: BeRuleParams;
+}
+/** The parsed and validated slot manifest of loadSlotManifest, with the numeric parts of `version` added. */
+export interface SlotManifest {
+    schema: string;
+    kind?: string;
+    version: string;
+    major: number;
+    minor: number;
+    patch: number;
+    editions?: string[];
+    sides: Record<string, {
+        reads: string[];
+    }>;
+    appKinds: Record<string, string[]>;
+    triggerKinds?: string[];
+    tiers: Record<string, Record<string, TierDef>>;
+    ruleParams: ManifestRuleParams;
+    slots: Slot[];
+    consumers?: string[];
+    crossOwner?: string;
+    crossApp?: string;
+}
+export declare const SEMVER: RegExp;
+export declare const NAME: RegExp;
+/** An npm package name, scoped or not. */
+export declare const PACKAGE_NAME: RegExp;
+/** The editions an app repository may declare in hfs.json (`full` when absent): the filter slots.mjs applies. */
+export declare const EDITIONS: readonly string[];
+/** What decides where schema changes live (ruleParams.<side>.schemaAuthority): TypeORM migrations under persistence/, or the SQL migration tree db/migrations. */
+export declare const SCHEMA_AUTHORITIES: readonly string[];
+/**
+ * The shape problems of the `connections` of one side: a list of {name, envPrefix, owner, isolation}, the owner an api or worker app
+ * of the same side (a connection is a bounded context and one service owns it), isolation `database` or `schema`.
+ *
+ * @param {unknown} list - The declared connections (null when it is not an array).
+ * @param {unknown} apps - The declared apps of the same side.
+ * @returns {string[]} The problems, none when the shape is right.
+ */
+export declare function connectionShapeProblems(list: Parsed, apps: Parsed): string[];
+export declare const SLOT_ID: RegExp;
+export declare const PRESENCE: string[];
+export declare const TRACKED: string[];
+export declare const TESTS: string[];
+/** The coverage mode of a tracked slot of the be profile or of a runtime manifest (scripts/hfs/coverage-scope.mjs and scripts/hfs/runtime-coverage-scope.mjs derive the coverage consumers from it). */
+export declare const COVERAGE: string[];
+export declare const APP_KIND = "app";
+/**
+ * The unit-tested roles of a back end whose spec is required (ruleParams.be.unitRoles of the slot manifest): [{ role, spec, slot?, exempt? }].
+ * THE one list: every check that asks "is this file unit-tested, and where is its spec" asks it here. What the unit run MEASURES is
+ * logicRoles over the coverage-required slots (coverage-scope.mjs), not this list.
+ */
+export declare const unitRolesOf: (manifest: SlotManifest) => UnitRole[];
+/** The roles that carry logic (ruleParams.be.logicRoles): measured at 100 per file inside a coverage-required slot. */
+export declare const logicRolesOf: (manifest: SlotManifest) => string[];
+/** The role suffix of a file name (`passport.tokens.ts` gives `tokens`). */
+export declare const suffixOf: (file: string) => string | null;
+/**
+ * The files a slot declares as logic (`logic`, names relative to the slot path): a file that carries logic without a logic-role suffix.
+ * Each is measured at 100 per file like a logic-role file (scripts/hfs/coverage-scope.mjs), and its `<stem>.spec.ts` beside it is a
+ * legitimate unit spec its slot admits (scripts/hfs/allows.mjs, eslint-canon-be unit-test-colocated). No role name is added for it.
+ */
+export declare const declaredLogicOf: (slot: Pick<Slot, "logic"> | null | undefined) => string[];
+/** The unit spec beside a declared logic file: `passport.tokens.ts` gives `passport.tokens.spec.ts`. */
+export declare const declaredLogicSpecOf: (file: string) => string;
+/**
+ * Shape problems of a slot's `logic`: a non-empty list of unique `<name>.<part>.ts` files, each one the slot requires or allows by that
+ * exact name, on a tracked directory slot of profile be that is coverage: required and unit-beside, and (given the logic roles) none
+ * already of a logic role, which its role measures.
+ */
+export declare function slotLogicProblems(slot: Parsed, at: string, logicRoles?: readonly unknown[]): string[];
+/** Shape problems of ruleParams.be.unitRoles: unique roles of the suffix vocabulary, each spec `<role>.spec`. */
+export declare function unitRolesProblems(be: Parsed): string[];
+/** Shape problems of ruleParams.be.logicRoles, valueRoles and thinRoles: each a non-empty list of unique roles of the suffix vocabulary; every unit role is a logic role. */
+export declare function roleListProblems(be: Parsed): string[];
+/** The kind of a manifest and of a declaration that describes the StarCi runtime repository; also its one profile. */
+export declare const RUNTIME_KIND = "runtime";
+export declare const MANIFEST_KINDS: string[];
+/** The kind of a parsed manifest: `kind`, or app when absent (knowledge/hfs/slots.yaml carries none). */
+export declare const manifestKind: (m: Parsed) => string;
+export declare function slotProblems(slot: Parsed, index: number, kind: string, { appScope, scopes, logicRoles }?: {
+    appScope?: string;
+    scopes?: string[];
+    logicRoles?: readonly unknown[];
+}): string[];
+/** Shape problems of a parsed manifest of kind runtime (knowledge/hfs/runtime-slots.yaml), in the words of modules/schemas/hfs-slots.schema.yaml. */
+export declare function runtimeShapeProblems(m: Parsed): string[];
+/** A non-empty map whose every key is a name and every value satisfies `valid`. */
+export declare const namedMapValid: (map: Parsed, valid: Parsed) => boolean;
+/** Shape problems of the tier map of one profile. */
+export declare function tierMapProblems(profile: string, tiers: Parsed): string[];
+/** Kind and slot restrictions narrow allowed tier edges and name declared source and target roles. */
+export declare function tierKindProblems(manifest: SlotManifest, profile: string): string[];
+/** The semantic rules of a runtime manifest beyond the slot rules both kinds share: tier names and the schema major. */
+export declare function runtimeSemanticProblems(m: Parsed): string[];