@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/starcistacks-runtime.d.mts

@@ -0,0 +1,7 @@
+type Parsed = any;
+export declare const appEdition: (repoRoot: string) => Parsed;
+/** An HFS app uses its edition's slot shape; other repository declarations still receive Swarm runtime checks. */
+export declare function applicationStackFindings(repoRoot: string): Parsed[];
+/** Lite may retain value-free development custody metadata without declaring a self-hosted development stack. */
+export declare function liteCustodyDirectory(directory: string): boolean;
+export {};

package/runtime/scripts/hfs/starcistacks-runtime.mjs

@@ -7,55 +7,66 @@ import { stacksFindings } from './rules/stacks.mjs';
 import { stacksRuntimeFindings } from './rules/stacks-runtime.mjs';
 import { findStackDeclaration } from '../lib/stack-declaration.mjs';
 import { loadSlotManifest, openHfs } from './slots.mjs';
-
 /** Source paths admitted to stack and scheduling checks; never descend through symlinks. */
 function safeSourceDirectory(repoRoot, relative) {
-  const root = path.resolve(repoRoot);
-  let cursor = path.resolve(root, relative);
-  while (cursor !== root) {
-    try { if (fs.lstatSync(cursor).isSymbolicLink()) return false; } catch { return false; }
-    cursor = path.dirname(cursor);
-  }
-  return true;
+    const root = path.resolve(repoRoot);
+    let cursor = path.resolve(root, relative);
+    while (cursor !== root) {
+        try {
+            if (fs.lstatSync(cursor).isSymbolicLink())
+                return false;
+        }
+        catch {
+            return false;
+        }
+        cursor = path.dirname(cursor);
+    }
+    return true;
 }
-
 function applicationStackFiles(repoRoot) {
-  return ['.starcistacks', '.github/workflows', 'deploy', 'scripts'].flatMap(relative => {
-    if (!safeSourceDirectory(repoRoot, relative)) return [];
-    return walkFiles(path.join(repoRoot, relative), { ignoreReadErrors: true, exclude: (_name, _file, entry) => entry.isSymbolicLink() })
-      .map(file => path.relative(repoRoot, file).replaceAll('\\', '/'));
-  });
+    return ['.starcistacks', '.github/workflows', 'deploy', 'scripts'].flatMap((relative) => {
+        if (!safeSourceDirectory(repoRoot, relative))
+            return [];
+        return walkFiles(path.join(repoRoot, relative), { ignoreReadErrors: true, exclude: (_name, _file, entry) => entry.isSymbolicLink() })
+            .map((file) => path.relative(repoRoot, file).replaceAll('\\', '/'));
+    });
 }
