@starci/hfs 5.3.0 → 5.5.0

package/sync/ci-commands.mjs

@@ -31,7 +31,7 @@ function codecovSteps(lcovReport, codecov) {
     ].join('\n');
 }
 /** Sonar is required: on every full run it consumes the test coverage and lint artifacts, and a missing token fails the job with a clear refusal. */
-function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
+function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout, scopes) {
     if (!sonar)
         return '';
     const condition = SONAR_CONDITION;
@@ -64,7 +64,7 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
         '          pattern: sonar-lint-*',
         '          path: reports',
         '          merge-multiple: true',
-        ...sonarMergeSteps(condition),
+        ...sonarMergeSteps(condition, scopes),
         '      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1',
         `        if: ${condition}`,
         '      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1',
@@ -137,15 +137,15 @@ function frontendBuild(source, app) {
     ].filter(Boolean).join('\n')).join('\n');
     return { env: singleEnv, steps };
 }
-/** The per-side lint reports (one artifact per lint matrix side) join into the one reports/lint.sonar.json the Sonar import reads, even when one side wrote none. The local release gate writes the same file with mergeSonarReports (release/lint-report.mjs): keep both identical. */
-function sonarMergeSteps(condition) {
+/** The per-scope lint reports (one artifact per lint matrix scope) join into the one reports/lint.sonar.json the Sonar import reads, even when one scope wrote none. The local release gate writes the same file with mergeSonarReports (release/lint-report.mjs): keep both identical. */
+function sonarMergeSteps(condition, scopes) {
     return [
         '      - name: merge Sonar lint reports',
         `        if: ${condition}`,
         '        run: |',
         "          node --input-type=module <<'NODE'",
         "          import fs from 'node:fs';",
-        "          const files = ['reports/lint.be.sonar.json', 'reports/lint.fe.sonar.json'];",
+        `          const files = [${scopes.map((scope) => `'reports/lint.${scope}.sonar.json'`).join(', ')}];`,
         "          const reports = files.filter(file => fs.existsSync(file)).map(file => JSON.parse(fs.readFileSync(file, 'utf8')));",
         '          const rules = [...new Map(reports.flatMap(report => report.rules).map(rule => [rule.id, rule])).values()];',
         '          const issues = reports.flatMap(report => report.issues);',
@@ -179,7 +179,7 @@ function ciJobSettings(declaration, source) {
     };
 }
 /** An omitted quality declaration preserves hosted Sonar, required OIDC Codecov, and the high production dependency audit. */
-export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info', quality = undefined, { nodeMajor = '22', app, packages = false } = {}) {
+export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info', quality = undefined, { nodeMajor = '22', app, packages = false, rootPackages = false } = {}) {
     const configuredSonar = quality === undefined ? { token: 'SONAR_TOKEN', hostVar: 'SONAR_HOST_URL' } : quality.sonar;
     const sonar = configuredSonar?.wiring === 'not-used' || configuredSonar?.mode === 'disabled' ? null : configuredSonar;
     const codecov = quality?.codecov ?? { enabled: true, auth: 'oidc' };
@@ -188,8 +188,11 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
     const build = frontendBuild(source, app);
     const settings = ciJobSettings(buildDeclaration(source), source);
     const side = '${{ matrix.side }}';
+    // The lint matrix: one job per side, and one for the root packages of an app that has them (their scope runs whatever became of the sides').
+    const scopes = ['be', 'fe', ...(rootPackages ? ['packages'] : [])];
     return {
         ...settings,
+        lintSides: `[${scopes.join(', ')}]`,
         lcovShardsDir: lcovReport.split('/').slice(0, -1).concat('shards').join('/'),
         // The istanbul JSON a shard writes beside the lcov (STARCI_COVERAGE_SHARD=1): what the coverage job merges.
         shardCoverageReport: lcovReport.split('/').slice(0, -1).concat('coverage-final.json').join('/'),
@@ -224,7 +227,7 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
         codecovSteps: codecovSteps(lcovReport, codecov),
         verdictSonarNeed: sonar ? ', sonar' : '',
         verdictSonarCheck: sonar ? `\n          if [[ "$FULL" == true && "$CHECKS" == true ]]; then expect sonar success; else expect sonar idle; fi` : '',
-        sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
+        sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar, scopes),
         lcovArtifact,
     };
 }

package/sync/compile-guard.d.mts

