@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/architecture/function-spec-providers.mjs

@@ -1,153 +1,171 @@
 import path from 'node:path';
-
 export const keyOf = (ts, property) => (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
 const exported = (ts, statement) => statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
-
 /** The directly defined functions among the declarations of an exported variable statement; other values are not callable. */
 function callableVariables(ts, statement) {
-  const names = [];
-  for (const declaration of statement.declarationList.declarations) {
-    const initializer = declaration.initializer;
-    if (ts.isIdentifier(declaration.name) && initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer))) names.push(declaration.name.text);
-  }
-  return names;
+    const names = [];
+    for (const declaration of statement.declarationList.declarations) {
+        const initializer = declaration.initializer;
+        if (ts.isIdentifier(declaration.name) && initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer)))
+            names.push(declaration.name.text);
+    }
+    return names;
 }
-
 /** The callable exports of one statement: an overload signature has no body and collapses into its implementation. */
 function callableExports(ts, statement) {
-  if (!exported(ts, statement)) return [];
-  if (ts.isFunctionDeclaration(statement)) return statement.name && statement.body ? [statement.name.text] : [];
-  return ts.isVariableStatement(statement) ? callableVariables(ts, statement) : [];
+    if (!exported(ts, statement))
+        return [];
+    if (ts.isFunctionDeclaration(statement))
+        return statement.name && statement.body ? [statement.name.text] : [];
+    return ts.isVariableStatement(statement) ? callableVariables(ts, statement) : [];
 }
-
 /**
  * The callable subset of a function subject's exports. Constants, enums, objects, types, `export ... from` re-exports and overload
  * signatures do not change which functions the spec must provide; a class or a default-export assignment keeps the class-provider
  * check (null), as does a module with no callable export.
  */
 export function functionSubjectExports(ts, sourceFile) {
-  const names = [];
-  for (const statement of sourceFile.statements) {
-    if (ts.isClassDeclaration(statement) || ts.isExportAssignment(statement)) return null;
-    for (const name of callableExports(ts, statement)) if (!names.includes(name)) names.push(name);
-  }
-  return names.length ? names : null;
+    const names = [];
+    for (const statement of sourceFile.statements) {
+        if (ts.isClassDeclaration(statement) || ts.isExportAssignment(statement))
+            return null;
+        for (const name of callableExports(ts, statement))
+            if (!names.includes(name))
+                names.push(name);
+    }
+    return names.length ? names : null;
 }
-
 const decoratorsOf = (ts, node) => (ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : []);
-
 /** A value object: an undecorated class whose constructor parameters carry no injection token, so Nest never builds it. */
 function isValueObjectClass(ts, declaration) {
-  if (decoratorsOf(ts, declaration).length > 0) return false;
-  const constructors = declaration.members.filter(member => ts.isConstructorDeclaration(member));
-  return constructors.every(constructor => constructor.parameters.every(parameter => decoratorsOf(ts, parameter).length === 0));
+    if (decoratorsOf(ts, declaration).length > 0)
+        return false;
+    const constructors = declaration.members.filter((member) => ts.isConstructorDeclaration(member));
+    return constructors.every(constructor => constructor.parameters.every(parameter => decoratorsOf(ts, parameter).length === 0));
 }
-
 /** The names of the value-object classes a module exports, or null when it exports a class that is not one (or none). */
 export function valueObjectSubjects(ts, sourceFile) {
-  const classes = sourceFile.statements.filter(statement => ts.isClassDeclaration(statement) && statement.name && exported(ts, statement));
-  if (!classes.length || !classes.every(declaration => isValueObjectClass(ts, declaration))) return null;
-  return classes.map(declaration => declaration.name.text);
+    const classes = sourceFile.statements.filter((statement) => ts.isClassDeclaration(statement) && Boolean(statement.name) && exported(ts, statement));
+    if (!classes.length || !classes.every(declaration => isValueObjectClass(ts, declaration)))
+        return null;
+    return classes.map(declaration => declaration.name.text);
 }
-
 /** The value of one literal object property. */
 export const propertyValue = (ts, object, key) => {
-  const property = object.properties.find(item => keyOf(ts, item) === key);
-  return property && ts.isPropertyAssignment(property) ? property.initializer : null;
+    const property = object.properties.find(item => keyOf(ts, item) === key);
+    return property && ts.isPropertyAssignment(property) ? property.initializer : null;
 };
