@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/patch-lint.d.ts

@@ -1,191 +0,0 @@
-import type { PatchLintIssue } from '../types/commands/index.js';
-import type { FireForgeConfig, ProjectLicense } from '../types/config.js';
-import { type CommentStyle } from './license-headers.js';
-import { lintPatchedCss } from './patch-lint-css.js';
-import { type LintIgnoreChecks } from './patch-lint-ignore.js';
-import { type PatchSizeMeasurement } from './patch-lint-size.js';
-export * from './patch-lint-cross.js';
-export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
-export { lintPatchedCss };
-export { countNonBinaryDiffLines, getPatchSizeThresholds, isTestFile, lintPatchSize, measurePatchSize, type PatchSizeMeasurement, type PatchSizeTierDecision, resolvePatchSizeTier, } from './patch-lint-size.js';
-export type { PatchSizeThresholds } from './patch-lint-size-thresholds.js';
-/**
- * Canonical `[check] file: message` rendering of a patch-lint issue. It is
- * the one string shape every reporter and refusal message uses, so operators
- * can grep one format across lint output and refusal details.
- */
-export declare function formatPatchLintIssue(issue: Pick<PatchLintIssue, 'check' | 'file' | 'message'>): string;
-/**
- * The files the `file-too-large` rule measures for a patch: the JS files
- * (`.js`, `.mjs`, `.sys.mjs`, …) the patch creates. A modified file is
- * never measured, and neither is a new file of another kind (CSS, FTL,
- * markup), however long. This is the rule's own predicate, not a mirror
- * of it: the rule selects its files through the same function.
- *
- * @param patchText - Unified-diff body of one patch
- * @returns Engine-relative paths the rule would size-check
- */
-export declare function filesMeasuredByFileTooLarge(patchText: string): Set<string>;
-/** True when `strippedContent` contains at least one assertion call. */
-export declare function hasBrowserChromeAssertion(strippedContent: string): boolean;
-/**
- * Detects comment style from file extension for license header checks.
- */
-export declare function commentStyleForFile(file: string): CommentStyle | null;
-/**
- * Decides whether a new file's leading header satisfies the
- * `missing-license-header` rule. It is the single owner of the acceptance
- * policy: `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
- * interactive export fixer) must agree, or the fixer offers to stack a
- * second header onto a file the lint already accepts.
- *
- * Accepted shapes, in order:
- *  - the project's own header for the file's comment style.
- *  - under `browser/branding/`, any recognised license header in the
- *    matching style: the setup-generated branding directory is copied from
- *    Firefox's `unofficial` template and arrives with Mozilla MPL-2.0
- *    headers, legitimate for copyright purposes (the assets are Mozilla's)
- *    even when the fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later.
- *  - on an MPL-2.0 project, any recognised header in the matching style.
- *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
- *    behind a leading editor-directive comment) regardless of the project
- *    license, on any file whose comment syntax is the block form (JS and
- *    CSS): a file copied from the Firefox tree legitimately keeps Mozilla's
- *    header for provenance in an EUPL/GPL/0BSD project too. Only the block
- *    form is accepted, because the `// `-style MPL header is
- *    FireForge-generated rather than upstream provenance, and `hash`-style
- *    files (FTL) stay excluded
- *    because `/* … *\/` is not a comment there.
- *
- * @param file - Engine-relative path of the new file
- * @param content - File content
- * @param style - Comment style resolved for the file
- * @param license - The project license
- */
-export declare function isAcceptableNewFileHeader(file: string, content: string, style: CommentStyle, license: ProjectLicense): boolean;
-/**
- * Checks new files for required license headers (acceptance policy in
- * {@link isAcceptableNewFileHeader}).
- *
- * @param repoDir - Absolute path to the engine directory
- * @param newFiles - New file paths (relative to repoDir)
- * @param config - Project configuration
- * @returns Array of lint issues
- */
-export declare function lintNewFileHeaders(repoDir: string, newFiles: string[], config: FireForgeConfig): Promise<PatchLintIssue[]>;
-/**
- * Lints patched JS/MJS files for import conventions, file size, JSDoc, and
- * observer topic naming.
- *
- * @param repoDir - Absolute path to the engine directory
- * @param affectedFiles - File paths (relative to repoDir)
- * @param newFiles - Set of files that are newly created in this patch
- * @param config - Project configuration
- * @param patchOwnedFiles - Optional set of patch-owned `.sys.mjs` paths for scoped JSDoc enforcement
- * @param patchOwnedChromeScripts - Optional set of patch-owned chrome
- *   subscripts (`.js` non-`.sys.mjs`) for scoped chrome-script JSDoc
- *   enforcement. Built by {@link resolvePatchOwnedChromeScripts}. Passed
- *   separately from `patchOwnedFiles` so the `runCheckJs` consumer (which
- *   only accepts `.sys.mjs`) is not silently broadened.
- * @returns Array of lint issues
- */
-export declare function lintPatchedJs(repoDir: string, affectedFiles: string[], newFiles: Set<string>, config: FireForgeConfig, patchOwnedFiles?: Set<string>, patchOwnedChromeScripts?: Set<string>): Promise<PatchLintIssue[]>;
-/**
- * Checks that modifications to existing (non-new) JS/MJS files include at
- * least one `// BINARYNAME:` comment in the added lines.
- *
- * @param diffContent - Raw unified diff string
- * @param config - Project configuration
- * @returns Array of lint issues
- */
-export declare function lintModificationComments(diffContent: string, config: FireForgeConfig): PatchLintIssue[];
-/**
- * Checks that modified (non-new) files with a supported extension still
- * start with a recognized license header.
- *
- * @param repoDir - Engine root directory
- * @param affectedFiles - All files affected by the patch
- * @param newFiles - Set of newly created files (excluded from this check)
- * @returns Warning-level lint issues for files missing any recognized header
- */
-export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles: string[], newFiles: Set<string>): Promise<PatchLintIssue[]>;
-/**
- * Optional behaviour switches for {@link lintExportedPatch}.
- */
-export interface LintExportedPatchOptions {
-    /**
-     * Cross-patch context for ownership resolution. Present whenever the
-     * caller has a loaded patch queue. Absent for the ad-hoc single-diff
-     * paths that have no queue to resolve against.
-     */
-    patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext;
-    /**
-     * Per-patch `check` IDs to drop from the returned issues. Threaded from
-     * `PatchMetadata.lintIgnore` so a patch that is advisory-noisy by nature
-     * (a cohesive branding bundle, auto-generated manifest, etc.) can opt out
-     * of a specific rule without reaching for the blunt `--skip-lint` hammer.
-     * Not mutated.
-     */
-    ignoreChecks?: LintIgnoreChecks;
-    /**
-     * Explicit tier override, threaded from `PatchMetadata.tier`. When
-     * `"branding"` forces the branding thresholds on the
-     * `large-patch-lines` rule. Callers with a per-patch manifest context
-     * (re-export, per-patch lint) should pass this. Aggregate-mode callers
-     * without a specific patch context omit it and fall through to
-     * auto-detection.
-     */
-    patchTier?: 'branding';
-    /**
-     * Skip the patch-size rules (`large-patch-files` / `large-patch-lines`).
-     * The ad-hoc `fireforge lint <files>` path passes a cross-patch file
-     * list that does not correspond to a single patch, so it suppresses the
-     * synthetic combined-list size check here and re-evaluates the size
-     * rules per owning patch instead, never synthesising a phantom
-     * oversized patch from the operator's file selection.
-     */
-    skipPatchSize?: boolean;
-    /**
-     * Restrict checkJs diagnostics to these repo-relative files. Module
-     * resolution still spans every owned file in `patchQueueCtx`. Export and
-     * re-export pass the patch under export so cross-patch `resource:///`
-     * imports resolve against the whole queue while only that patch's
-     * findings surface.
-     */
-    checkJsReportScope?: ReadonlySet<string>;
-    /**
-     * Pre-computed checkJs issues for this patch. When provided, the internal
-     * checkJs invocation is skipped and these are appended verbatim: the
-     * per-patch lint path builds one queue-wide checkJs program and
-     * attributes findings per patch instead of rebuilding per patch.
-     */
-    precomputedCheckJs?: readonly PatchLintIssue[];
-    /**
-     * Invoked with the issues dropped by the `ignoreChecks` waiver filter,
-     * when any were. Suppression semantics are unchanged (the returned issue
-     * list still excludes them), but the caller can report
-     * the measurement a waived size finding carried (per-patch NOTICE lines
-     * and the `--report` JSON) instead of losing it entirely.
-     */
-    onSuppressed?: (suppressed: PatchLintIssue[]) => void;
-    /**
-     * The patch's {@link measurePatchSize} result, when the caller already
-     * measured it for its own report or cache row. Absent, the size rules
-     * measure the diff themselves.
-     */
-    patchSizeMeasurement?: PatchSizeMeasurement;
-}
-/**
- * Runs all patch lint checks and returns combined issues.
- *
- * @param repoDir - Absolute path to the engine directory
- * @param affectedFiles - File paths (relative to repoDir) affected by the patch
- * @param diffContent - Raw unified diff string
- * @param config - Project configuration
- * @param options - Optional context and behaviour switches. See
- *   {@link LintExportedPatchOptions}. Every optional input lives here
- *   rather than in a positional tail: four of the five call sites had to
- *   pass `undefined` placeholders to reach the one member they wanted.
- * @returns Array of all lint issues found
- */
-export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, options?: LintExportedPatchOptions): Promise<PatchLintIssue[]>;