@starci/hfs 4.12.2 → 4.13.2

package/cache/jsonl.d.mts

@@ -0,0 +1,31 @@
+import type { CacheRecord, Finding, JsonValue } from './types.mjs';
+/** `value` as JSON with every object's keys sorted and undefined members dropped. */
+export declare function canonicalJson(value: unknown): string;
+/** Findings sorted by line, column, rule, message. */
+export declare function sortFindings(findings: readonly Finding[]): Finding[];
+/** Records sorted by path, then step. */
+export declare function sortRecords(records: readonly CacheRecord[]): CacheRecord[];
+/** The file text of `records`: sorted, one canonical line each, LF, a final newline; the empty set is the empty text. */
+export declare function serializeRecords(records: readonly CacheRecord[]): string;
+/** What a file held: the records it parsed and how many lines were not one (a half-merged or hand-damaged line). */
+export interface ParsedRecords {
+    readonly records: CacheRecord[];
+    readonly invalid: number;
+}
+/** Parses a record file. CRLF is tolerated; a line that is not a record is counted and skipped, never thrown on. */
+export declare function parseRecords(text: string): ParsedRecords;
+/**
+ * The records a union merge may have doubled, reduced to one per (path, step): the one whose hash matches the tree
+ * (`currentHash(path)`); the rest are dropped. A key whose matching records differ keeps none (two branches disagreeing is a
+ * mismatch, so the step judges again).
+ */
+export declare function reconcile(records: readonly CacheRecord[], currentHash: (path: string) => string | undefined): CacheRecord[];
+/**
+ * The area a record belongs to: the first `depth` folders of its path (`modules/billing` for `modules/billing/a/b.ts`), or
+ * `root` for a file with no folder. A change rewrites only the area files it touched.
+ */
+export declare function areaOf(path: string, depth?: number): string;
+/** Records grouped by area file name (`<area>.jsonl`), groups and files sorted. */
+export declare function groupByArea(records: readonly CacheRecord[], depth?: number): Map<string, CacheRecord[]>;
+/** True when `value` survives JSON unchanged: a guard for record payloads. */
+export declare function isJsonValue(value: unknown): value is JsonValue;

package/cache/jsonl.mjs

@@ -0,0 +1,115 @@
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === 'object') {
+        const source = value;
+        const out = {};
+        for (const key of Object.keys(source).sort(compare))
+            if (source[key] !== undefined)
+                out[key] = sortKeys(source[key]);
+        return out;
+    }
+    return value;
+}
+/** `value` as JSON with every object's keys sorted and undefined members dropped. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+/** Findings sorted by line, column, rule, message. */
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => a.line - b.line || a.column - b.column || compare(a.rule, b.rule) || compare(a.message, b.message));
+}
+/** Records sorted by path, then step. */
+export function sortRecords(records) {
+    return [...records].sort((a, b) => compare(a.path, b.path) || compare(a.step, b.step));
+}
+/** The file text of `records`: sorted, one canonical line each, LF, a final newline; the empty set is the empty text. */
+export function serializeRecords(records) {
+    const lines = sortRecords(records).map((record) => canonicalJson({ ...record, findings: sortFindings(record.findings) }));
+    return lines.length === 0 ? '' : `${lines.join('\n')}\n`;
+}
+function isRecord(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    return typeof v['path'] === 'string' && typeof v['step'] === 'string' && typeof v['hash'] === 'string' && Array.isArray(v['findings']);
+}
+/** Parses a record file. CRLF is tolerated; a line that is not a record is counted and skipped, never thrown on. */
+export function parseRecords(text) {
+    const records = [];
+    let invalid = 0;
+    for (const raw of text.split('\n')) {
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (line.trim() === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isRecord(parsed))
+                records.push(parsed);
+            else
+                invalid += 1;
+        }
+        catch {
+            invalid += 1;
+        }
+    }
+    return { records, invalid };
+}
+/**
+ * The records a union merge may have doubled, reduced to one per (path, step): the one whose hash matches the tree
+ * (`currentHash(path)`); the rest are dropped. A key whose matching records differ keeps none (two branches disagreeing is a
+ * mismatch, so the step judges again).
+ */
+export function reconcile(records, currentHash) {
+    const byKey = new Map();
+    for (const record of records) {
+        if (currentHash(record.path) !== record.hash)
+            continue;
+        const key = `${record.path}\0${record.step}`;
+        byKey.set(key, [...(byKey.get(key) ?? []), record]);
+    }
+    const out = [];
+    for (const group of byKey.values()) {
+        const first = group[0];
+        if (first === undefined)
+            continue;
+        const text = canonicalJson(first);
+        if (group.every((record) => canonicalJson(record) === text))
+            out.push(first);
+    }
+    return sortRecords(out);
+}
+/**
+ * The area a record belongs to: the first `depth` folders of its path (`modules/billing` for `modules/billing/a/b.ts`), or
+ * `root` for a file with no folder. A change rewrites only the area files it touched.
+ */
+export function areaOf(path, depth = 2) {
+    const folders = path.split('/').slice(0, -1).slice(0, depth);
+    return folders.length === 0 ? 'root' : folders.join('/');
+}
+/** Records grouped by area file name (`<area>.jsonl`), groups and files sorted. */
+export function groupByArea(records, depth = 2) {
+    const groups = new Map();
+    for (const record of records) {
+        const file = `${areaOf(record.path, depth)}.jsonl`;
+        groups.set(file, [...(groups.get(file) ?? []), record]);
+    }
+    for (const [file, group] of groups)
+        groups.set(file, sortRecords(group));
+    return new Map([...groups].sort(([a], [b]) => compare(a, b)));
+}
+/** True when `value` survives JSON unchanged: a guard for record payloads. */
+export function isJsonValue(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (typeof value === 'object')
+        return Object.values(value).every(isJsonValue);
+    return false;
+}