-
 /** A literal value object maps every exported function to its real sibling import. */
 function realFunctions(ts, value, names, imports, rel, serviceRel) {
-  if (!value || !ts.isObjectLiteralExpression(value) || value.properties.length !== names.length) return false;
-  const remaining = new Set(names);
-  for (const property of value.properties) {
-    const key = keyOf(ts, property);
-    const identifier = ts.isShorthandPropertyAssignment(property) ? property.name : property.initializer;
-    if (!remaining.delete(key) || !identifier || !ts.isIdentifier(identifier)) return false;
-    const binding = imports.get(identifier.text);
-    if (!binding || binding.name !== key || !binding.module.startsWith('.')) return false;
-    const target = path.posix.normalize(path.posix.join(path.posix.dirname(rel), binding.module)).replace(/\.[cm]?[jt]s$/u, '');
-    if (target !== serviceRel.replace(/\.ts$/u, '')) return false;
-  }
-  return remaining.size === 0;
+    if (!value || !ts.isObjectLiteralExpression(value) || value.properties.length !== names.length)
+        return false;
+    const remaining = new Set(names);
+    for (const property of value.properties) {
+        const key = keyOf(ts, property);
+        const identifier = ts.isShorthandPropertyAssignment(property) ? property.name : ts.isPropertyAssignment(property) ? property.initializer : undefined;
+        if (key === null || !remaining.delete(key) || !identifier || !ts.isIdentifier(identifier))
+            return false;
+        const binding = imports.get(identifier.text);
+        if (!binding || binding.name !== key || !binding.module.startsWith('.'))
+            return false;
+        const target = path.posix.normalize(path.posix.join(path.posix.dirname(rel), binding.module)).replace(/\.[cm]?[jt]s$/u, '');
+        if (target !== serviceRel.replace(/\.ts$/u, ''))
+            return false;
+    }
+    return remaining.size === 0;
 }
-
 /** Every node satisfying a predicate, within one spec. */
 function matchingNodes(ts, root, predicate) {
-  const found = [];
-  const visit = node => {
-    if (predicate(node)) found.push(node);
-    ts.forEachChild(node, visit);
-  };
-  visit(root);
-  return found;
+    const found = [];
+    const visit = (node) => {
+        if (predicate(node))
+            found.push(node);
+        ts.forEachChild(node, visit);
+    };
+    visit(root);
+    return found;
 }
-
 /** The declared variable initialized by an expression, including its await and call chain. */
 function initializedVariable(ts, expression) {
-  let cursor = expression;
-  let compiled = false;
-  let awaited = false;
-  while (cursor.parent && (ts.isAwaitExpression(cursor.parent) || ts.isPropertyAccessExpression(cursor.parent) || ts.isCallExpression(cursor.parent))) {
-    cursor = cursor.parent;
-    if (ts.isAwaitExpression(cursor)) awaited = true;
-    if (ts.isCallExpression(cursor) && ts.isPropertyAccessExpression(cursor.expression) && cursor.expression.name.text === 'compile') compiled = true;
-  }
-  if (!compiled || !awaited) return null;
-  const declaration = cursor.parent;
-  return declaration && ts.isVariableDeclaration(declaration) && ts.isIdentifier(declaration.name) ? declaration.name.text : null;
+    let cursor = expression;
+    let compiled = false;
+    let awaited = false;
+    while (cursor.parent && (ts.isAwaitExpression(cursor.parent) || ts.isPropertyAccessExpression(cursor.parent) || ts.isCallExpression(cursor.parent))) {
+        cursor = cursor.parent;
+        if (ts.isAwaitExpression(cursor))
+            awaited = true;
+        if (ts.isCallExpression(cursor) && ts.isPropertyAccessExpression(cursor.expression) && cursor.expression.name.text === 'compile')
+            compiled = true;
+    }
+    if (!compiled || !awaited)
+        return null;
+    const declaration = cursor.parent;
+    return declaration && ts.isVariableDeclaration(declaration) && ts.isIdentifier(declaration.name) ? declaration.name.text : null;
 }