@@ -0,0 +1,36 @@
+/** The TypeScript compiler API of the app's own install, typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** The refusal code of a held group. */
+export declare const GROUP_HELD = "HFS_SYNC_GROUP_HELD";
+/** The pseudo-group of the retired files a sync deletes. */
+export declare const RETIRED_GROUP = "retired";
+/** One write the guard judges: an app-relative path, its managed group, and its new text (null: the file is deleted). */
+export interface GuardedWrite {
+    path: string;
+    group: string;
+    text: string | null;
+}
+/** A group sync does not write, with its files and the errors its writes would add. */
+export interface HeldGroup {
+    group: string;
+    files: string[];
+    errors: string[];
+}
+/** What the guard answers: the held groups, and the sides it could not compile. */
+export interface GuardVerdict {
+    held: HeldGroup[];
+    unchecked: string[];
+}
+/** Whether `file` (app-relative) is TypeScript source a side compiles. */
+export declare const isGuardedSource: (file: string) => boolean;
+/** The tsconfig that compiles an app-relative source: `be/tsconfig.json`, or the front-end app's or package's own; null when there is none. */
+export declare function projectOf(root: string, file: string): string | null;
+/**
+ * The groups `starci app sync --execute` holds back at `root`: every write of a TypeScript source is compiled, per side, with the side's own
+ * TypeScript (`loadTs`, the app's install by default); a side with no tsconfig compiles nothing, a side whose TypeScript is not installed is
+ * named in `unchecked`.
+ */
+export declare function guardWrites(root: string, writes: readonly GuardedWrite[], loadTs?: (dir: string) => Ts | null): GuardVerdict;
+/** The lines sync prints for a held group: what is held and why, the first errors, and what to do. */
+export declare function heldLines(group: HeldGroup): string[];
+export {};

package/sync/compile-guard.mjs