-
-export const appEdition = repoRoot => readJson(repoRoot, 'hfs.json')?.edition ?? 'full';
-
+export const appEdition = (repoRoot) => readJson(repoRoot, 'hfs.json')?.edition ?? 'full';
 /** An HFS app uses its edition's slot shape; other repository declarations still receive Swarm runtime checks. */
 export function applicationStackFindings(repoRoot) {
-  const files = applicationStackFiles(repoRoot), declaration = readJson(repoRoot, 'hfs.json');
-  if (declaration?.kind === 'app') {
-    try {
-      const resolver = openHfs({ declaration, manifest: loadSlotManifest() });
-      const findings = stacksFindings({ repoRoot, files, resolver }), manifestFile = '.starcistacks/application-stacks.yaml';
-      if (resolver.slot('app.starcistacks')?.requires?.includes('application-stacks.yaml') && !files.includes(manifestFile))
-        return [{ code: 'HFS_STACKS_SHAPE', level: 'error', path: manifestFile, message: `${manifestFile}: the app stacks slot requires this declaration` }, ...findings];
-      return findings;
-    } catch (error) {
-      return [{ code: 'HFS_STACKS_SHAPE', level: 'error', path: 'hfs.json', message: `hfs.json: cannot resolve the app stacks shape: ${error.message}` }];
+    const files = applicationStackFiles(repoRoot), declaration = readJson(repoRoot, 'hfs.json');
+    if (declaration?.kind === 'app') {
+        try {
+            const resolver = openHfs({ declaration, manifest: loadSlotManifest() });
+            const findings = stacksFindings({ repoRoot, files, resolver }), manifestFile = '.starcistacks/application-stacks.yaml';
+            if (resolver.slot('app.starcistacks')?.requires?.includes('application-stacks.yaml') && !files.includes(manifestFile))
+                return [{ code: 'HFS_STACKS_SHAPE', level: 'error', path: manifestFile, message: `${manifestFile}: the app stacks slot requires this declaration` }, ...findings];
+            return findings;
+        }
+        catch (error) {
+            return [{ code: 'HFS_STACKS_SHAPE', level: 'error', path: 'hfs.json', message: `hfs.json: cannot resolve the app stacks shape: ${error.message}` }];
+        }
     }
-  }
-  const doc = findStackDeclaration(repoRoot).doc;
-  return doc ? stacksRuntimeFindings({ repoRoot, files, doc }) : [];
+    const doc = findStackDeclaration(repoRoot).doc;
+    return doc ? stacksRuntimeFindings({ repoRoot, files, doc }) : [];
 }
-
 /** Lite may retain value-free development custody metadata without declaring a self-hosted development stack. */
 export function liteCustodyDirectory(directory) {
-  let entries;
-  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return false; }
-  return entries.length > 0 && entries.every(entry => {
-    if (entry.isSymbolicLink()) return false;
-    if (entry.isFile()) return entry.name === 'environment.json';
-    if (!entry.isDirectory() || entry.name !== 'secrets') return false;
-    return fs.readdirSync(path.join(directory, entry.name), { withFileTypes: true })
-      .every(secret => secret.isFile() && !secret.isSymbolicLink() && (secret.name === '.gitkeep' || /^[a-z0-9-]+\.enc(?:\.yaml)?$/.test(secret.name)));
-  });
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    return entries.length > 0 && entries.every(entry => {
+        if (entry.isSymbolicLink())
+            return false;
+        if (entry.isFile())
+            return entry.name === 'environment.json';
+        if (!entry.isDirectory() || entry.name !== 'secrets')
+            return false;
+        return fs.readdirSync(path.join(directory, entry.name), { withFileTypes: true })
+            .every(secret => secret.isFile() && !secret.isSymbolicLink() && (secret.name === '.gitkeep' || /^[a-z0-9-]+\.enc(?:\.yaml)?$/.test(secret.name)));
+    });
 }

package/runtime/scripts/hfs/test-world-slot.d.mts

@@ -0,0 +1,2 @@
+/** True when `slot` (a slot id, or a file's slot) belongs to the test world family. */
+export declare const isTestWorldSlot: (slot: unknown) => boolean;

package/runtime/scripts/hfs/test-world-slot.mjs

@@ -1,6 +1,5 @@
 // test-world-slot.mjs - the one answer of the machine checks to "is this slot the test world": the slot `be.tests.world` or one of its
 // sub-slots (`be.tests.world.kit`, the world's inlined helpers), which form one test composition root. The lint side asks the same of
 // the slot view through `inTestWorld` of packages/eslint/be/lib/hfs.mjs.
-
 /** True when `slot` (a slot id, or a file's slot) belongs to the test world family. */
 export const isTestWorldSlot = (slot) => typeof slot === 'string' && (slot === 'be.tests.world' || slot.startsWith('be.tests.world.'));

package/runtime/scripts/hfs/trailing-slashes.d.mts

@@ -0,0 +1,2 @@
+/** `text` without its trailing `/` characters. */
+export declare function trimTrailingSlashes(text: string): string;

package/runtime/scripts/hfs/trailing-slashes.mjs

@@ -1,8 +1,8 @@
 // Trailing-slash trimming for slot paths and generated roots, linear in the length of the text.