-
 /** The subject variable receiving module.get, whether declared there or assigned in beforeEach. */
 function retrievedVariable(ts, call) {
-  let cursor = call;
-  while (cursor.parent && (ts.isAwaitExpression(cursor.parent) || ts.isParenthesizedExpression(cursor.parent))) cursor = cursor.parent;
-  const parent = cursor.parent;
-  if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) return parent.name.text;
-  if (parent && ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(parent.left)) return parent.left.text;
-  return null;
+    let cursor = call;
+    while (cursor.parent && (ts.isAwaitExpression(cursor.parent) || ts.isParenthesizedExpression(cursor.parent)))
+        cursor = cursor.parent;
+    const parent = cursor.parent;
+    if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name))
+        return parent.name.text;
+    if (parent && ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(parent.left))
+        return parent.left.text;
+    return null;
+}
+/** The `.text` of a node's `name`, when the node has an identifier-like name. */
+function nameTextOf(node) {
+    // reason: a loose compiler-API node; only declarations carry a `name`, and its `.text` is read when it is a string
+    const name = node?.name;
+    return typeof name?.text === 'string' ? name.text : undefined;
 }
-
 /** A helper returning the retrieved subject is followed to the variable receiving its result. */
 function retrievedSubjects(ts, read, sourceFile) {
-  const direct = retrievedVariable(ts, read);
-  if (direct) return [direct];
-  if (!read.parent || !ts.isReturnStatement(read.parent)) return [];
-  let helper = read.parent;
-  while (helper.parent && !ts.isFunctionLike(helper)) helper = helper.parent;
-  const name = helper.name?.text ?? helper.parent?.name?.text;
-  if (!name) return [];
-  return matchingNodes(ts, sourceFile, node => ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === name)
-    .map(node => retrievedVariable(ts, node)).filter(Boolean);
+    const direct = retrievedVariable(ts, read);
+    if (direct)
+        return [direct];
+    if (!read.parent || !ts.isReturnStatement(read.parent))
+        return [];
+    let helper = read.parent;
+    while (helper.parent && !ts.isFunctionLike(helper))
+        helper = helper.parent;
+    const name = nameTextOf(helper) ?? nameTextOf(helper.parent);
+    if (!name)
+        return [];
+    return matchingNodes(ts, sourceFile, node => ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === name)
+        .map(node => retrievedVariable(ts, node)).filter((variable) => Boolean(variable));
 }
-
 /** The same compiled module retrieves the matching token and its result actually calls a subject function. */
 function retrievedSubjectUsed(ts, call, token, names) {
-  const moduleName = initializedVariable(ts, call);
-  if (!moduleName) return false;
-  const sourceFile = call.getSourceFile();
-  const reads = matchingNodes(ts, sourceFile, node => {
-    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return false;
-    const member = node.expression;
-    return ts.isIdentifier(member.expression) && member.expression.text === moduleName && member.name.text === 'get'
-      && node.arguments.length === 1 && ts.isIdentifier(node.arguments[0]) && node.arguments[0].text === token.text;
-  });
-  return reads.some(read => {
-    const subjects = retrievedSubjects(ts, read, sourceFile);
-    return matchingNodes(ts, sourceFile, node => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
-      && ts.isIdentifier(node.expression.expression) && subjects.includes(node.expression.expression.text) && names.includes(node.expression.name.text)).length > 0;
-  });
+    const moduleName = initializedVariable(ts, call);
+    if (!moduleName)
+        return false;
+    const sourceFile = call.getSourceFile();
+    const reads = matchingNodes(ts, sourceFile, node => {
+        if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression))
+            return false;
+        const member = node.expression;
+        const first = node.arguments[0];
+        return ts.isIdentifier(member.expression) && member.expression.text === moduleName && member.name.text === 'get'
+            && node.arguments.length === 1 && first !== undefined && ts.isIdentifier(first) && first.text === token.text;
+    });
+    return reads.some(read => {
+        const subjects = retrievedSubjects(ts, read, sourceFile);
+        return matchingNodes(ts, sourceFile, node => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
+            && ts.isIdentifier(node.expression.expression) && subjects.includes(node.expression.expression.text) && names.includes(node.expression.name.text)).length > 0;
+    });
 }
