@starci/hfs 5.0.7 → 5.1.0

package/lint/run.mjs

@@ -6,107 +6,31 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-// starci app lint - the ONE lint entry and the ONE report of a StarCi app.
+// The linters of `starci app check --gate lint`: ESLint once per side and stylelint over the fe stylesheets, through the app's own install.
 //
-//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--full] [--json] [--out <file>]
-//
-// It runs at the app root (the folder of hfs.json), over the app (or over the app-relative files named by --changed):
-//   1. ESLint once per side, from the side folder, through the app's own install and that side's eslint.config.mjs (be/ the be canon,
-//      fe/ the fe canon: the per-file rules and the project-graph rules of the architecture machine, findings on the line of the
-//      offending TypeScript file); each side lints only its own files, so the be rules never see fe/ and the fe rules never see be/;
-//   2. `starci app check` for what has no TypeScript file to sit on (the tree, managed files, pins, CI, contracts, docs, .starciwork), root and sides;
-//   3. stylelint over the fe side's stylesheets (sync STYLE_GLOB), from fe/ with its stylelint.config.mjs.
-// Their findings become one list of one shape (`starci/lint@1`), every path app-relative. `--json` prints that report on stdout;
-// `--out <file>` writes the same findings as THE Sonar Generic Issue Import file (engine ids starci-hfs, eslint, stylelint in one
-// document); the exit code is the land-gate input: 0 no finding, 1 at least one, 2 a tool could not run (never a pass).
-// --changed restricts ESLint and stylelint to the listed files and keeps of the app findings only those on a listed file or on no file.
-// --workspace scopes the same lint to one npm workspace of the fe side (fe/apps/<app> or fe/packages/<pkg>, app-relative): ESLint and
-// stylelint over that folder only, and of the app findings only those inside it. It is the `lint` script of every fe workspace (the
-// turbo `lint` task); the root `npm run lint` stays the whole app. There is no second linter: a workspace lint is this lint, scoped.
-// The result cache (contexts/project/check-cache.md): when the caller hands lintRepository a cache session, ESLint and stylelint judge only what
-// the records of `.starcistacks/cache/lint/<side>/` cannot vouch for (cache/lint-family.mjs) - the same records and fingerprint `app check --lint`
-// uses, so the two verbs never hold two answers. `--side` reads and writes its side's records, `--workspace` reads and writes none, `--changed`
-// and `--fix` bypass the cache, and `--full` judges everything again and rewrites the records.
+//   1. ESLint runs from the side folder with that side's eslint.config.mjs (be/ the be canon, fe/ the fe canon: the per-file rules and the
+//      project-graph rules of the architecture machine, findings on the line of the offending TypeScript file); each side lints only its own
+//      files, so the be rules never see fe/ and the fe rules never see be/;
+//   2. stylelint judges the fe side's stylesheets (sync STYLE_GLOB) from fe/ with its stylelint.config.mjs.
+// `cachedLinters` is the one entry of `app check`: per side it judges only what the records of `.starcistacks/cache/lint/<side>/` cannot
+// vouch for (cache/lint-family.mjs, contexts/project/check-cache.md), and `eslintRepository` is the launcher it and the cacheless run share.
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { makeTempDir } from '../runtime/scripts/api/fs/make-temp-dir.mjs';
 import { completedNode, isHostHeld, isNodeExecutionRefusal, runHeavyNode } from '../runtime/scripts/api/node/run-node.mjs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { linterReport, mergeReports, sonarReport, sourceRootsOf } from '../report/sonar.mjs';
 import { SIDES, appRelativeMessages, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
-import { isSide } from '../runtime/scripts/hfs/slot-manifest-shape.mjs';
-import { chunkByChars, mapBounded, mergeRuns } from './chunk.mjs';
 import { STYLE_GLOB } from '../sync/index.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
 import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
-import { gateVerdict } from '../runtime/scripts/hfs/gate-threshold.mjs';
 import { mergeBase } from '../runtime/scripts/api/git/merge-base.mjs';
 import { lintFamilyReport, lintSide, loadAppTypeScript } from '../cache/lint-family.mjs';
-// --side judges only that side; root HFS findings belong to be, its Sonar report stays on that side.
-export const LINT_SCHEMA = 'starci/lint@1';
 /** The side whose stylesheets stylelint judges. */
 const STYLE_SIDE = 'fe';
 const CODE_PREFIX = /^\[([A-Z][A-Z0-9_]+)\] /;
 const posix = (file) => String(file).replace(/\\/g, '/').replace(/^\.\//, '');
-/** An npm workspace of the fe side, app-relative: one folder below fe/apps or fe/packages (the root package.json workspaces). */
-const WORKSPACE = /^fe\/(?:apps|packages)\/[a-z0-9][a-z0-9-]*$/;
-/** The app-relative workspace of `opts.workspace` (already app-relative), or a refusal when it is not one folder of fe/apps or fe/packages. */
-export function workspaceOf(workspace) {
-    const rel = posix(workspace).replace(/\/+$/, '');
-    if (!WORKSPACE.test(rel))
-        throw new Error(`--workspace ${workspace} is not an fe workspace (fe/apps/<app> or fe/packages/<pkg>, from the app root)`);
-    return rel;
-}
-/** Side scopes partition the full lint; Sonar reports share that scope and a frontend workspace cannot belong to be. */
-function validateSide(opts) {
-    if (opts.side === undefined)
-        return;
-    if (!isSide(opts.side))
-        throw new Error('LINT_SIDE_INVALID: --side is be or fe');
-    if (opts.side === 'be' && opts.workspace !== undefined)
-        throw new Error('LINT_SIDE_WORKSPACE_CONFLICT: --side be cannot judge a frontend workspace');
-}
-/** Side findings stay with their side; findings outside both sides belong to the backend lint. */
-function findingOnSide(finding, side) {
-    if (side === undefined)
-        return true;
-    const file = posix(finding.path ?? '');
-    const owner = SIDES.find((candidate) => file === candidate || file.startsWith(`${candidate}/`));
-    return (owner ?? 'be') === side;
-}
-/** The flags of `starci app lint`; `--changed` takes every argument up to the next flag, and a repeated `--changed` adds to the list (the
- *  catalog's list flag, `--changed a --changed b`, as the CLI dispatcher passes it through). */
-export function parseLintArgs(argv) {
-    const opts = { changed: null, fix: false, format: 'text', out: undefined, workspace: undefined };
-    for (let i = 0; i < argv.length; i += 1) {
-        const arg = argv[i];
-        if (arg === '--changed') {
-            opts.changed ??= [];
-            while (i + 1 < argv.length && !argv[i + 1].startsWith('--'))
-                opts.changed.push(posix(argv[++i]));
-        }
-        else if (arg === '--fix')
-            opts.fix = true;
-        else if (arg === '--full')
-            opts.full = true;
-        else if (arg === '--json')
-            opts.format = 'json';
-        else if (['--out', '--workspace', '--side'].includes(arg)) {
-            if (arg === '--side' && (argv[i + 1] === undefined || argv[i + 1].startsWith('--')))
-                throw new Error('LINT_SIDE_INVALID: --side needs be or fe');
-            if (argv[i + 1] === undefined)
-                throw new Error(`${arg} needs a value`);
-            opts[arg.slice(2)] = argv[++i];
-        }
-        else
-            throw new Error(`unknown argument ${arg}`);
-    }
-    if (opts.workspace !== undefined && opts.changed !== null)
-        throw new Error('--workspace and --changed do not combine: a workspace lint judges the whole workspace');
-    validateSide(opts);
-    return opts;
-}
 /** The typed ESLint run reads nothing above the app root: its TypeScript `sys` is bound by this preload (3.3, bound-sys.cjs). */
 const BOUND_ENV = 'STARCI_LINT_BOUND';
 const linterBoundArgs = () => ['--require', fileURLToPath(new URL('./bound-sys.cjs', import.meta.url))];
@@ -119,8 +43,25 @@ export function eslintHeapArgs(env = process.env) {
     const mb = Number(env[ESLINT_HEAP_ENV]);
     return Number.isInteger(mb) && mb > 0 ? [`--max-old-space-size=${mb}`] : [];
 }
+/** The ESLint list runner (eslint-list.cts, built beside this file). */
+const LIST_RUNNER = fileURLToPath(new URL('./eslint-list.cjs', import.meta.url));
+/** The snapshots an ESLint child wrote, by canon name; undefined when it wrote none or a file that is not a snapshot list (the cache then builds the graph itself). */
+function readGraphSnapshots(file) {
+    try {
+        const written = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const snapshots = written?.snapshots;
+        if (snapshots === null || typeof snapshots !== 'object' || Array.isArray(snapshots))
+            return undefined;
+        const sound = Object.values(snapshots).every((snapshot) => snapshot !== null && typeof snapshot === 'object' && snapshot.byFile !== null && typeof snapshot.byFile === 'object' && !Array.isArray(snapshot.byFile)
+            && Object.values(snapshot.byFile).every((findings) => Array.isArray(findings)));
+        return sound ? snapshots : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** A linter's json results through the app's own install, run from `cwd` (a side folder): `{ results }` or `{ error }`. The child runs while the caller goes on. */
-export async function runLinter({ cwd, pkg, bin, args, bound = null }, execute) {
+export async function runLinter({ cwd, pkg, bin, args, bound = null, list, files, graph }, execute) {
     let entry;
     try {
         const manifest = createRequire(path.join(cwd, 'package.json')).resolve(`${pkg}/package.json`);
@@ -131,7 +72,27 @@ export async function runLinter({ cwd, pkg, bin, args, bound = null }, execute)
         return { error: `${pkg} is not installed for ${cwd}` };
     }
     const heap = pkg === 'eslint' ? eslintHeapArgs() : [];
-    const run = completedNode(await runHeavyNode(execute, { kind: 'eslint', label: `app lint ${pkg} ${path.basename(cwd)}`, args: [...heap, ...(bound ? linterBoundArgs() : []), entry, ...args], cwd, maxBuffer: 64 * 1024 * 1024, ...(bound ? { env: { ...process.env, [BOUND_ENV]: bound } } : {}) }), pkg);
+    // A named list, or a run that hands its project graph out, goes through the list runner: the job is a file it reads (ESLint lints all of it in one
+    // process, no command line holds a path), the whole side is the list `.`, and the graph snapshots come back in a file beside the job.
+    const listed = pkg === 'eslint' && (list !== undefined || graph !== undefined) ? makeTempDir('starci-eslint-') : null;
+    let childArgs = [entry, ...args];
+    const snapshotFile = listed === null || graph === undefined ? null : path.join(listed, 'graph.json');
+    if (listed !== null) {
+        const job = path.join(listed, 'job.json');
+        fs.writeFileSync(job, JSON.stringify({ files: list ?? ['.'], fix: args.includes('--fix'), ...(snapshotFile === null || graph === undefined ? {} : { graph: { out: snapshotFile, canons: graph } }) }));
+        childArgs = [LIST_RUNNER, job];
+    }
+    const count = list?.length ?? files;
+    let run;
+    let handed;
+    try {
+        run = completedNode(await runHeavyNode(execute, { kind: 'eslint', label: `app check ${pkg} ${path.basename(cwd)}`, args: [...heap, ...(bound ? linterBoundArgs() : []), ...childArgs], cwd, maxBuffer: 64 * 1024 * 1024, ...(count === undefined || pkg !== 'eslint' ? {} : { files: count }), ...(bound ? { env: { ...process.env, [BOUND_ENV]: bound } } : {}) }), pkg);
+        handed = snapshotFile === null ? undefined : readGraphSnapshots(snapshotFile);
+    }
+    finally {
+        if (listed !== null)
+            fs.rmSync(listed, { recursive: true, force: true });
+    }
     // ESLint prints its report on stdout; stylelint uses stderr. JSON does not prove a completed child: only exits 0/1
     // without a spawn error or signal are measurable, and exit 1 must carry findings.
     let results;
@@ -145,17 +106,12 @@ export async function runLinter({ cwd, pkg, bin, args, bound = null }, execute)
         return { error: `${pkg} produced a report that is not a result list` };
     const completed = !run.error && !run.signal && [0, 1].includes(run.status)
         && (run.status === 0 || results.some((result) => result?.messages?.length || result?.warnings?.length));
-    return { results, ...(completed ? {} : { error: `${pkg} could not complete in ${path.basename(cwd)}/ (exit ${run.status}, signal ${run.signal ?? 'none'}): ${String(run.error?.message || run.stderr || run.stdout || '').trim().split('\n')[0]}` }) };
+    return { results, ...(handed === undefined || !completed ? {} : { graph: handed }), ...(completed ? {} : { error: `${pkg} could not complete in ${path.basename(cwd)}/ (exit ${run.status}, signal ${run.signal ?? 'none'}): ${String(run.error?.message || run.stderr || run.stdout || '').trim().split('\n')[0]}` }) };
 }
 const eslintFindings = (results, appRoot) => results.flatMap((result) => (result.messages ?? []).map((message) => ({
     engine: 'eslint', rule: message.ruleId ?? 'eslint-error', code: CODE_PREFIX.exec(message.message ?? '')?.[1] ?? null, severity: message.severity === 1 ? 'warning' : 'error',
     path: posix(path.relative(appRoot, result.filePath)), line: message.line ?? null, column: message.column ?? null, message: message.message,
 })));
-const stylelintFindings = (results, appRoot) => results.flatMap((result) => (result.warnings ?? []).map((warning) => ({
-    engine: 'stylelint', rule: warning.rule || 'stylelint-error', code: null, severity: 'error',
-    path: posix(path.relative(appRoot, result.source)), line: warning.line ?? null, column: warning.column ?? null, message: warning.text,
-})));
-const byLocation = (a, b) => `${a.path ?? ''}:${String(a.line ?? 0).padStart(7, '0')}:${a.rule}`.localeCompare(`${b.path ?? ''}:${String(b.line ?? 0).padStart(7, '0')}:${b.rule}`);
 /** The files of `changed` (app-relative) below `side`/, relative to the side folder. */
 const onSide = (changed, side) => changed.filter((file) => file.startsWith(`${side}/`)).map((file) => file.slice(side.length + 1));
 const fileKey = (file) => process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file);
@@ -276,7 +232,7 @@ export async function installedLintConfig({ repoRoot, cwd, side }) {
     return [...config, ...familyConfig];
 }
 /** Read both installed canons' source selectors, then enumerate that scope; unavailable selectors cannot prove coverage. */
-async function sourceFiles({ repoRoot, cwd, side, scope: folderScope }) {
+async function sourceFiles({ repoRoot, cwd, side }) {
     const config = await installedLintConfig({ repoRoot, cwd, side });
     const scope = canonScope(config);
     const files = [];
@@ -294,11 +250,11 @@ async function sourceFiles({ repoRoot, cwd, side, scope: folderScope }) {
                 files.push(file);
         }
     };
-    visit(folderScope ?? '');
+    visit('');
     return files.sort(byCodeUnit);
 }
 /** Every requested source needs an explicit, well-formed result; suppressed findings and foreign paths cannot witness a completed lint. */
-function checkedEslintResults({ results, expected, cwd, scope, changed }) {
+function checkedEslintResults({ results, expected, cwd, changed }) {
     const required = new Set(expected.map((file) => fileKey(path.join(cwd, file))));
     const seen = new Set(), valid = [], errors = [];
     for (const result of results) {
@@ -309,7 +265,7 @@ function checkedEslintResults({ results, expected, cwd, scope, changed }) {
             continue;
         }
         const key = fileKey(result.filePath);
-        if (!inside(cwd, result.filePath) || (scope && !inside(path.join(cwd, scope), result.filePath)) || (changed && !required.has(key))) {
+        if (!inside(cwd, result.filePath) || (changed && !required.has(key))) {
             errors.push(`eslint produced a result outside the requested scope: ${result.filePath}`);
             continue;
         }
@@ -325,22 +281,26 @@ function checkedEslintResults({ results, expected, cwd, scope, changed }) {
         errors.push(`eslint produced no result for requested source files: ${missing.join(', ')}`);
     return { results: valid, errors };
 }
-const ESLINT_ARGV_BUDGET = 24_000;
-const ESLINT_CONCURRENCY = 3;
 /** A launch that threw instead of returning a record is a tool error of the run (exit 2), not a crash of the CLI. */
 const spawnFailure = (error) => {
     if (isNodeExecutionRefusal(error))
         throw error;
     return { error: `could not start eslint: ${String(error?.message ?? error)}` };
 };
+/** The installed canon of `side`, which publishes the project-graph rules, as the child imports it; undefined when it cannot be resolved (the cache then builds the graph itself). */
+function graphCanonsOf(repoRoot, cwd, side) {
+    const name = `@starci/eslint-canon-${side}`;
+    try {
+        return [{ name, entry: ownCanonEntry({ repoRoot, cwd }, name) }];
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Starts the ESLint child of every side that has work and returns one record per side: skipped, a scope error, or the running child. */
-async function launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe, run = runLinter }) {
+async function launchEslint({ app, repoRoot, opts, changed, existing, run = runLinter, scopes = {}, handOutGraph = false }) {
     const launches = [];
     for (const side of app ? SIDES.filter((candidate) => opts.side === undefined || opts.side === candidate) : []) {
-        if (workspace !== null && side !== STYLE_SIDE) {
-            launches.push({ side, skipped: `outside --workspace ${workspace}` });
-            continue;
-        }
         const sources = onSide(existing, side).filter((file) => /\.(?:[cm]?[jt]sx?)$/.test(file));
         if (changed !== null && !sources.length) {
             launches.push({ side, skipped: 'no changed source file' });
@@ -348,28 +308,32 @@ async function launchEslint({ app, repoRoot, opts, changed, existing, workspace,
         }
         const cwd = path.join(repoRoot, side);
         let expected;
+        // a caller that enumerated the side's scope already (the cache) hands it over: the canon config is loaded and the folders walked once per run
+        const known = scopes[side];
         try {
-            expected = changed ? sources : await sourceFiles({ repoRoot, cwd, side, scope: onFe });
+            expected = changed ? sources : known !== undefined ? [...known] : await sourceFiles({ repoRoot, cwd, side });
         }
         catch (error) {
             launches.push({ side, scopeError: `eslint source scope is unavailable in ${side}/: ${String(error?.message ?? error)}` });
             continue;
         }
         const head = ['--format', 'json', ...(opts.fix ? ['--fix'] : [])];
-        const launch = (files) => Promise.resolve().then(() => run({ cwd, pkg: 'eslint', bin: 'eslint', args: [...head, ...files], bound: repoRoot }));
-        // A diff of hundreds of files exceeds the Windows command line: the sources go in chunks and the reports are merged.
-        const chunks = changed ? chunkByChars(sources, ESLINT_ARGV_BUDGET) : [[onFe ?? '.']];
-        launches.push({ side, cwd, expected, run: chunks.length === 1 ? launch(chunks[0]).catch(spawnFailure) : mapBounded(chunks, launch, ESLINT_CONCURRENCY).then(mergeRuns) });
+        // the child that builds the canon's project graph for its rules hands the snapshot out when the caller keeps the graph findings (the cache)
+        const graph = handOutGraph ? graphCanonsOf(repoRoot, cwd, side) : undefined;
+        // The files of a diff go to ONE child through a file (a diff of hundreds of long paths outgrows the Windows command line, and each extra
+        // child would build the whole TypeScript program again); the whole side is a single directory argument.
+        const launch = Promise.resolve().then(() => run(changed ? { cwd, pkg: 'eslint', bin: 'eslint', args: head, list: sources, bound: repoRoot, ...(graph === undefined ? {} : { graph }) } : { cwd, pkg: 'eslint', bin: 'eslint', args: [...head, '.'], files: expected.length, bound: repoRoot, ...(graph === undefined ? {} : { graph }) }));
+        launches.push({ side, cwd, expected, run: launch.catch(spawnFailure) });
     }
     return launches;
 }
-/** Execute each side's installed ESLint config once; check and lint share scope, coverage and tool-failure judgment. */
-export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loadSlotManifest(), repoRoot), opts = {}, changed = null, existing = [], workspace = null, onFe = null, run }) {
-    const findings = [], errors = [], raw = [];
+/** Execute each side's installed ESLint config once, whole or over a named list; the cached and the cacheless run share scope, coverage and tool-failure judgment. */
+export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loadSlotManifest(), repoRoot), opts = {}, changed = null, existing = [], run, scopes, handOutGraph }) {
+    const findings = [], errors = [], raw = [], graphs = {};
     const engine = { sides: {} };
     if (!app.sides)
         throw new Error('ESLint runs at the app root, the folder of hfs.json');
-    const launches = await launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe, run });
+    const launches = await launchEslint({ app, repoRoot, opts, changed, existing, run, ...(scopes === undefined ? {} : { scopes }), ...(handOutGraph === true ? { handOutGraph } : {}) });
     const settled = await Promise.allSettled(launches.map(launch => launch.run ?? null));
     const rejected = settled.filter((run) => run.status === 'rejected');
     const failed = rejected.find(run => isHostHeld(run.reason)) ?? rejected[0];
@@ -391,7 +355,7 @@ export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loa
         if (linted.error)
             errors.push(linted.error);
         if (linted.results) {
-            const checked = checkedEslintResults({ results: linted.results, expected: launch.expected, cwd: launch.cwd, scope: onFe, changed: changed !== null });
+            const checked = checkedEslintResults({ results: linted.results, expected: launch.expected, cwd: launch.cwd, changed: changed !== null });
             errors.push(...checked.errors);
             linted.results = checked.results;
             const appRelative = appRelativeMessages(side, path.join(repoRoot, side));
@@ -402,8 +366,10 @@ export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loa
             findings.push(...eslintFindings(linted.results, repoRoot));
         }
         engine.sides[side] = { files: linted.results?.length ?? 0 };
+        if (linted.graph !== undefined)
+            graphs[side] = linted.graph;
     });
-    return { findings, errors, raw, engine };
+    return { findings, errors, raw, engine, graphs };
 }
 // ------------------------------------------------------------------------------------------------ the cached lint
 /** A `crossFileInputs` export that has the shape the cache reads, or null (an installed canon without it, or with a broken one, is linted whole). */
@@ -483,22 +449,18 @@ export function gitBaseToken(repoRoot) {
  * validation of a full run (eslintRepository), the rest take their records. The answer has the shape of eslintRepository's, plus the stylelint
  * results, so the lint report is built the same way from either.
  */
-export async function cachedLinters({ repoRoot, app, opts, workspace, onFe, run, cache }) {
+export async function cachedLinters({ repoRoot, app, side: only, run, session }) {
     const eslint = { findings: [], errors: [], raw: [], engine: { sides: {} } };
     const style = { results: [], errors: [], ran: false };
     const sides = [];
-    const decision = cache.session.decide('lint');
-    const full = opts.full === true ? '--full' : decision.mode === 'full' ? decision.reason : null;
+    const decision = session.decide('lint');
+    const full = decision.mode === 'full' ? decision.reason : null;
     const gitToken = gitBaseToken(repoRoot);
-    for (const side of SIDES.filter((candidate) => opts.side === undefined || opts.side === candidate)) {
-        if (workspace !== null && side !== STYLE_SIDE) {
-            eslint.engine.sides[side] = { files: 0, skipped: `outside --workspace ${workspace}` };
-            continue;
-        }
+    for (const side of SIDES.filter((candidate) => only === undefined || only === candidate)) {
         const cwd = path.join(repoRoot, side);
         let scope, canons;
         try {
-            scope = await sourceFiles({ repoRoot, cwd, side, scope: null });
+            scope = await sourceFiles({ repoRoot, cwd, side });
             canons = await canonDeclarations({ repoRoot, cwd, side });
         }
         catch (error) {
@@ -508,16 +470,15 @@ export async function cachedLinters({ repoRoot, app, opts, workspace, onFe, run,
         }
         const styled = side === STYLE_SIDE;
         const outcome = await lintSide({
-            session: cache.session, side, sideRoot: cwd, scope, stylesheets: styled ? stylesheetsOf(cwd) : [],
-            report: onFe === null ? null : (file) => file.startsWith(`${onFe}/`),
-            canons, styleCanon: styled ? await styleDeclaration({ repoRoot, cwd }) : null, typescript: () => loadAppTypeScript(cwd), extraKey: '', gitToken, full, write: workspace === null,
+            session, side, sideRoot: cwd, scope, stylesheets: styled ? stylesheetsOf(cwd) : [],
+            canons, styleCanon: styled ? await styleDeclaration({ repoRoot, cwd }) : null, typescript: () => loadAppTypeScript(cwd), extraKey: '', gitToken, full, write: true,
             eslint: async (files) => {
                 const listed = files === null ? null : files.map((file) => `${side}/${file}`);
-                const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], workspace: listed === null ? workspace : null, onFe: listed === null ? onFe : null, run });
-                return { results: sub.raw, errors: sub.errors };
+                const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], run, scopes: { [side]: scope }, handOutGraph: true });
+                return { results: sub.raw, errors: sub.errors, ...(sub.graphs[side] === undefined ? {} : { graph: sub.graphs[side] }) };
             },
             stylelint: styled ? async (files) => {
-                const linted = await (run ?? runLinter)({ cwd, pkg: 'stylelint', bin: 'stylelint', args: [...(files ?? [onFe ? `${onFe}/src/**/*.css` : STYLE_GLOB]), '--formatter', 'json'] });
+                const linted = await (run ?? runLinter)({ cwd, pkg: 'stylelint', bin: 'stylelint', args: [...(files ?? [STYLE_GLOB]), '--formatter', 'json'] });
                 const appRelative = appRelativeMessages(STYLE_SIDE, cwd);
                 for (const result of linted.results ?? [])
                     for (const warning of result.warnings ?? [])
@@ -536,164 +497,6 @@ export async function cachedLinters({ repoRoot, app, opts, workspace, onFe, run,
             style.ran = true;
         }
     }
-    cache.session.report(lintFamilyReport(sides));
+    session.report(lintFamilyReport(sides));
     return { eslint, stylelint: style, sides };
 }
-/** Starts stylelint over the fe stylesheets (the running child), or returns null when no stylesheet is in scope. */
-function launchStylelint({ repoRoot, opts, changed, existing, onFe, run }) {
-    if (opts.side === 'be')
-        return null;
-    const styles = onSide(existing, STYLE_SIDE).filter((file) => file.endsWith('.css'));
-    if (changed !== null && !styles.length)
-        return null;
-    return (run ?? runLinter)({ cwd: path.join(repoRoot, STYLE_SIDE), pkg: 'stylelint', bin: 'stylelint', args: [...(changed ? styles : [onFe ? `${onFe}/src/**/*.css` : STYLE_GLOB]), '--formatter', 'json', ...(opts.fix ? ['--fix'] : [])] });
-}
-/**
- * Run the whole lint of the app at `repoRoot`. `hfsCheck(repoRoot)` returns the `starci app check` result (`{ findings, tracked }`); the CLI
- * injects it. Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
- */
-export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [], runLinter: linter, cache }) {
-    const changed = opts.changed === null ? null : new Set(opts.changed);
-    const errors = [];
-    let workspace = null;
-    let validSide = true;
-    try {
-        validateSide(opts);
-    }
-    catch (error) {
-        errors.push(String(error?.message ?? error));
-        validSide = false;
-    }
-    if (opts.workspace !== undefined) {
-        try {
-            workspace = workspaceOf(opts.workspace);
-        }
-        catch (error) {
-            errors.push(String(error?.message ?? error));
-        }
-    }
-    /** Whether an app-relative path lies inside the scoped workspace. */
-    const inWorkspace = (file) => posix(file).startsWith(`${workspace}/`);
-    const existing = changed ? [...changed].filter((file) => fs.existsSync(path.join(repoRoot, file))) : [];
-    const findings = [];
-    const raw = { eslint: [], stylelint: [] };
-    const engines = {};
-    let app = null;
-    try {
-        app = readRepoDeclaration(loadSlotManifest(), repoRoot);
-    }
-    catch (error) {
-        errors.push(`starci app lint runs at the app root: ${String(error?.message ?? error)}`);
-    }
-    if (app && !app.sides) {
-        errors.push(`${repoRoot} is the ${app.side} side of an app; starci app lint runs at the app root, the folder of hfs.json`);
-        app = null;
-    }
-    if (!validSide || (opts.workspace !== undefined && workspace === null))
-        app = null;
-    if (workspace !== null && !fs.existsSync(path.join(repoRoot, workspace, 'package.json'))) {
-        errors.push(`--workspace ${workspace} holds no package.json; it is not a workspace of this app`);
-        app = null;
-    }
-    /** The workspace folder relative to the fe side folder (apps/<app> or packages/<pkg>). */
-    const onFe = workspace === null ? null : workspace.slice(STYLE_SIDE.length + 1);
-    // The linters and the app check are independent: every child starts first, the app check runs while they work, and the results are read in a fixed order.
-    // The cache serves a whole-side lint only: --changed judges named files and --fix rewrites them, so neither reads nor writes a record.
-    const cached = cache !== undefined && changed === null && !opts.fix ? cache : null;
-    const cachedRun = app && cached ? cachedLinters({ app, repoRoot, opts, workspace, onFe, run: linter, cache: cached }) : null;
-    const eslintRun = app ? (cachedRun ? cachedRun.then((answer) => answer.eslint) : eslintRepository({ app, repoRoot, opts, changed: changed ? [...changed] : null, existing, workspace, onFe, run: linter })) : null;
-    const styleLaunch = app && !cachedRun ? launchStylelint({ repoRoot, opts, changed, existing, onFe, run: linter }) : null;
-    const checkRun = app ? Promise.resolve().then(() => hfsCheck(repoRoot)).then((value) => ({ value, error: undefined }), (error) => ({ value: undefined, error })) : null;
-    // A transport refusal does not abandon a sibling child or let its rejection escape unobserved.
-    const completed = await Promise.allSettled([eslintRun, styleLaunch, checkRun]);
-    const refused = completed.filter((run) => run.status === 'rejected');
-    const failure = refused.find(run => isHostHeld(run.reason)) ?? refused[0];
-    if (failure !== undefined)
-        throw failure.reason;
-    // 1. ESLint, once per side, from the side folder with that side's config.
-    const eslint = eslintRun ? await eslintRun : { engine: { sides: {} }, errors: [], raw: [], findings: [] };
-    engines.eslint = eslint.engine;
-    errors.push(...eslint.errors);
-    raw.eslint.push(...eslint.raw);
-    findings.push(...eslint.findings);
-    // 3. stylelint over the fe side's stylesheets.
-    if (app) {
-        if (cachedRun) {
-            const answer = (await cachedRun).stylelint;
-            errors.push(...answer.errors);
-            if (answer.ran)
-                raw.stylelint = answer.results;
-            findings.push(...stylelintFindings(answer.results, repoRoot));
-        }
-        else if (styleLaunch) {
-            const linted = await styleLaunch;
-            if (linted.error)
-                errors.push(linted.error);
-            if (linted.results) {
-                const appRelative = appRelativeMessages(STYLE_SIDE, path.join(repoRoot, STYLE_SIDE));
-                for (const result of linted.results)
-                    for (const warning of result.warnings ?? [])
-                        warning.text = appRelative(warning.text);
-                raw.stylelint = linted.results;
-                findings.push(...stylelintFindings(linted.results, repoRoot));
-            }
-        }
-        engines.stylelint = { side: STYLE_SIDE, files: raw.stylelint.length };
-    }
-    // 2. The app check: root and sides.
-    let checked = { findings: [] };
-    if (checkRun) {
-        const settled = await checkRun;
-        if (isNodeExecutionRefusal(settled.error))
-            throw settled.error;
-        if (settled.error)
-            errors.push(`starci app check could not run: ${String(settled.error?.message ?? settled.error)}`);
-        else
-            checked = settled.value;
-    }
-    const repoErrors = checked.findings.filter((finding) => finding.level === 'error' && findingOnSide(finding, opts.side));
-    // A workspace lint keeps only the app findings inside the workspace; the rest belong to the root lint of the whole app.
-    const kept = workspace !== null
-        ? repoErrors.filter((finding) => finding.path && inWorkspace(finding.path))
-        : changed === null ? repoErrors : repoErrors.filter((finding) => !finding.path || changed.has(posix(finding.path)));
-    for (const finding of kept) {
-        findings.push({ engine: 'hfs', rule: finding.code, code: finding.code, severity: 'error', path: finding.path ? posix(finding.path) : null, line: finding.line ?? null, column: finding.column ?? null, message: finding.message, titleVi: finding.titleVi, nextStepVi: finding.nextStepVi });
-    }
-    engines.hfs = { findings: kept.length };
-    findings.sort(byLocation);
-    let properties = '';
-    try {
-        properties = fs.readFileSync(path.join(repoRoot, 'sonar-project.properties'), 'utf8');
-    }
-    catch { /* no properties: every finding keeps its own path */ }
-    const sourceRoots = sourceRootsOf(properties).filter((root) => findingOnSide({ path: root }, opts.side));
-    const tracked = sourceRoots.length ? trackedFiles(repoRoot) : [];
-    const sonar = mergeReports([
-        sonarReport(kept, { sourceRoots, tracked }),
-        linterReport('eslint', raw.eslint, { root: repoRoot, sourceRoots, tracked }),
-        linterReport('stylelint', raw.stylelint, { root: repoRoot, sourceRoots, tracked }),
-    ]);
-    // Green under the threshold (gate-threshold.mjs): every finding is still reported, only the verdict changes. A warning is a
-    // rule of the canon's counting cohort (eslint-canon-fe COUNTING): reported and counted per rule, never part of the verdict.
-    const failing = findings.filter((finding) => finding.severity !== 'warning');
-    const counting = {};
-    for (const finding of findings)
-        if (finding.severity === 'warning')
-            counting[finding.rule] = (counting[finding.rule] ?? 0) + 1;
-    const gate = gateVerdict(failing);
-    const report = { schema: LINT_SCHEMA, ok: gate.pass && errors.length === 0, repoRoot, changed: changed ? [...changed].sort(byCodeUnit) : null, workspace, ...(opts.side === undefined ? {} : { side: opts.side }), counts: { error: failing.length, warning: findings.length - failing.length }, counting, engines, errors, findings, gate };
-    return { report, sonar, exit: errors.length ? 2 : gate.pass ? 0 : 1 };
-}
-export function printLintText(report, out) {
-    for (const f of report.findings)
-        out(`${f.path ?? '-'}${f.line ? `:${f.line}${f.column ? `:${f.column}` : ''}` : ''}  ${f.severity === 'warning' ? 'warn ' : ''}${f.engine}/${f.rule}  ${f.message}\n`);
-    for (const e of report.errors)
-        out(`ERROR ${e}\n`);
-    const per = Object.keys(report.engines).map((engine) => `${engine} ${report.findings.filter((f) => f.engine === engine && f.severity !== 'warning').length}`).join(', ');
-    out(`\nstarci app lint: ${report.counts.error} finding${report.counts.error === 1 ? '' : 's'} (${per})${report.errors.length ? `, ${report.errors.length} tool error${report.errors.length === 1 ? '' : 's'}` : ''}\n`);
-    const counting = Object.entries((report.counting ?? {})).sort(([a], [b]) => a.localeCompare(b));
-    if (counting.length)
-        out(`counting (warn, not in the verdict): ${counting.map(([rule, count]) => `${rule} ${count}`).join(', ')}\n`);
-    if (report.gate?.line)
-        out(`${report.gate.line}\n`);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "5.0.7",
+  "version": "5.1.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/release/lint-report.d.mts

@@ -1,6 +1,6 @@
 import type { VerbContext } from './index.mjs';
 /**
- * Runs `starci app lint --side <side> --out <file>` for every side the app has, then writes reports/lint.sonar.json.
+ * Runs `starci app check --gate lint --side <side> --out <file>` for every side the app has, then writes reports/lint.sonar.json.
  * `launch` turns an argv into [command, args] for the platform. Returns { pass, text }: the honest log of every lint run and the verdict.
  * A lint that exits non-zero (findings or error) or writes no report fails the row; nothing is skipped.
  */

package/release/lint-report.mjs

@@ -1,5 +1,5 @@
 // lint-report.mjs - the external issues report the release gate's sonar row produces before it runs the scanner.
-// The app declares `sonar.externalIssuesReportPaths=reports/lint.sonar.json`; the managed CI makes it with `lint --side <side> --out reports/lint.<side>.sonar.json`
+// The app declares `sonar.externalIssuesReportPaths=reports/lint.sonar.json`; the managed CI makes it with `app check --gate lint --side <side> --out reports/lint.<side>.sonar.json`
 // per lint matrix side and a "merge Sonar lint reports" step. This module does the same locally, through the same process seam as every gate
 // (an argument array through ctx.spawn, never a shell). The merge below is the one in packages/hfs/sync/ci-commands.mjs (sonarMergeSteps): keep them identical.
 import fs from 'node:fs';
@@ -17,7 +17,7 @@ function mergeSonarReports(reports) {
 /** The sides the app has: a be/ or fe/ folder beside the app root. */
 const sidesOf = (root) => LINT_SIDES.filter((side) => fs.existsSync(path.join(root, side)));
 /**
- * Runs `starci app lint --side <side> --out <file>` for every side the app has, then writes reports/lint.sonar.json.
+ * Runs `starci app check --gate lint --side <side> --out <file>` for every side the app has, then writes reports/lint.sonar.json.
  * `launch` turns an argv into [command, args] for the platform. Returns { pass, text }: the honest log of every lint run and the verdict.
  * A lint that exits non-zero (findings or error) or writes no report fails the row; nothing is skipped.
  */
@@ -30,7 +30,7 @@ export function produceLintReports(ctx, { launch, platform, env }) {
     for (const side of sides) {
         const file = path.join(ctx.cwd, sideReport(side));
         fs.rmSync(file, { force: true });
-        const argv = ['npx', 'starci', 'app', 'lint', '--side', side, '--out', sideReport(side)];
+        const argv = ['npx', 'starci', 'app', 'check', '--gate', 'lint', '--side', side, '--out', sideReport(side)];
         const [command, args] = launch(argv, platform);
         out.push(`$ ${argv.join(' ')}\n`);
         const run = tool(ctx, command, args, { cwd: ctx.cwd, env });

package/report/sonar.d.mts

@@ -48,7 +48,7 @@ interface CheckFinding {
     line?: number;
 }
 type LinterResult = any;
-/** One document of several (the starci-hfs, eslint and stylelint documents of one app lint): rules by id, issues in the one sort order. */
+/** One document of several (the starci-hfs, eslint and stylelint documents of one app check): rules by id, issues in the one sort order. */
 export declare function mergeReports(reports: readonly SonarDocument[]): SonarDocument;
 /**
  * The Generic Issue Import document of a check's findings (the `findings` of checkRepository, each with the catalog's

package/report/sonar.mjs

@@ -1,10 +1,10 @@
-// Sonar documents of the ONE lint entry `starci app lint`: the building blocks that turn the
+// Sonar documents of the lint gate of `starci app check` (`--out`): the building blocks that turn the
 // findings of the StarCi canon into a Sonar Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`).
 //   sonarReport(findings)        the repository findings of `starci app check`, engineId `starci-hfs`, rule id = the finding code
 //   linterReport(kind, results)  a linter's own json output (`eslint -f json`, `stylelint --formatter json`), engineId `eslint` / `stylelint`,
 //                                rule id = the linter's rule. Sonar's own ESLint import (sonar.eslint.reportPaths) is not used: it drops an
 //                                issue on a file outside sonar.sources, and a stylelint result has no native import at all.
-//   mergeReports(reports)        the documents of one `starci app lint` run as ONE file
+//   mergeReports(reports)        the documents of one `starci app check` run as ONE file
 // One placement rule for every engine: Sonar imports an issue only on a file it indexes (a tracked source or stylesheet under
 // sonar.sources). A finding on any other path (hfs.json, a workflow, a package under an unindexed root, e2e/, a directory) is filed
 // on the first source file of sonar.sources and its message names the real path, so no finding is dropped.
@@ -33,7 +33,7 @@ function document(rules, issues) {
     const used = new Set(sorted.map((issue) => issue.ruleId));
     return { rules: [...rules.values()].filter((rule) => used.has(rule.id)).sort((a, b) => cmp(a.id, b.id)), issues: sorted };
 }
-/** One document of several (the starci-hfs, eslint and stylelint documents of one app lint): rules by id, issues in the one sort order. */
+/** One document of several (the starci-hfs, eslint and stylelint documents of one app check): rules by id, issues in the one sort order. */
 export function mergeReports(reports) {
     const rules = new Map(reports.flatMap((report) => report.rules).map((rule) => [rule.id, rule]));
     return document(rules, reports.flatMap((report) => report.issues));