-
 /** `text` without its trailing `/` characters. */
 export function trimTrailingSlashes(text) {
-  let end = text.length;
-  while (end > 0 && text.codePointAt(end - 1) === 47) end -= 1;
-  return text.slice(0, end);
+    let end = text.length;
+    while (end > 0 && text.codePointAt(end - 1) === 47)
+        end -= 1;
+    return text.slice(0, end);
 }

package/runtime/scripts/hfs/tree-findings.d.mts

@@ -0,0 +1,9 @@
+import type { PathFinding } from './path-findings.mjs';
+import type { Resolver } from './slots.mjs';
+/** The tree findings of R03: empty directories, ghost siblings, untracked entries outside an ignored slot. */
+export declare function treeFindings({ repoRoot, resolver, tracked, reportedUntracked }: {
+    repoRoot: string;
+    resolver: Resolver;
+    tracked?: string[];
+    reportedUntracked?: Set<string>;
+}): PathFinding[];

package/runtime/scripts/hfs/tree-findings.mjs

@@ -1,22 +1,23 @@
 import { readTree, treeFacts, untrackedEntries } from './tree.mjs';
 import { liteStarciworkTreeFindings } from './path-findings.mjs';
-
 /** The tree findings of R03: empty directories, ghost siblings, untracked entries outside an ignored slot. */
 export function treeFindings({ repoRoot, resolver, tracked = [], reportedUntracked = new Set() }) {
-  const inIgnoredSlot = (rel) => resolver.classifyPath(`${rel}/.probe`).tracking === 'ignored';
-  const findings = liteStarciworkTreeFindings(repoRoot, resolver, tracked);
-  const facts = treeFacts(readTree(repoRoot, { isIgnored: inIgnoredSlot }));
-  for (const { path: dir, below } of facts.empty) {
-    findings.push({ code: 'HFS_EMPTY_DIR', level: 'error', path: dir, below, message: `${dir} has no file below it` + (below ? ` (nor in its ${below} sub-director${below === 1 && 'y' || 'ies'})` : '') + '; git tracks no empty directory, so it is a leftover' });
-  }
-  for (const { path: dir, of, distance } of facts.ghosts) {
-    findings.push({ code: 'HFS_GHOST_TREE', level: 'error', path: dir, of, distance, message: `${dir} is empty and ${distance} edit${distance === 1 ? '' : 's'} from its sibling ${of}: a renamed or misspelt structure that was never removed` });
-  }
-  for (const entry of untrackedEntries(repoRoot)) {
-    const bare = entry.replace(/\/$/, '');
-    if (reportedUntracked.has(bare)) continue;
-    const ignored = entry.endsWith('/') ? inIgnoredSlot(bare) : resolver.classifyPath(bare).tracking === 'ignored';
-    if (!ignored) findings.push({ code: 'HFS_UNTRACKED_ROOT_ENTRY', level: 'error', path: bare, message: `${entry} is neither tracked nor git-ignored, and no ignored slot owns it` });
-  }
-  return findings;
+    const inIgnoredSlot = (rel) => resolver.classifyPath(`${rel}/.probe`).tracking === 'ignored';
+    const findings = liteStarciworkTreeFindings(repoRoot, resolver, tracked);
+    const facts = treeFacts(readTree(repoRoot, { isIgnored: inIgnoredSlot }));
+    for (const { path: dir, below } of facts.empty) {
+        findings.push({ code: 'HFS_EMPTY_DIR', level: 'error', path: dir, below, message: `${dir} has no file below it` + (below ? ` (nor in its ${below} sub-director${below === 1 && 'y' || 'ies'})` : '') + '; git tracks no empty directory, so it is a leftover' });
+    }
+    for (const { path: dir, of, distance } of facts.ghosts) {
+        findings.push({ code: 'HFS_GHOST_TREE', level: 'error', path: dir, of, distance, message: `${dir} is empty and ${distance} edit${distance === 1 ? '' : 's'} from its sibling ${of}: a renamed or misspelt structure that was never removed` });
+    }
+    for (const entry of untrackedEntries(repoRoot)) {
+        const bare = entry.replace(/\/$/, '');
+        if (reportedUntracked.has(bare))
+            continue;
+        const ignored = entry.endsWith('/') ? inIgnoredSlot(bare) : resolver.classifyPath(bare).tracking === 'ignored';
+        if (!ignored)
+            findings.push({ code: 'HFS_UNTRACKED_ROOT_ENTRY', level: 'error', path: bare, message: `${entry} is neither tracked nor git-ignored, and no ignored slot owns it` });
+    }
+    return findings;
 }

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