package/cache/lint-family.d.mts

@@ -0,0 +1,162 @@
+import type TypeScript from 'typescript';
+import type { CheckSession, FamilyReport } from './types.mjs';
+type Ts = typeof TypeScript;
+/** Record steps of the `lint/<side>` folder. */
+export declare const LINT_STEPS: Readonly<{
+    eslint: "eslint";
+    stylelint: "stylelint";
+    imports: "imports";
+    graph: "graph";
+    meta: "meta";
+}>;
+/** The record path of the side's own record (no file of the tree holds it). */
+export declare const SIDE_RECORD = ".side";
+/** One input a rule reads that the import graph does not carry (`crossFileInputs` of a canon; see its cross-file-inputs.ts). */
+export interface CrossFileInput {
+    readonly rule: string;
+    readonly kind: 'content' | 'exists' | 'git';
+    readonly relativeTo: 'file' | 'side';
+    readonly globs: readonly string[];
+    readonly appliesTo: readonly string[];
+    /** For `git`: the line count above which the rule reads history; a shorter file does not depend on it. */
+    readonly minLines?: number;
+    readonly reader?: string;
+}
+/** One finding of the canon's project graph on a file. */
+export interface GraphFinding {
+    readonly rule: string;
+    readonly code: string;
+    readonly line: number;
+    readonly column: number;
+    readonly message: string;
+}
+/** What a canon's `projectGraph` export answers. */
+export interface GraphSnapshot {
+    readonly files?: number;
+    readonly byFile: Readonly<Record<string, readonly GraphFinding[]>>;
+}
+/** What the family needs to know of one installed canon (an ESLint canon, a grammar family, the stylelint canon). */
+export interface CanonDeclarations {
+    /** The package name, for the reason line. */
+    readonly name: string;
+    /** Its `crossFileInputs`, or null when the installed canon does not declare them (the side is then linted whole). */
+    readonly crossFileInputs: readonly CrossFileInput[] | null;
+    /** Whether the canon publishes project-graph rules. */
+    readonly graphRules: boolean;
+    /** Its `projectGraph` export; null when it publishes graph rules without the export (the side is then linted whole). */
+    readonly projectGraph: ((input: {
+        repoRoot: string;
+    }) => GraphSnapshot) | null;
+}
+/** The fields of an ESLint result the cache keeps and rebuilds. */
+export interface EslintMessage {
+    ruleId: string | null;
+    message: string;
+    line?: number;
+    column?: number;
+    endLine?: number;
+    severity?: number;
+    [key: string]: unknown;
+}
+export interface EslintResult {
+    filePath: string;
+    messages: EslintMessage[];
+    [key: string]: unknown;
+}
+/** The fields of a stylelint result the cache keeps and rebuilds. */
+export interface StylelintWarning {
+    rule: string;
+    text: string;
+    line?: number;
+    column?: number;
+    endLine?: number;
+    severity?: string;
+    [key: string]: unknown;
+}
+export interface StylelintResult {
+    source: string;
+    warnings: StylelintWarning[];
+    [key: string]: unknown;
+}
+/** The answer of a linter seam: validated results of the files it was asked about, or why it could not complete. */
+export interface LinterOutcome<R> {
+    results: R[];
+    errors: string[];
+}
+/** Everything one side's cached lint needs. */
+export interface LintSideInput {
+    session: CheckSession;
+    side: string;
+    /** The absolute side folder, where the linters run from. */
+    sideRoot: string;
+    /** The canon scope of the side, enumerated afresh: side-relative posix source files. */
+    scope: readonly string[];
+    /** The stylesheets stylelint judges (fe only): side-relative posix; empty otherwise. */
+    stylesheets: readonly string[];
+    /** The files this run reports when it reports part of a side (a workspace lint); null reports the whole side. A partial run never writes. */
+    report: ((file: string) => boolean) | null;
+    /** The ESLint canon, its grammar family, in config order. */
+    canons: readonly CanonDeclarations[];
+    /** The stylelint canon; null when the side has no stylesheet judge. */
+    styleCanon: CanonDeclarations | null;
+    /** The app's own TypeScript, for the import graph. */
+    typescript: () => Ts;
+    /** A digest of the side's untracked program inputs (generated code the program reads); a change dirties the side. */
+    extraKey: string;
+    /** The merge-base of HEAD with the base branch (what the size-growth rules compare with), or a marker when there is none; `git` inputs depend on it. */
+    gitToken?: string;
+    /** Set for `--full` or a full decision: ignore the records and rewrite them. */
+    full: string | null;
+    /** Whether this run may write the side's records. */
+    write: boolean;
+    /** ESLint over `files` (side-relative), or over the whole requested scope when null; results already validated and with app-relative messages. */
+    eslint: (files: readonly string[] | null) => Promise<LinterOutcome<EslintResult>>;
+    /** stylelint over `files`, or over the whole glob when null. Absent when the side has no stylesheet judge. */
+    stylelint: ((files: readonly string[] | null) => Promise<LinterOutcome<StylelintResult>>) | null;
+}
+/** What one side's lint reports back to the verb. */
+export interface LintSideOutcome {
+    eslint: EslintResult[];
+    stylelint: StylelintResult[];
+    errors: string[];
+    stats: LintSideStats;
+}
+/** The counts and the reason of a side, for the family line. */
+export interface LintSideStats {
+    mode: 'full' | 'diff';
+    reason: string;
+    checked: number;
+    reused: number;
+    newFindings: number;
+    knownFindings: number;
+    fixedFindings: number;
+    written: boolean;
+}
+/**
+ * The digest of what the declared cross-file inputs of `file` hold now: for each declaration that applies, the matching paths of the app with
+ * their hashes (`content`) or alone (`exists`). Undefined when no declaration applies. `paths` are app-relative; side-relative globs are
+ * resolved below `<side>/`, so a glob may step out of the side with `../` to the app root.
+ */
+export declare function crossDigestFactory(options: {
+    side: string;
+    declarations: readonly CrossFileInput[];
+    paths: readonly string[];
+    hashOf: (appRelative: string) => string | undefined;
+    /** The state of git history the `git` inputs stand for (the merge-base with the base branch); changes when the base moves. */
+    gitToken?: string;
+    /** The line count of a side-relative file, for the `git` inputs that matter only above a size. */
+    lineCountOf?: (file: string) => number;
+}): (file: string) => string | undefined;
+/** The TypeScript the app installed, resolved from the side folder like the linters are (not this package's own copy). */
+export declare function loadAppTypeScript(sideRoot: string): Ts;
+/**
+ * Judges one side: ESLint (and, for fe, stylelint) over what the records cannot vouch for, the records of the rest, and the new records.
+ * Never throws for a tool failure: those come back in `errors`, and a side with an error stores nothing.
+ */
+export declare function lintSide(input: LintSideInput): Promise<LintSideOutcome>;
+/** The family line of a run over several sides: one report for the family, the sides' counts added and their reasons joined. */
+export declare function lintFamilyReport(sides: readonly {
+    side: string;
+    stats: LintSideStats;
+}[]): FamilyReport;
+export {};