-
 /** A pure function service has exactly one real subject value provider, retrieved and exercised through Nest. */
 export function checkFunctionSubject({ ts, rel, serviceRel, imports, call, list, names, report }) {
-  const provider = list.elements[0];
-  const shape = provider && ts.isObjectLiteralExpression(provider) && provider.properties.length === 2;
-  const token = shape ? propertyValue(ts, provider, 'provide') : null;
-  const value = shape ? propertyValue(ts, provider, 'useValue') : null;
-  if (list.elements.length !== 1 || !token || !ts.isIdentifier(token) || !realFunctions(ts, value, names, imports, rel, serviceRel)) {
-    report(provider ?? list, `${rel}: a function-only subject needs exactly one { provide: TOKEN, useValue: { ...realFunctions } } provider containing every callable export imported from ./${path.posix.basename(serviceRel, '.ts')}.`);
-    return;
-  }
-  if (!retrievedSubjectUsed(ts, call, token, names)) report(list, `${rel}: retrieve the function subject with moduleRef.get(TOKEN) from this compiled testing module and exercise a function on the returned subject.`);
+    const provider = list.elements[0];
+    const shape = provider && ts.isObjectLiteralExpression(provider) && provider.properties.length === 2;
+    const token = shape ? propertyValue(ts, provider, 'provide') : null;
+    const value = shape ? propertyValue(ts, provider, 'useValue') : null;
+    if (list.elements.length !== 1 || !token || !ts.isIdentifier(token) || !realFunctions(ts, value, names, imports, rel, serviceRel)) {
+        report(provider ?? list, `${rel}: a function-only subject needs exactly one { provide: TOKEN, useValue: { ...realFunctions } } provider containing every callable export imported from ./${path.posix.basename(serviceRel, '.ts')}.`);
+        return;
+    }
+    if (!retrievedSubjectUsed(ts, call, token, names))
+        report(list, `${rel}: retrieve the function subject with moduleRef.get(TOKEN) from this compiled testing module and exercise a function on the returned subject.`);
 }

package/runtime/scripts/hfs/architecture/hfs-graph.d.mts

@@ -0,0 +1,78 @@
+import type { Node, SourceFile, TypeChecker } from 'typescript';
+import type { ArchitectureConfig, TypeScriptApi } from './config.mjs';
+type Resolver = ArchitectureConfig['hfs'];
+/** One import, re-export or type-only import the TypeScript context recorded between two files (absolute `to`). */
+export interface ContextEdge {
+    to: string;
+    runtime: boolean;
+    line: number;
+    column: number;
+    specifier: string;
+    reexport?: boolean;
+    /** The import or export declaration (or import type, require call) the edge comes from. */
+    declaration: Node;
+}
+/** The part of the TypeScript context the graph reads: the loaded source files and their outgoing edges. */
+export interface GraphContext {
+    files: Iterable<SourceFile>;
+    edges: Map<string, ContextEdge[]>;
+}
+/** The TypeScript context a check receives: the graph's inputs plus the compiler API and the per-file checker. */
+export interface CheckContext extends GraphContext {
+    ts: TypeScriptApi;
+    checkerFor: (fileName: string) => TypeChecker;
+}
+/** A graph.files node: a production source file classified by the slot manifest. */
+export interface GraphFile {
+    abs: string;
+    rel: string;
+    slot: string | null;
+    status: string;
+    tier: string | null;
+    owner: ReturnType<Resolver['ownerOf']> | null;
+    sourceFile: SourceFile;
+}
+/** A graph.edges entry: a context edge between two graphed files, by repository-relative path. */
+export interface GraphEdge {
+    from: string;
+    to: string;
+    runtime: boolean;
+    line: number;
+    column: number;
+    specifier: string;
+    reexport: boolean;
+    edge: ContextEdge;
+}
+/** What a graph-based check receives. */
+export interface CheckInput {
+    config: ArchitectureConfig;
+    graph: HfsGraph;
+    context: CheckContext;
+}
+/** One finding a check reports: the rule, a message, a location, and whatever extra fields the rule adds. */
+export interface ArchitectureViolation {
+    ruleId: string;
+    message: string;
+    path?: string;
+    line?: number;
+    column?: number;
+    [extra: string]: unknown;
+}
+/** An owner instance that holds at least one graph file. */
+export interface OwnerRoot {
+    slot: string;
+    root: string;
+    tier: string;
+}
+/** What `buildHfsGraph` returns. */
+export interface HfsGraph {
+    profile: string;
+    resolver: Resolver;
+    files: Map<string, GraphFile>;
+    edges: GraphEdge[];
+    unit: (rel: string) => string | null;
+    ownerRoots: Map<string, OwnerRoot>;
+    abs: (file: string) => string | null;
+}
+export declare function buildHfsGraph(config: ArchitectureConfig, context: GraphContext): HfsGraph;
+export {};

package/runtime/scripts/hfs/architecture/hfs-graph.mjs

@@ -1,6 +1,5 @@
 import { canonical } from './config.mjs';
 import { relativePath } from './typescript.mjs';