@@ -0,0 +1,189 @@
+// compile-guard.mjs - HFS_SYNC_GROUP_HELD: `starci app sync --execute` never writes a render that leaves the app uncompilable. Before it writes
+// a managed TypeScript source (or deletes a retired one), the side's own TypeScript compiles the app with the writes laid over the disk and
+// compares the diagnostics of every file they touch, and of every file that imports one, with the same files on disk. A managed group whose
+// writes add an error (a template that reads a name the app does not provide yet, or drops one the app still imports) is held whole: none
+// of its files is written, the rest of the render is, and the sync names the group, its files and the errors, so the app provides what the
+// render reads and runs sync again. A side whose TypeScript is not installed cannot be compiled; its writes go through and say so.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+/** The refusal code of a held group. */
+export const GROUP_HELD = 'HFS_SYNC_GROUP_HELD';
+/** The pseudo-group of the retired files a sync deletes. */
+export const RETIRED_GROUP = 'retired';
+/** How many errors a held group prints. */
+const SHOWN_ERRORS = 20;
+const SOURCE = /\.tsx?$/;
+/** Whether `file` (app-relative) is TypeScript source a side compiles. */
+export const isGuardedSource = (file) => SOURCE.test(file) && !file.endsWith('.d.ts') && (file.startsWith('be/') || file.startsWith('fe/'));
+/** The tsconfig that compiles an app-relative source: `be/tsconfig.json`, or the front-end app's or package's own; null when there is none. */
+export function projectOf(root, file) {
+    const parts = file.split('/');
+    const project = parts[0] === 'be' ? 'be/tsconfig.json' : parts.length > 3 ? `fe/${parts[1]}/${parts[2]}/tsconfig.json` : null;
+    return project !== null && fs.existsSync(path.join(root, project)) ? project : null;
+}
+/** One side's compilation: its compiler, options and root files, the overlay of writes keyed the way the host compares file names. */
+class Side {
+    #ts;
+    #root;
+    #options;
+    #rootNames;
+    #baseline = new Map();
+    #program;
+    constructor(ts, root, project) {
+        this.#ts = ts;
+        this.#root = root;
+        const file = path.join(root, project);
+        const read = ts.readConfigFile(file, ts.sys.readFile);
+        const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(file), { noEmit: true }, file);
+        this.#options = { ...parsed.options, noEmit: true };
+        this.#rootNames = parsed.fileNames;
+    }
+    /** The name the host compares: absolute, forward slashes, lower case where the file system ignores case. */
+    key(file) {
+        const absolute = path.resolve(this.#root, file).replaceAll('\\', '/');
+        return this.#ts.sys.useCaseSensitiveFileNames ? absolute : absolute.toLowerCase();
+    }
+    #host(overlay) {
+        const host = this.#ts.createCompilerHost(this.#options, true);
+        const { readFile, fileExists, getSourceFile } = host;
+        host.readFile = (name) => (overlay.has(this.key(name)) ? overlay.get(this.key(name)) ?? undefined : readFile.call(host, name));
+        host.fileExists = (name) => (overlay.has(this.key(name)) ? overlay.get(this.key(name)) !== null : fileExists.call(host, name));
+        host.getSourceFile = (name, language, onError, create) => {
+            if (!overlay.has(this.key(name)))
+                return getSourceFile.call(host, name, language, onError, create);
+            const text = overlay.get(this.key(name));
+            return text === null || text === undefined ? undefined : this.#ts.createSourceFile(name, text, language, true);
+        };
+        return host;
+    }
+    #programOf(overlay, added) {
+        const rootNames = [...this.#rootNames.filter((name) => overlay.get(this.key(name)) !== null), ...added];
+        return this.#ts.createProgram({ rootNames, options: this.#options, host: this.#host(overlay), ...(this.#program === undefined ? {} : { oldProgram: this.#program }) });
+    }
+    /** The files of the program that import one of `targets` (keys), each with the targets it imports. */
+    importers(targets, overlay) {
+        const host = this.#host(overlay);
+        const cache = this.#ts.createModuleResolutionCache(this.#root, (name) => this.key(name), this.#options);
+        const found = new Map();
+        for (const name of this.#rootNames) {
+            const text = host.readFile(name);
+            if (text === undefined)
+                continue;
+            for (const imported of this.#ts.preProcessFile(text, true, true).importedFiles) {
+                const resolved = this.#ts.resolveModuleName(imported.fileName, name, this.#options, host, cache).resolvedModule?.resolvedFileName;
+                if (resolved === undefined || !targets.has(this.key(resolved)))
+                    continue;
+                const into = found.get(this.key(name)) ?? new Set();
+                into.add(this.key(resolved));
+                found.set(this.key(name), into);
+            }
+        }
+        return found;
+    }
+    /** The errors of `files` (keys) as `path TScode message`, each file once, in the program with `overlay` laid over the disk. */
+    errors(files, overlay, added) {
+        const program = this.#programOf(overlay, added);
+        if (overlay.size === 0)
+            this.#program = program;
+        const byKey = new Map(program.getSourceFiles().map((source) => [this.key(source.fileName), source]));
+        const answer = new Map();
+        for (const file of files) {
+            const source = byKey.get(file);
+            const relative = path.relative(this.#root, source?.fileName ?? file).replaceAll('\\', '/');
+            const found = source === undefined ? [] : [...program.getSyntacticDiagnostics(source), ...program.getSemanticDiagnostics(source)];
+            answer.set(file, found.map((diagnostic) => `${relative}${source === undefined || diagnostic.start === undefined ? '' : `:${String(source.getLineAndCharacterOfPosition(diagnostic.start).line + 1)}`} TS${String(diagnostic.code)} ${this.#ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')}`));
+        }
+        return answer;
+    }
+    /** The errors of `files` on disk, computed once per file. */
+    baseline(files) {
+        const missing = files.filter((file) => !this.#baseline.has(file));
+        if (missing.length > 0)
+            for (const [file, found] of this.errors(missing, new Map(), []))
+                this.#baseline.set(file, found);
+        return new Map(files.map((file) => [file, this.#baseline.get(file) ?? []]));
+    }
+}
+/** An error without its line, so a line moved by the write is the same error. */
+const unplaced = (error) => error.replace(/^([^ ]*?):\d+ /, '$1 ');
+/** The errors of `after` that `before` does not hold, counted as a multiset of unplaced errors. */
+function added(before, after) {
+    const left = new Map();
+    for (const error of before)
+        left.set(unplaced(error), (left.get(unplaced(error)) ?? 0) + 1);
+    return after.filter((error) => {
+        const count = left.get(unplaced(error)) ?? 0;
+        left.set(unplaced(error), count - 1);
+        return count <= 0;
+    });
+}
+/** The held groups of one side: compile with every write of the groups still in play, hold the groups that add an error, again until none does. */
+function judgeSide(side, writes) {
+    const held = [];
+    let open = [...writes];
+    while (open.length > 0) {
+        const overlay = new Map(open.map((write) => [side.key(write.path), write.text]));
+        const groupOf = new Map(open.map((write) => [side.key(write.path), write.group]));
+        // An importer is found on the disk with the new files added, so the importer of a file the writes delete is found too.
+        const importers = side.importers(new Set(overlay.keys()), new Map([...overlay].filter(([, text]) => text !== null)));
+        const files = [...new Set([...[...overlay.keys()].filter((file) => overlay.get(file) !== null), ...importers.keys()])];
+        const before = side.baseline(files);
+        const after = side.errors(files, overlay, open.filter((write) => write.text !== null).map((write) => path.resolve(write.path)));
+        const errors = new Map();
+        for (const file of files) {
+            const fresh = added(before.get(file) ?? [], after.get(file) ?? []);
+            if (fresh.length === 0)
+                continue;
+            const groups = groupOf.has(file) ? [groupOf.get(file)] : [...(importers.get(file) ?? [])].map((target) => groupOf.get(target));
+            for (const group of groups)
+                errors.set(group, [...(errors.get(group) ?? []), ...fresh]);
+        }
+        if (errors.size === 0)
+            break;
+        for (const [group, found] of errors)
+            held.push({ group, files: open.filter((write) => write.group === group).map((write) => write.path), errors: [...new Set(found)] });
+        open = open.filter((write) => !errors.has(write.group));
+    }
+    return held;
+}
+/**
+ * The groups `starci app sync --execute` holds back at `root`: every write of a TypeScript source is compiled, per side, with the side's own
+ * TypeScript (`loadTs`, the app's install by default); a side with no tsconfig compiles nothing, a side whose TypeScript is not installed is
+ * named in `unchecked`.
+ */
+export function guardWrites(root, writes, loadTs = (dir) => loadTypescript(dir, root)) {
+    const verdict = { held: [], unchecked: [] };
+    const bySide = new Map();
+    for (const write of writes.filter((candidate) => isGuardedSource(candidate.path))) {
+        const project = projectOf(root, write.path);
+        if (project !== null)
+            bySide.set(project, [...(bySide.get(project) ?? []), { ...write, path: path.join(root, write.path) }]);
+    }
+    for (const [project, sideWrites] of bySide) {
+        const ts = loadTs(path.join(root, path.dirname(project)));
+        if (ts === null) {
+            verdict.unchecked.push(project);
+            continue;
+        }
+        for (const group of judgeSide(new Side(ts, root, project), sideWrites)) {
+            const relative = group.files.map((file) => path.relative(root, file).replaceAll('\\', '/'));
+            const known = verdict.held.find((entry) => entry.group === group.group);
+            if (known === undefined)
+                verdict.held.push({ ...group, files: relative });
+            else
+                verdict.held.splice(verdict.held.indexOf(known), 1, { group: group.group, files: [...known.files, ...relative], errors: [...known.errors, ...group.errors] });
+        }
+    }
+    return verdict;
+}
+/** The lines sync prints for a held group: what is held and why, the first errors, and what to do. */
+export function heldLines(group) {
+    const more = group.errors.length > SHOWN_ERRORS ? [`  ... ${String(group.errors.length - SHOWN_ERRORS)} more`] : [];
+    return [
+        `${GROUP_HELD} ${group.group}: ${String(group.files.length)} files not written, the render adds ${String(group.errors.length)} type errors to the app (${group.files.join(', ')})`,
+        ...group.errors.slice(0, SHOWN_ERRORS).map((error) => `  ${error}`),
+        ...more,
+        `  make the app provide what the render reads (each error names it), then run "npx --no-install starci app sync --execute" again`,
+    ];
+}

package/sync/index.d.mts

@@ -1,6 +1,8 @@
+import { type PackagesCoverage } from '../runtime/scripts/hfs/coverage-scope.mjs';
 import { type RepoView } from '../runtime/scripts/hfs/slots.mjs';
 import type { AppRepo } from '../runtime/scripts/hfs/slot-app-view.mjs';
 import type { Slot, SlotManifest } from '../runtime/scripts/hfs/manifest-shape.mjs';
+import { guardWrites, type GuardedWrite } from './compile-guard.mjs';
 import type { ImageApp } from './stack-images.mjs';
 export declare const TEMPLATES_DIR: string;
 /** The scopes a target is rendered for: the app root, then each side. */
@@ -22,6 +24,7 @@ export interface Target {
     template: string;
     mode: string;
     slot?: string;
+    group?: string;
     markdown?: boolean;
 }
 /** The markers around a managed block. */
@@ -39,6 +42,8 @@ export interface RenderedTarget {
     scripts?: Record<string, unknown>;
     markdown?: boolean | undefined;
     markers?: Markers;
+    /** The managed group of a slot's file (`managedBy`), which sync writes or holds whole (compile-guard.mjs). */
+    group?: string;
 }
 /** What comparing a rendered target with the disk answers. */
 export interface TargetCheck {
@@ -64,6 +69,7 @@ export interface AppSourceFacts {
     read: (file: string) => string;
     workPresent: boolean;
     hasImage: (file: string) => boolean;
+    hasContracts: boolean;
     modules?: readonly string[];
     otherPackages?: readonly string[];
     stack: any;
@@ -142,6 +148,8 @@ export declare function sonarScope(presets: Presets | null | undefined): {
 };
 /** The managed ESLint config at the app root that lints the root workspace packages. */
 export declare const PACKAGES_LINT_FILE = "eslint.config.mjs";
+/** The app-relative folders of the root packages whose logic the back end's unit run measures: every module package and every other package, never the registry. */
+export declare const rootPackageFolders: (source: Partial<Pick<AppSourceFacts, "modules" | "otherPackages">> | undefined) => string[];
 export declare function appSource(root: string, { parseYaml, notices }?: {
     parseYaml?: ParseYaml | undefined;
     notices?: string[] | undefined;
@@ -184,12 +192,19 @@ export declare function imageApps(app: ResolvedApp, source: Partial<Pick<AppSour
 /**
  * The Dockerfile of every declared app, [{ path, content }] (app-relative): written once by starci app scaffold from templates/<side>/image/<kind>
  * and then the app's own, judged by the docker rules (R187-R191). A Next image copies the fe packages only when the fe side opts into
- * them and the be contracts only when the fe side reads them, so each COPY names a folder the app has.
+ * them and the be contracts only when the fe side reads them and the back end holds them (`source.hasContracts`: a back end that emits no
+ * contract has no be/contracts/, and a COPY of a missing folder fails the image build), so each COPY names a folder the app has.
  */
-export declare function imageFiles(app: ResolvedApp, source?: Partial<Pick<AppSourceFacts, 'hasImage'>>): {
+export declare function imageFiles(app: ResolvedApp, source?: Partial<Pick<AppSourceFacts, 'hasImage' | 'hasContracts'>>): {
     path: string;
     content: string;
 }[];
+/** Every value a template of `scope` can name, derived from hfs.json and the presets. */
+/**
+ * The `packages` option of the managed be/jest.config.js (`starciJestConfig`), laid out as prettier lays it out (width 120, indent 4): the root packages whose
+ * specs the unit run holds, with the files measured in them; an app without one has no such option.
+ */
+export declare function jestPackagesSource(packages: PackagesCoverage): string;
 export declare function variables(app: ResolvedApp, scope: string, presets: Presets | null | undefined, sonarKey: string | null | undefined, manifest?: SlotManifest, source?: Pick<AppSourceFacts, 'files' | 'read'> & Partial<AppSourceFacts>): Record<string, string>;
 /**
  * The rendered targets of an app declaration. Without source facts the app counts the back-end source files its own targets
@@ -229,9 +244,13 @@ export declare function renderRepo(root: string, { presets, parseYaml, notices,
 export declare function retiredFiles(root: string, hfs: {
     edition?: string;
 } | null | undefined): string[];
-export declare function runSync(argv: string[], { cwd, out, presets, parseYaml }?: {
+/** The writes of `targets` and the deletions of `retired` the compile guard judges: every file sync would change, with its managed group. */
+export declare function guardedWrites(root: string, targets: readonly RenderedTarget[], retired: readonly string[]): GuardedWrite[];
+export declare function runSync(argv: string[], { cwd, out, presets, parseYaml, loadTs }?: {
     cwd?: string;
     out?: (line: string) => unknown;
     presets?: Presets | undefined;
     parseYaml?: ParseYaml | undefined;
+    /** The TypeScript of a side folder the compile guard compiles with; the app's own install by default. */
+    loadTs?: Parameters<typeof guardWrites>[2];
 }): Promise<number>;