@@ -0,0 +1,35 @@
+/** One directory of the walked tree. */
+export interface TreeNode {
+    name: string;
+    rel: string;
+    files: number;
+    dirs: TreeNode[];
+}
+/** The tree's own findings: topmost empty directories and ghost siblings. */
+export interface TreeFacts {
+    empty: Array<{
+        path: string;
+        below: number;
+    }>;
+    ghosts: Array<{
+        path: string;
+        of: string;
+        distance: number;
+    }>;
+}
+/**
+ * The directory tree of `repoRoot` below any `ignored` slot: {name, rel, files, dirs: [node]}. A directory in an
+ * ignored slot is not entered and counts as holding a file (its content is build output the repository does not own).
+ * Links are not followed.
+ */
+export declare function readTree(repoRoot: string, { isIgnored }: {
+    isIgnored: (rel: string) => boolean;
+}): TreeNode;
+/**
+ * The tree's own findings: `empty` are the topmost directories with no file anywhere below them (each with the number of
+ * directories it holds); `ghosts` are pairs of sibling directories within GHOST_DISTANCE edits where `ghost` has no file
+ * below it and `of` is its lookalike.
+ */
+export declare function treeFacts(tree: TreeNode): TreeFacts;
+/** Entries git neither tracks nor ignores, as it prints them (a wholly untracked directory is one entry ending in '/'). */
+export declare function untrackedEntries(repoRoot: string): string[];

package/runtime/scripts/hfs/tree.mjs

@@ -7,80 +7,90 @@ import path from 'node:path';
 import { lsFiles } from '../api/git/ls-files.mjs';
 import { gitOutputOf } from '../lib/git.mjs';
 import { posixPath } from '../lib/path-key.mjs';
-
 /** Directory names no tree check enters: git's own store and installed packages. */
 const NEVER_WALKED = new Set(['.git', 'node_modules']);
 /** Two sibling names this close (Levenshtein) are the same name misspelt. */
 const GHOST_DISTANCE = 2;
-
 /** Levenshtein distance of two names. */
 function editDistance(a, b) {
-  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i += 1) {
-    const row = [i];
-    for (let j = 1; j <= b.length; j += 1) row[j] = Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
-    previous = row;
-  }
-  return previous[b.length];
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j += 1)
+            row[j] = Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        previous = row;
+    }
+    return previous[b.length];
 }
-
 /**
  * The directory tree of `repoRoot` below any `ignored` slot: {name, rel, files, dirs: [node]}. A directory in an
  * ignored slot is not entered and counts as holding a file (its content is build output the repository does not own).
  * Links are not followed.
  */
 export function readTree(repoRoot, { isIgnored }) {
-  const walk = (abs, rel) => {
-    const node = { name: path.basename(abs), rel, files: 0, dirs: [] };
-    let entries;
-    try { entries = fs.readdirSync(abs, { withFileTypes: true }); } catch { return node; }
-    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
-      if (!entry.isDirectory()) { node.files += 1; continue; }
-      if (NEVER_WALKED.has(entry.name)) continue;
-      if (isIgnored(childRel)) { node.files += 1; continue; }
-      node.dirs.push(walk(path.join(abs, entry.name), childRel));
-    }
-    return node;
-  };
-  return walk(repoRoot, '');
+    const walk = (abs, rel) => {
+        const node = { name: path.basename(abs), rel, files: 0, dirs: [] };
+        let entries;
+        try {
+            entries = fs.readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            return node;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (!entry.isDirectory()) {
+                node.files += 1;
+                continue;
+            }
+            if (NEVER_WALKED.has(entry.name))
+                continue;
+            if (isIgnored(childRel)) {
+                node.files += 1;
+                continue;
+            }
+            node.dirs.push(walk(path.join(abs, entry.name), childRel));
+        }
+        return node;
+    };
+    return walk(repoRoot, '');
 }