-
 /**
  * The file and owner graph the HFS architecture checks share. Every production source file the TypeScript context
  * loaded becomes a node classified by the slot manifest (config.hfs is the resolver of scripts/hfs/slots.mjs);
@@ -17,57 +16,62 @@ import { relativePath } from './typescript.mjs';
  */
 // Every production source file the TypeScript context loaded, as a graph.files node keyed by its repository-relative path.
 const collectFiles = (config, context, resolver) => {
-  const files = new Map();
-  const absolute = new Map();
-  for (const sourceFile of context.files) {
-    const file = canonical(sourceFile.fileName);
-    const rel = relativePath(config.root, file);
-    if (rel.startsWith('..')) continue;
-    const classified = resolver.classifyPath(rel);
-    files.set(rel, {
-      abs: file,
-      rel,
-      slot: classified.slot ?? null,
-      status: classified.status,
-      tier: classified.slot ? resolver.tierOf(rel) : null,
-      owner: classified.slot ? resolver.ownerOf(rel) : null,
-      sourceFile,
-    });
-    absolute.set(file, rel);
-  }
-  return { files, absolute };
+    const files = new Map();
+    const absolute = new Map();
+    for (const sourceFile of context.files) {
+        const file = canonical(sourceFile.fileName);
+        const rel = relativePath(config.root, file);
+        if (rel.startsWith('..'))
+            continue;
+        const classified = resolver.classifyPath(rel);
+        files.set(rel, {
+            abs: file,
+            rel,
+            slot: classified.slot ?? null,
+            status: classified.status,
+            tier: classified.slot ? resolver.tierOf(rel) : null,
+            owner: classified.slot ? resolver.ownerOf(rel) : null,
+            sourceFile,
+        });
+        absolute.set(file, rel);
+    }
+    return { files, absolute };
 };
