@starci/hfs 5.0.7 → 5.1.0

package/lint/eslint-list.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// eslint-list.cts - ESLint over a list of files in ONE process, through the app's own install (the Node API of the ESLint the side's folder resolves).
+//
+// The CLI of ESLint takes its files as arguments, and a diff of hundreds of long paths outgrows the Windows command line (32,767 characters), which
+// used to cut the list into chunks that each built the whole TypeScript program again. This runner reads the list from a JSON file named by its one
+// argument ({ files, fix }), lints it once from its working directory (the side folder) and prints the results as the `--format json` of the CLI
+// does (the list of result objects), so the launcher validates them the same way. Its exit code is the CLI's: 0 clean of errors, 1 at least one
+// error, 2 the run could not complete (the message is on stderr). It stays CommonJS like bound-sys.cts, which may be preloaded in front of it.
+//
+// The project graph the canon's graph rules read is built in this process, once per side. When the job names the canons (`graph.canons`, the entry file
+// of each installed canon) and a file (`graph.out`), the runner asks each canon for the snapshot of the graph it built (`projectGraphSnapshot`) after
+// the lint and writes `{ snapshots }` there, so the cache keeps the graph findings without building the graph a second time in the CLI. A canon that
+// cannot answer leaves its snapshot out; the report and the exit code are never affected.
+const fs = require('node:fs');
+const path = require('node:path');
+const { createRequire } = require('node:module');
+const { pathToFileURL } = require('node:url');
+/** Writes the snapshot of the graph each named canon built in this process; a canon that cannot answer is left out. */
+async function handOutGraph(handoff, repoRoot) {
+    const snapshots = {};
+    for (const { name, entry } of handoff.canons) {
+        try {
+            const canon = await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href));
+            if (typeof canon.projectGraphSnapshot === 'function')
+                snapshots[name] = canon.projectGraphSnapshot({ repoRoot });
+        }
+        catch { /* the cache builds this canon's graph itself */ }
+    }
+    fs.writeFileSync(handoff.out, JSON.stringify({ snapshots }));
+}
+async function main() {
+    const job = JSON.parse(fs.readFileSync(String(process.argv[2]), 'utf8'));
+    const cwd = process.cwd();
+    const { ESLint } = createRequire(path.join(cwd, 'package.json'))('eslint');
+    const results = await new ESLint({ cwd, fix: job.fix }).lintFiles(job.files);
+    if (job.fix)
+        await ESLint.outputFixes(results);
+    if (job.graph !== undefined)
+        await handOutGraph(job.graph, cwd);
+    process.stdout.write(JSON.stringify(results));
+    return results.some((result) => result.errorCount > 0 || result.fatalErrorCount > 0) ? 1 : 0;
+}
+main().then((code) => { process.exitCode = code; }, (error) => {
+    process.stderr.write(`${String(error?.stack ?? error)}\n`);
+    process.exitCode = 2;
+});

package/lint/run.d.mts

@@ -1,34 +1,40 @@
 import { type HeavyNodeRun } from '../runtime/scripts/api/node/run-node.mjs';
-import { type CanonDeclarations, type LintSideStats } from '../cache/lint-family.mjs';
+import { type CanonDeclarations, type GraphSnapshot, type LintSideStats } from '../cache/lint-family.mjs';
 import type { CheckSession } from '../cache/types.mjs';
 type Dynamic = any;
-/** The parsed arguments of the lint verb. */
-export interface LintOptions {
-    changed: string[] | null;
-    fix: boolean;
-    format: string;
-    out: string | undefined;
-    workspace: string | undefined;
-    side?: string;
-    full?: boolean;
-}
-/** The cache a lint run may use: the session of the check cache. The caller flushes it after the run. */
-export interface LintCache {
-    session: CheckSession;
-}
-/** What a linter run answers: its json results, or why it could not complete (both when the run was partial). */
+/**
+ * The project-graph findings of one canon, as its `projectGraphSnapshot` answers them: by side-relative posix path.
+ * The ESLint child builds this graph for the canon's graph rules, so it hands the snapshot out instead of the cache building the same graph again.
+ */
+export type GraphSnapshotParts = Readonly<Record<string, GraphSnapshot>>;
+/** What a linter run answers: its json results, or why it could not complete (both when the run was partial), and the graph snapshots its child handed out, by canon name. */
 export interface LinterRun {
     results?: Dynamic[];
     error?: string;
+    graph?: GraphSnapshotParts;
 }