-
 const holdsNoFile = (node) => node.files === 0 && node.dirs.every(holdsNoFile);
 const countDirs = (node) => node.dirs.reduce((sum, child) => sum + 1 + countDirs(child), 0);
-
 function collectGhosts(node, ghosts) {
-  for (const [i, a] of node.dirs.entries()) {
-    for (const b of node.dirs.slice(i + 1)) {
-      if (editDistance(a.name, b.name) > GHOST_DISTANCE) continue;
-      if (holdsNoFile(a)) ghosts.push({ path: a.rel, of: b.rel, distance: editDistance(a.name, b.name) });
-      if (holdsNoFile(b)) ghosts.push({ path: b.rel, of: a.rel, distance: editDistance(a.name, b.name) });
+    for (const [i, a] of node.dirs.entries()) {
+        for (const b of node.dirs.slice(i + 1)) {
+            if (editDistance(a.name, b.name) > GHOST_DISTANCE)
+                continue;
+            if (holdsNoFile(a))
+                ghosts.push({ path: a.rel, of: b.rel, distance: editDistance(a.name, b.name) });
+            if (holdsNoFile(b))
+                ghosts.push({ path: b.rel, of: a.rel, distance: editDistance(a.name, b.name) });
+        }
     }
-  }
 }
-
 function collectTreeFacts(node, empty, ghosts) {
-  for (const child of node.dirs) {
-    if (holdsNoFile(child)) empty.push({ path: child.rel, below: countDirs(child) });
-    else collectTreeFacts(child, empty, ghosts);
-  }
-  collectGhosts(node, ghosts);
+    for (const child of node.dirs) {
+        if (holdsNoFile(child))
+            empty.push({ path: child.rel, below: countDirs(child) });
+        else
+            collectTreeFacts(child, empty, ghosts);
+    }
+    collectGhosts(node, ghosts);
 }
-
 /**
  * The tree's own findings: `empty` are the topmost directories with no file anywhere below them (each with the number of
  * directories it holds); `ghosts` are pairs of sibling directories within GHOST_DISTANCE edits where `ghost` has no file
  * below it and `of` is its lookalike.
  */
 export function treeFacts(tree) {
-  const empty = [];
-  const ghosts = [];
-  collectTreeFacts(tree, empty, ghosts);
-  return { empty, ghosts };
+    const empty = [];
+    const ghosts = [];
+    collectTreeFacts(tree, empty, ghosts);
+    return { empty, ghosts };
 }
-
 /** Entries git neither tracks nor ignores, as it prints them (a wholly untracked directory is one entry ending in '/'). */
 export function untrackedEntries(repoRoot) {
-  const out = gitOutputOf(lsFiles(['-z', '--others', '--exclude-standard', '--directory', '--no-empty-directory'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files');
-  return out.split('\0').filter(Boolean).map(posixPath);
+    const out = gitOutputOf(lsFiles(['-z', '--others', '--exclude-standard', '--directory', '--no-empty-directory'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files');
+    return out.split('\0').filter(Boolean).map(posixPath);
 }

package/runtime/scripts/hfs/typescript-programs.d.mts

@@ -0,0 +1,36 @@
+import type * as TypeScript from 'typescript';
+/** The caller's TypeScript compiler module. */
+export type TsApi = typeof import('typescript');
+/** Share compiler inputs only until this check finishes; nested callers join the same run. */
+export declare function withTypeScriptProgramRun<T>(run: () => T): T;
+/**
+ * build(), shared inside a program run by every caller that asks for the same kind, compiler and input. An input that
+ * is not plain data (a function, a class instance) is never shared.
+ */
+export declare function sharedInProgramRun<T>(kind: string, ts: TsApi, input: unknown, build: () => T): T;
+/** ts.createProgram, shared inside a program run. */
+export declare function createTypeScriptProgram(ts: TsApi, { rootNames, options, projectReferences }: {
+    rootNames: readonly string[];
+    options: TypeScript.CompilerOptions;
+    projectReferences?: readonly TypeScript.ProjectReference[] | undefined;
+}): TypeScript.Program;
+/** A tsconfig read by readTypeScriptProject: the parsed project, or null with the read error. */
+export type ProjectRead = {
+    read: {
+        config?: unknown;
+        error: TypeScript.Diagnostic;
+    };
+    parsed: null;
+} | {
+    read: {
+        config?: unknown;
+        error?: undefined;
+    };
+    parsed: TypeScript.ParsedCommandLine;
+};
+/** Read and expand a tsconfig with the caller's TypeScript compiler and optional tracked file reader. */
+export declare function readTypeScriptProject(ts: TsApi, configFile: string, readFile?: (file: string) => string | undefined): ProjectRead;
+/** Resolve a project reference with the compiler's API, including older compiler fallback. */
+export declare function typeScriptProjectReferencePath(ts: TsApi, reference: TypeScript.ProjectReference): string;
+/** Resolve an import using the selected project's compiler options. */
+export declare function resolveTypeScriptModule(ts: TsApi, specifier: string, from: string, options: TypeScript.CompilerOptions, host?: TypeScript.ModuleResolutionHost, cache?: TypeScript.ModuleResolutionCache): string | undefined;

package/runtime/scripts/hfs/typescript-programs.mjs

@@ -1,98 +1,95 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import path from 'node:path';
 import { byCodeUnit } from '../lib/list.mjs';
-
-// One TypeScript program per (compiler, root names, compiler options, project references) inside a program run, and
-// one value per (kind, compiler, input) for what callers derive from those programs (the architecture context).
-// A caller (canon-scan's architecture machine, a script checker) opens one run around its work and releases it after,
-// so nothing built here outlives the run that built it. Outside a run every call
-// builds afresh.
 const runs = new AsyncLocalStorage();
-
 /** Share compiler inputs only until this check finishes; nested callers join the same run. */
 export function withTypeScriptProgramRun(run) {
-  return runs.getStore() ? run() : runs.run(new Map(), run);
+    return runs.getStore() ? run() : runs.run(new Map(), run);
 }
-
-
 function keyOf(value) {
-  if (value === undefined) return 'u';
-  if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return JSON.stringify(value);
-  if (Array.isArray(value)) {
-    const items = value.map(keyOf);
-    return items.includes(null) ? null : `[${items.join(',')}]`;
-  }
-  if (typeof value !== 'object' || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) return null;
-  const entries = [];
-  for (const name of Object.keys(value).sort(byCodeUnit)) {
-    const item = keyOf(value[name]);
-    if (item === null) return null;
-    entries.push(`${JSON.stringify(name)}:${item}`);
-  }
-  return `{${entries.join(',')}}`;
+    if (value === undefined)
+        return 'u';
+    if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        const items = value.map(keyOf);
+        return items.includes(null) ? null : `[${items.join(',')}]`;
+    }
+    if (typeof value !== 'object' || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null))
+        return null;
+    const entries = [];
+    for (const name of Object.keys(value).sort(byCodeUnit)) {
+        const item = keyOf(value[name]);
+        if (item === null)
+            return null;
+        entries.push(`${JSON.stringify(name)}:${item}`);
+    }
+    return `{${entries.join(',')}}`;
 }
-
 /**
  * build(), shared inside a program run by every caller that asks for the same kind, compiler and input. An input that
  * is not plain data (a function, a class instance) is never shared.
  */
 export function sharedInProgramRun(kind, ts, input, build) {
-  const values = runs.getStore();
-  const key = values ? keyOf(input) : null;
-  if (key === null) return build();
-  let byKey = values.get(ts);
-  if (!byKey) {
-    byKey = new Map();
-    values.set(ts, byKey);
-  }
-  const id = `${kind}\0${key}`;
-  if (!byKey.has(id)) byKey.set(id, build());
-  return byKey.get(id);
+    const values = runs.getStore();
+    const key = values ? keyOf(input) : null;
+    if (key === null || !values)
+        return build();
+    let byKey = values.get(ts);
+    if (!byKey) {
+        byKey = new Map();
+        values.set(ts, byKey);
+    }
+    const id = `${kind}\0${key}`;
+    if (!byKey.has(id))
+        byKey.set(id, build());
+    return byKey.get(id);
 }
-
 /** ts.createProgram, shared inside a program run. */
 export function createTypeScriptProgram(ts, { rootNames, options, projectReferences }) {
-  return sharedInProgramRun('program', ts, { rootNames, options, projectReferences },
-    () => ts.createProgram({ rootNames, options, projectReferences, host: sharedSourceHost(ts, options) }));
+    return sharedInProgramRun('program', ts, { rootNames, options, projectReferences }, () => ts.createProgram({ rootNames, options, projectReferences, host: sharedSourceHost(ts, options) })); // exactOptionalPropertyTypes: the optional host and references are passed through as undefined, as before
 }
-
 function sharedSourceHost(ts, options) {
-  if (!runs.getStore()) return undefined;
-  const registry = sharedInProgramRun('documents', ts, null,
-    () => ts.createDocumentRegistry(ts.sys.useCaseSensitiveFileNames, ts.sys.getCurrentDirectory()));
-  const host = ts.createCompilerHost(options);
-  const readSource = host.getSourceFile;
-  // TypeScript's registry separates parse-affecting settings and Node module formats. Sharing syntax trees leaves
-  // module resolution and symbol/type caches with each program, including projects with different path aliases.
-  host.getSourceFile = (file, sourceOptions, onError, fresh) => {
-    if (fresh) return readSource(file, sourceOptions, onError, fresh);
-    let text;
-    try { text = host.readFile(file); } catch (error) {
-      onError?.(String(error.message ?? error));
-      text = '';
-    }
-    if (text === undefined) return undefined;
-    return registry.acquireDocument(file, options, ts.ScriptSnapshot.fromString(text), '0', undefined, sourceOptions);
-  };
-  return host;
+    if (!runs.getStore())
+        return undefined;
+    const registry = sharedInProgramRun('documents', ts, null, () => ts.createDocumentRegistry(ts.sys.useCaseSensitiveFileNames, ts.sys.getCurrentDirectory()));
+    const host = ts.createCompilerHost(options);
+    const readSource = host.getSourceFile;
+    // TypeScript's registry separates parse-affecting settings and Node module formats. Sharing syntax trees leaves
+    // module resolution and symbol/type caches with each program, including projects with different path aliases.
+    host.getSourceFile = (file, sourceOptions, onError, fresh) => {
+        if (fresh)
+            return readSource(file, sourceOptions, onError, fresh);
+        let text;
+        try {
+            text = host.readFile(file);
+        }
+        catch (error) {
+            onError?.(String(error.message ?? error));
+            text = '';
+        }
+        if (text === undefined)
+            return undefined;
+        return registry.acquireDocument(file, options, ts.ScriptSnapshot.fromString(text), '0', undefined, sourceOptions);
+    };
+    return host;
 }
-
 /** Read and expand a tsconfig with the caller's TypeScript compiler and optional tracked file reader. */
 export function readTypeScriptProject(ts, configFile, readFile = ts.sys.readFile) {
-  const read = ts.readConfigFile(configFile, readFile);
-  if (read.error) return { read, parsed: null };
-  const host = readFile === ts.sys.readFile ? ts.sys : { ...ts.sys, readFile };
-  return { read, parsed: ts.parseJsonConfigFileContent(read.config, host, path.dirname(configFile), undefined, configFile) };
+    const read = ts.readConfigFile(configFile, readFile);
+    if (read.error)
+        return { read: read, parsed: null };
+    const host = readFile === ts.sys.readFile ? ts.sys : { ...ts.sys, readFile };
+    return { read: read, parsed: ts.parseJsonConfigFileContent(read.config, host, path.dirname(configFile), undefined, configFile) };
 }
-
 /** Resolve a project reference with the compiler's API, including older compiler fallback. */
 export function typeScriptProjectReferencePath(ts, reference) {
-  if (typeof ts.resolveProjectReferencePath === 'function') return ts.resolveProjectReferencePath(reference);
-  return path.extname(reference.path) ? reference.path : path.join(reference.path, 'tsconfig.json');
+    if (typeof ts.resolveProjectReferencePath === 'function')
+        return ts.resolveProjectReferencePath(reference);
+    return path.extname(reference.path) ? reference.path : path.join(reference.path, 'tsconfig.json');
 }
-
 /** Resolve an import using the selected project's compiler options. */
 export function resolveTypeScriptModule(ts, specifier, from, options, host, cache) {
-  const resolverHost = host === undefined ? ts.sys : host;
-  return ts.resolveModuleName(specifier, from, options, resolverHost, cache).resolvedModule?.resolvedFileName;
+    const resolverHost = host === undefined ? ts.sys : host;
+    return ts.resolveModuleName(specifier, from, options, resolverHost, cache).resolvedModule?.resolvedFileName;
 }

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

@@ -0,0 +1,45 @@
+import type { AllowsResult } from './allows.mjs';
+import type { OpenedHfs, ClassifiedPath, RepoView, RuleParams } from './slots.mjs';
+import type { Parsed } from './manifest-shape.mjs';
+/** The frozen view of one side of an app that the lint factories hand their rules (`settings.starci.hfs`). */
+export interface HfsView {
+    repoRoot: string;
+    profile: string;
+    side: string | null;
+    edition: string;
+    grammar?: string;
+    apps: RepoView['apps'];
+    connections: RepoView['connections'];
+    patterns: readonly string[];
+    ruleParams: RuleParams | null;
+    relative: (file: string) => string;
+    classify: (file: string) => ClassifiedPath;
+    slotOf: (file: string) => string | null;
+    tierOf: (file: string) => string | null;
+    ownerOf: (file: string) => string | null;
+    allows: (file: string) => AllowsResult | null;
+    slot: OpenedHfs['slot'];
+}
+/**
+ * The view of the app folder on disk at `repoRoot`, against the manifest under `runtimeRoot`: a side folder (be/, fe/) finds the
+ * app-root hfs.json one level up and gets that side's view, so every linted file below it is judged by its own side's slots.
+ *
+ * @param {{ runtimeRoot: string, repoRoot: string }} input - Where the manifest copy lives and the side folder (or app root).
+ * @returns {object} The frozen view.
+ */
+export declare const openHfsView: ({ runtimeRoot, repoRoot }: {
+    runtimeRoot: string;
+    repoRoot: string;
+}) => HfsView;
+/**
+ * The view of one side of an in-memory app declaration (rule tests): no file is read except the manifest.
+ *
+ * @param {{ runtimeRoot: string, declaration: object, repoRoot: string, side: string }} input - Manifest root, hfs.json object, the linted side folder, its side.
+ * @returns {object} The frozen view.
+ */
+export declare const declaredHfsView: ({ runtimeRoot, declaration, repoRoot, side }: {
+    runtimeRoot: string;
+    declaration: Parsed;
+    repoRoot: string;
+    side: string;
+}) => HfsView;