-
 // Every import, re-export and type-only import between two graphed files, as rel-path edges.
 const collectEdges = (context, absolute) => {
-  const edges = [];
-  for (const [file, list] of context.edges) {
-    const from = absolute.get(file);
-    if (!from) continue;
-    for (const edge of list) {
-      const to = absolute.get(edge.to);
-      if (!to || to === from) continue;
-      edges.push({ from, to, runtime: edge.runtime, line: edge.line, column: edge.column, specifier: edge.specifier, reexport: Boolean(edge.reexport), edge });
+    const edges = [];
+    for (const [file, list] of context.edges) {
+        const from = absolute.get(file);
+        if (!from)
+            continue;
+        for (const edge of list) {
+            const to = absolute.get(edge.to);
+            if (!to || to === from)
+                continue;
+            edges.push({ from, to, runtime: edge.runtime, line: edge.line, column: edge.column, specifier: edge.specifier, reexport: Boolean(edge.reexport), edge });
+        }
     }
-  }
-  return edges;
+    return edges;
 };
-
 export function buildHfsGraph(config, context) {
-  const resolver = config.hfs;
-  const { files, absolute } = collectFiles(config, context, resolver);
-  const edges = collectEdges(context, absolute);
-  const unit = rel => {
-    const node = files.get(rel);
-    if (!node) return null;
-    if (node.owner) return `${node.owner.slot}:${node.owner.root}`;
-    const classified = resolver.classifyPath(rel);
-    return classified.slot ? `${classified.slot}:${classified.root}` : null;
-  };
-  const ownerRoots = new Map();
-  for (const node of files.values()) if (node.owner) {
-    const key = `${node.owner.slot}:${node.owner.root}`;
-    if (!ownerRoots.has(key)) ownerRoots.set(key, { slot: node.owner.slot, root: node.owner.root, tier: resolver.slot(node.owner.slot).tier });
-  }
-  return { profile: resolver.repo.profile, resolver, files, edges, unit, ownerRoots, abs: file => absolute.get(file) ?? null };
+    const resolver = config.hfs;
+    const { files, absolute } = collectFiles(config, context, resolver);
+    const edges = collectEdges(context, absolute);
+    const unit = (rel) => {
+        const node = files.get(rel);
+        if (!node)
+            return null;
+        if (node.owner)
+            return `${node.owner.slot}:${node.owner.root}`;
+        const classified = resolver.classifyPath(rel);
+        return classified.slot ? `${classified.slot}:${classified.root}` : null;
+    };
+    const ownerRoots = new Map();
+    for (const node of files.values())
+        if (node.owner) {
+            const key = `${node.owner.slot}:${node.owner.root}`;
+            if (!ownerRoots.has(key))
+                ownerRoots.set(key, { slot: node.owner.slot, root: node.owner.root, tier: resolver.slot(node.owner.slot)?.tier ?? '' }); // the owner slot came from resolver.ownerOf, so the manifest holds it
+        }
+    return { profile: resolver.repo.profile, resolver, files, edges, unit, ownerRoots, abs: (file) => absolute.get(file) ?? null };
 }

package/runtime/scripts/hfs/architecture/hfs.d.mts

@@ -0,0 +1,135 @@
+import type { Resolver } from '../slots.mjs';
+import type { ArchitectureConfig } from './config.mjs';
+import type { ArchitectureViolation } from './hfs-graph.mjs';
+/**
+ * HFS repository-tree check (knowledge/hfs/README.md): every StarCi repository is an
+ * apps/<app>/ monorepo on npm with a fixed root-entry allowlist; backend composition lives in
+ * apps/<app>/src and shared source under src/{features,modules,tests} with the three module tiers
+ * domain/platform/integrations; frontend source lives only under apps/<app>/src. The judged tree is
+ * the tracked one (`git ls-files` from the target root); a target outside a work tree falls back to
+ * the filesystem view so fixtures and un-tracked checkouts are judged the same way.
+ */
+export declare const HFS_RULE_IDS: string[];
+/** The shape of the uniform tree view (see treeView). */
+export interface TreeView {
+    source: 'git' | 'fs';
+    top: string[];
+    children: (dir: string) => string[];
+    hasDir: (dir: string) => boolean;
+    hasFile: (file: string) => boolean;
+    files: () => string[];
+}
+/** The part of the layout contract the tree check reads; `checkHfsWithoutConfig` has only the root and the kinds. */
+type HfsConfig = Pick<ArchitectureConfig, 'root'> & Partial<Pick<ArchitectureConfig, 'kinds' | 'hfs'>>;
+/** The tree view of a list of tracked paths (posix, root-relative): what the git view answers, for a list already in hand. */
+export declare function trackedTreeView(tracked: string[]): TreeView;
+/** Presentation checks shared by the product HFS gate and this runtime's own standalone gate. */
+export declare function checkRepoPresentation({ root, runtime, tree, profile, edition }: {
+    root: string;
+    runtime?: boolean;
+    tree?: TreeView;
+    profile?: string;
+    edition?: string;
+}): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        source: string;
+    };
+};
+export declare function checkHfs(config: HfsConfig): {
+    violations: never[];
+    coverage: {
+        status: string;
+        source?: never;
+        rootEntries?: never;
+        apps?: never;
+        ruleIds?: never;
+    };
+} | {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        source: "fs" | "git";
+        rootEntries: number;
+        apps: string[];
+        ruleIds: string[];
+    };
+};
+/**
+ * The HFS tree check of the app root (`resolver` is the app's): the README, the root entries the app-root slots allow and require,
+ * the automatic gates (hooks, the root scripts they call, the workflows) and the hooks path. `starci app check` runs it once per app; the
+ * machine runs checkHfs once per side folder.
+ */
+export declare function checkAppRoot({ root, resolver, tree }: {
+    root: string;
+    resolver: Resolver;
+    tree?: TreeView;
+}): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        source: "fs" | "git";
+        hooksPath: {
+            status: string;
+            reason: string;
+            hooks?: never;
+        } | {
+            status: string;
+            reason?: never;
+            hooks?: never;
+        } | {
+            status: string;
+            hooks: "missing" | "installed" | "empty" | "unreadable";
+            reason?: never;
+        };
+        rootEntries: number;
+    };
+};
+/** Keep tree findings visible even when the TypeScript architecture config is invalid. */
+export declare function checkHfsWithoutConfig(repositoryRoot: string): {
+    violations: never[];
+    coverage: {
+        status: string;
+        source?: never;
+        rootEntries?: never;
+        apps?: never;
+        ruleIds?: never;
+    };
+} | {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        source: "fs" | "git";
+        rootEntries: number;
+        apps: string[];
+        ruleIds: string[];
+    };
+} | {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        source: "fs" | "git";
+        hooksPath: {
+            status: string;
+            reason: string;
+            hooks?: never;
+        } | {
+            status: string;
+            reason?: never;
+            hooks?: never;
+        } | {
+            status: string;
+            hooks: "missing" | "installed" | "empty" | "unreadable";
+            reason?: never;
+        };
+        rootEntries: number;
+    };
+} | {
+    violations: never[];
+    coverage: {
+        status: string;
+        reason: string;
+    };
+};
+export {};