-/** The seam that runs a linter through the app's own install from cwd. */
-export type LinterRunner = (spec: {
+/**
+ * What a linter run is asked for. `list` is the files an ESLint run lints (cwd-relative, posix) when they are named one by one: they go to the child
+ * through a file, never the command line, and `args` then holds the options alone. `files` is the number of source files the run judges, which the
+ * heavy-command budget of the ESLint kind scales with (a list names its own count).
+ */
+export interface LinterSpec {
     cwd: string;
     pkg: string;
     bin: string;
     args: string[];
     bound?: string | null;
-}) => Promise<LinterRun>;
+    list?: readonly string[] | undefined;
+    files?: number | undefined;
+    graph?: readonly GraphCanon[] | undefined;
+}
+/** An installed canon whose graph snapshot the ESLint child hands out: its package name and the entry file the child imports. */
+export interface GraphCanon {
+    name: string;
+    entry: string;
+}
+/** The seam that runs a linter through the app's own install from cwd. */
+export type LinterRunner = (spec: LinterSpec) => Promise<LinterRun>;
 /** One finding of the lint report. */
 export interface LintFinding {
     engine: string;
@@ -39,17 +45,9 @@ export interface LintFinding {
     line: number | null;
     column: number | null;
     message: string;
-    titleVi?: string;
-    nextStepVi?: string;
 }
 /** The app declaration the slot machine returns (readRepoDeclaration): sides are present at an app root. */
 type RepoDeclaration = Dynamic;
-export declare const LINT_SCHEMA = "starci/lint@1";
-/** 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 declare function workspaceOf(workspace: string): string;
-/** 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 declare function parseLintArgs(argv: readonly string[]): LintOptions;
 /**
  * The heap of the ESLint child in MiB: the starci CLI sets it from its one owner, the eslint memory of ops/liveness.yaml `heavy` (a typed whole-side
  * lint of a large app outgrows node's default heap). Unset, ESLint runs on node's default.
@@ -57,13 +55,7 @@ export declare function parseLintArgs(argv: readonly string[]): LintOptions;
 export declare const ESLINT_HEAP_ENV = "STARCI_ESLINT_HEAP_MB";
 export declare function eslintHeapArgs(env?: NodeJS.ProcessEnv): string[];
 /** 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 declare function runLinter({ cwd, pkg, bin, args, bound }: {
-    cwd: string;
-    pkg: string;
-    bin: string;
-    args: string[];
-    bound?: string | null;
-}, execute?: HeavyNodeRun): Promise<LinterRun>;
+export declare function runLinter({ cwd, pkg, bin, args, bound, list, files, graph }: LinterSpec, execute?: HeavyNodeRun): Promise<LinterRun>;
 /**
  * The lint scope a flat config declares: `ignored(file)` for its global ignores (a block holding only `ignores` and `name`), which prune
  * the walk, and `source(file)` for a file some block's `files` select while that block's own `ignores` do not (standard flat-config
@@ -85,8 +77,8 @@ export declare function installedLintConfig({ repoRoot, cwd, side }: {
     cwd: string;
     side: string;
 }): Promise<Dynamic[]>;
-/** Execute each side's installed ESLint config once; check and lint share scope, coverage and tool-failure judgment. */
-export declare function eslintRepository({ repoRoot, app, opts, changed, existing, workspace, onFe, run }: {
+/** 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 declare function eslintRepository({ repoRoot, app, opts, changed, existing, run, scopes, handOutGraph }: {
     repoRoot: string;
     app?: RepoDeclaration;
     opts?: {
@@ -95,9 +87,9 @@ export declare function eslintRepository({ repoRoot, app, opts, changed, existin
     };
     changed?: readonly string[] | null;
     existing?: readonly string[];
-    workspace?: string | null;
-    onFe?: string | null;
     run?: LinterRunner | undefined;
+    scopes?: Readonly<Record<string, readonly string[]>> | undefined;
+    handOutGraph?: boolean | undefined;
 }): Promise<{
     findings: LintFinding[];
     errors: string[];
@@ -108,6 +100,7 @@ export declare function eslintRepository({ repoRoot, app, opts, changed, existin
             skipped?: string;
         }>;
     };
+    graphs: Record<string, GraphSnapshotParts>;
 }>;
 /** What the cache reads of the canons a side lints with: the ESLint canon (which publishes the project-graph rules) and the grammar family of the fe side. */
 export declare function canonDeclarations({ repoRoot, cwd, side }: {
@@ -122,7 +115,7 @@ export declare function canonDeclarations({ repoRoot, cwd, side }: {
 export declare function gitBaseToken(repoRoot: string): string;
 /** What the cached linters answer: the ESLint answer in the shape of eslintRepository's, the stylelint results, and each side's counts. */
 export interface CachedLinters {
-    eslint: Awaited<ReturnType<typeof eslintRepository>>;
+    eslint: Omit<Awaited<ReturnType<typeof eslintRepository>>, 'graphs'>;
     stylelint: {
         results: Dynamic[];
         errors: string[];
@@ -138,30 +131,11 @@ export interface CachedLinters {
  * 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 declare function cachedLinters({ repoRoot, app, opts, workspace, onFe, run, cache }: {
+export declare function cachedLinters({ repoRoot, app, side: only, run, session }: {
     repoRoot: string;
     app: RepoDeclaration;
-    opts: LintOptions;
-    workspace: string | null;
-    onFe: string | null;
+    side?: string | undefined;
     run?: LinterRunner | undefined;
-    cache: LintCache;
+    session: CheckSession;
 }): Promise<CachedLinters>;
-/**
- * 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 declare function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles, runLinter: linter, cache }: {
-    repoRoot: string;
-    opts: LintOptions;
-    hfsCheck: (repoRoot: string) => Dynamic;
-    trackedFiles?: (repoRoot: string) => string[];
-    runLinter?: LinterRunner | undefined;
-    cache?: LintCache | undefined;
-}): Promise<{
-    report: Dynamic;
-    sonar: Dynamic;
-    exit: number;
-}>;
-export declare function printLintText(report: Dynamic, out: (text: string) => unknown): void;
 export {};