@noctcore/lint-meta-rules 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,395 @@
+import { IMetaRule } from '@noctcore/harness';
+
+/**
+ * Options for {@link createAgentsDocPresenceRule}.
+ *
+ * De-projected from nightcore, which hardcoded `AGENTS.md`, the root/apps/packages
+ * layout and a fixed leaf opt-out set. The doc filename, which dirs require it,
+ * and the opt-out list are all options.
+ */
+interface AgentsDocPresenceOptions {
+    /** The agent-contract filename required in each location. Default `'AGENTS.md'`. */
+    readonly docFile?: string;
+    /** Whether the repo root must carry the doc. Default `true`. */
+    readonly requireAtRoot?: boolean;
+    /** `package.json` globs for deployable surfaces (all require the doc). Default `['apps/*\/package.json']`. */
+    readonly surfaceGlobs?: readonly string[];
+    /** `package.json` globs for library packages (require the doc unless opted out). Default `['packages/*\/package.json']`. */
+    readonly packageGlobs?: readonly string[];
+    /** Package directories exempt from the requirement. Default `[]`. */
+    readonly optOut?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Agent-contract coverage. Every deployable surface and public boundary must
+ * ship the agent-contract doc so an agent editing it reads the guardrails first.
+ * Trivial leaf packages may be opted out; a NEW package must ship the doc by
+ * default.
+ */
+declare function createAgentsDocPresenceRule(options?: AgentsDocPresenceOptions): IMetaRule;
+
+/**
+ * Options for {@link createCanonicalHelpersSingleHomeRule}.
+ *
+ * De-projected from nightcore, which hardcoded `apps/web/src/**\/*.utils.ts` and
+ * a `/lib/` exclusion. `include` selects the helper homes to compare;
+ * `excludeContains` drops paths containing any listed fragment.
+ */
+interface CanonicalHelpersSingleHomeOptions {
+    /** Globs of helper-home files to scan for duplicate exports. Default `['apps/web/src/**\/*.utils.ts']`. */
+    readonly include?: readonly string[];
+    /** Drop any matched path containing one of these fragments. Default `['/lib/']`. */
+    readonly excludeContains?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Pure helpers must live in one canonical home. When the helper-home pattern is
+ * adopted, a duplicate exported helper name (the same symbol exported from 2+
+ * different home files) is flagged so the helper stays consolidated. Strict, no
+ * baseline.
+ */
+declare function createCanonicalHelpersSingleHomeRule(options?: CanonicalHelpersSingleHomeOptions): IMetaRule;
+
+/**
+ * Options for {@link createFileSizeRatchetRule}.
+ *
+ * This single factory subsumes BOTH of nightcore's file-size ratchet rules —
+ * `web-file-size-ratchet` (apps/web/src, .ts+.tsx) and `engine-file-size-ratchet`
+ * (packages/engine/src, .ts) — because they were byte-identical logic differing
+ * only in their scanned roots, extensions and exclusions. A consumer creates one
+ * instance per capped area. `id` names both the rule and its committed baseline
+ * file (`<baselineDir>/<id>.json`), so give each instance a distinct `id`.
+ */
+interface FileSizeRatchetOptions {
+    /** Rule id AND baseline file basename. Default `'file-size-ratchet'`. */
+    readonly id?: string;
+    /** Source roots to scan. Default `[]` (inert until configured), e.g. `['apps/web/src']`. */
+    readonly roots?: readonly string[];
+    /** File extensions to include. Default `['.ts', '.tsx']`. */
+    readonly extensions?: readonly string[];
+    /** The per-file line cap. Default `400`. */
+    readonly cap?: number;
+    /** A file is excluded if its path contains any of these. Default test/spec/story markers. */
+    readonly excludeContains?: readonly string[];
+    /** A file is excluded if its path starts with any of these (e.g. codegen dirs). Default `[]`. */
+    readonly excludePrefixes?: readonly string[];
+    /** A baseline entry that shrank below `frozen * tightenRatio` must be re-frozen. Default `0.85`. */
+    readonly tightenRatio?: number;
+    /** Where committed baselines live, relative to repo root. Default {@link DEFAULT_BASELINE_DIR}. */
+    readonly baselineDir?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * File-size governance with a one-way ratchet. Today's over-cap offenders are
+ * frozen in a committed baseline; a NEW over-cap file, or a frozen one that
+ * GREW, fails. Legacy files may only shrink; new files may never join. The
+ * baseline additionally SELF-TIGHTENS: an entry whose file is gone, is now at or
+ * below the cap, or shrank far below its frozen value is itself a violation
+ * demanding a baseline update — so paydowns are captured and the frozen debt can
+ * only shrink.
+ *
+ * Measured in raw physical lines (`wc -l` semantics) so the number an author
+ * sees in the editor is the number the gate sees.
+ */
+declare function createFileSizeRatchetRule(options?: FileSizeRatchetOptions): IMetaRule;
+
+/**
+ * Options for {@link createLayerRankRule}.
+ *
+ * De-projected from nightcore, which hardcoded a fixed rank table
+ * (contracts → shared → storage/skills → engine → surfaces) and the `@nightcore`
+ * scope. The `ranks` table, `scope`, and the surface tier are all options.
+ *
+ * `ranks` defaults to `{}`, which makes the rule INERT (no package is ranked, so
+ * nothing is forbidden) until a consumer supplies its own layering — the same
+ * "off until you opt in" discipline the ESLint monorepo rules use.
+ */
+interface LayerRankOptions {
+    /** npm scope of workspace packages. Default `'@nightcore'`. */
+    readonly scope?: string;
+    /** Layer package name → rank. Higher-ranked may import only strictly-lower. Default `{}`. */
+    readonly ranks?: Readonly<Record<string, number>>;
+    /** Path prefix marking a deployable surface. Default `'apps/'`. */
+    readonly surfacePrefix?: string;
+    /** Rank assigned to surface files. Omit to leave surfaces unranked (skipped). */
+    readonly surfaceRank?: number;
+    /** Regex (source) extracting the layer name from a file path. Default `'^packages/([^/]+)/'`. */
+    readonly packageDirPattern?: string;
+    /** Globs of source files to scan. Default packages + apps `src/**` `.ts`/`.tsx`. */
+    readonly sourceGlobs?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Layer ranks encode a fixed dependency direction: a module may import only
+ * STRICTLY-lower-ranked `<scope>` packages; equal (sideways) or higher (upward)
+ * is forbidden. Unranked `<scope>` packages are leaf utilities outside the
+ * documented spine — an import of one is skipped, and a module living in one is
+ * skipped, so the rule never produces a false positive on a package whose tier
+ * is not fixed.
+ */
+declare function createLayerRankRule(options?: LayerRankOptions): IMetaRule;
+
+/**
+ * Options for {@link createNoClonedComponentFoldersRule}.
+ *
+ * De-projected from nightcore, which hardcoded `apps/web/src/components`, the
+ * `ui`/`app` excluded features, and a fixed `ALLOWED_CLONES` allowlist. The
+ * components root, barrel marker, excluded features, allowlist and the
+ * shared-destination hint are all options.
+ */
+interface NoClonedComponentFoldersOptions {
+    /** Root under which `<feature>/<Component>/` folders live. Default `'apps/web/src/components'`. */
+    readonly componentsRoot?: string;
+    /** Barrel file that marks a component folder. Default `'index.ts'`. */
+    readonly barrelFile?: string;
+    /** Feature folders whose contents are not feature components. Default `['ui', 'app']`. */
+    readonly excludedFeatures?: readonly string[];
+    /** Component names allowed to be cloned across features (a shrinking allowlist). Default `[]`. */
+    readonly allowedClones?: readonly string[];
+    /** Where a shared surface should be hoisted, used in the message. Default `'components/ui'`. */
+    readonly sharedDest?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Same-named component folders across features are how sibling drift happens: a
+ * component cloned into a second feature diverges silently. A shared surface
+ * belongs in the shared destination; a genuinely different one deserves a name
+ * that says so. The allowlist freezes today's clone groups and only shrinks —
+ * an allowlist entry with no remaining clone group is itself a violation.
+ */
+declare function createNoClonedComponentFoldersRule(options?: NoClonedComponentFoldersOptions): IMetaRule;
+
+/**
+ * Options for {@link createNoWarnSeverityRule}.
+ *
+ * De-projected from nightcore, which hardcoded `eslint.config.mjs`: the set of
+ * flat-config files to scan is now the `configFiles` option (each is scanned if
+ * it exists), so the rule fits whatever flat-config filename a repo uses.
+ */
+interface NoWarnSeverityOptions {
+    /** Flat-config files to scan; each is read only if present. */
+    readonly configFiles?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Severity is `error` or `off`, never `warn`. Agents iterate by reading CI
+ * failures; a warning is a silent miss an agent will not act on. This scans the
+ * flat-config text (line comments stripped) for any `'warn'` / `"warn"` literal.
+ */
+declare function createNoWarnSeverityRule(options?: NoWarnSeverityOptions): IMetaRule;
+
+/**
+ * Options for {@link createPackageShapeRule}.
+ *
+ * De-projected from nightcore, which hardcoded the `@nightcore` scope, the
+ * `packages/*` vs `apps/*` split, the `src/index.ts` barrel and the `dist/`
+ * output marker. Every anchor is now an option. `libraryGlobs` packages get the
+ * full name + barrel + build-output checks; `appGlobs` packages (deployable
+ * surfaces) get the name check only.
+ */
+interface PackageShapeOptions {
+    /** npm scope every workspace is named under (`<scope>/<dir>`). Default `'@nightcore'`. */
+    readonly scope?: string;
+    /** `package.json` globs for library packages (full checks). Default `['packages/*\/package.json']`. */
+    readonly libraryGlobs?: readonly string[];
+    /** `package.json` globs for app/surface packages (name check only). Default `['apps/*\/package.json']`. */
+    readonly appGlobs?: readonly string[];
+    /** Directory → exact package name overrides for intentionally off-scope packages. Default `{}`. */
+    readonly externalNames?: Readonly<Record<string, string>>;
+    /** Barrel each library package must expose, relative to its dir. Default `'src/index.ts'`. */
+    readonly barrelPath?: string;
+    /** Substring the build-output fields must contain. Default `'dist/'`. */
+    readonly distMarker?: string;
+    /** `package.json` string fields that must point at built output. Default `['main','module','types']`. */
+    readonly distFields?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Package-shape invariant. Every workspace is named `<scope>/<dir>` matching its
+ * folder. Library packages additionally expose a single barrel and point their
+ * `main`/`module`/`types`/`exports` at the built output. App packages are
+ * deployable surfaces — only the name match applies to them.
+ */
+declare function createPackageShapeRule(options?: PackageShapeOptions): IMetaRule;
+
+/**
+ * Options for {@link createTestRunnerSegregationRule}.
+ *
+ * De-projected from nightcore, which hardcoded `bun:test` vs `vitest`, the
+ * `packages/*` + `apps/sidecar` bun set and the `apps/web` + `eslint-plugin`
+ * vitest set. The two runner import specifiers and the dir groups are options.
+ */
+interface TestRunnerSegregationOptions {
+    /** `package.json` globs whose dirs default to the bun runner. Default `['packages/*\/package.json']`. */
+    readonly bunPackageGlobs?: readonly string[];
+    /** Extra bun-runner directories beyond the globbed packages. Default `[]`. */
+    readonly bunExtraDirs?: readonly string[];
+    /** Directories that use the foreign (non-bun) runner. Default `[]`. */
+    readonly vitestDirs?: readonly string[];
+    /** The bun-side runner import specifier. Default `'bun:test'`. */
+    readonly bunRunnerImport?: string;
+    /** The foreign runner import specifier. Default `'vitest'`. */
+    readonly foreignRunnerImport?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * The test runner is segregated by workspace and never mixed within a package.
+ * Bun-side test files must import the bun runner and never the foreign one;
+ * foreign-side test files must never import the bun runner (they may pull the
+ * foreign runner in transitively via shared test-utils, so a direct import is
+ * not required).
+ */
+declare function createTestRunnerSegregationRule(options?: TestRunnerSegregationOptions): IMetaRule;
+
+/**
+ * Options for {@link createTestSiblingEnforcementRule}.
+ *
+ * De-projected from nightcore, which hardcoded `apps/web/src/**\/*.utils.ts` and
+ * the `.utils.test.ts(x)` sibling shape. `include` selects which source files
+ * must be tested; `testExtensions` are the accepted colocated-test suffixes.
+ */
+interface TestSiblingEnforcementOptions {
+    /** Globs of source files that must ship a colocated test. Default `['apps/web/src/**\/*.utils.ts']`. */
+    readonly include?: readonly string[];
+    /** Accepted colocated-test extensions (replace the source `.ts`/`.tsx`). Default `['.test.ts', '.test.tsx']`. */
+    readonly testExtensions?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every source file matched by `include` must have a colocated sibling test.
+ * Modelled on nightcore's `.utils.ts → .utils.test.ts(x)` rule and generalized:
+ * for a matched file, the sibling is the same path with its `.ts`/`.tsx`
+ * extension replaced by each configured test extension. Strict (no baseline) —
+ * the pattern is opt-in via which files match `include`.
+ */
+declare function createTestSiblingEnforcementRule(options?: TestSiblingEnforcementOptions): IMetaRule;
+
+/**
+ * Options for {@link createTestWorkspaceEnrollmentRule}.
+ *
+ * De-projected from nightcore, which hardcoded the `test:node` script name, a
+ * `packages/*` + `apps/sidecar` dir list, and a vitest exclusion set. All are
+ * options.
+ */
+interface TestWorkspaceEnrollmentOptions {
+    /** The root-manifest script that must enumerate every tested package. Default `'test:node'`. */
+    readonly scriptName?: string;
+    /** The root manifest path. Default `'package.json'`. */
+    readonly manifestPath?: string;
+    /** `package.json` globs whose dirs are candidate test workspaces. Default `['packages/*\/package.json']`. */
+    readonly packageGlobs?: readonly string[];
+    /** Extra directories to check beyond the globbed packages. Default `[]`. */
+    readonly extraDirs?: readonly string[];
+    /** Directories tested by a different runner/script (excluded here). Default `[]`. */
+    readonly excludeDirs?: readonly string[];
+    /** Glob suffix (relative to a dir) that detects the presence of tests. Default `'**\/*.test.ts'`. */
+    readonly testGlobSuffix?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * A test workspace that is not enumerated in the aggregate test script runs in
+ * no CI gate. This fails when any candidate package that HAS test files is
+ * missing from the configured `scriptName` command in the root manifest.
+ */
+declare function createTestWorkspaceEnrollmentRule(options?: TestWorkspaceEnrollmentOptions): IMetaRule;
+
+/**
+ * Options for {@link createUiPrimitiveShapeRule}.
+ *
+ * De-projected from nightcore, which hardcoded `apps/web/src/components/ui`, the
+ * `test`/`stories` roles and the `.tsx` extension. All are options.
+ */
+interface UiPrimitiveShapeOptions {
+    /** The primitives root. Default `'apps/web/src/components/ui'`. */
+    readonly uiRoot?: string;
+    /** Barrel file that marks a folder-primitive. Default `'index.ts'`. */
+    readonly barrelFile?: string;
+    /** Proof-of-behavior sibling roles a folder-primitive must ship. Default `['test', 'stories']`. */
+    readonly roles?: readonly string[];
+    /** Extension of primitive and proof files. Default `'.tsx'`. */
+    readonly extension?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * The primitives root is the one folder exempt from folder-per-component: flat
+ * single files are allowed for presentational primitives. But once a primitive
+ * graduates to a folder (its own dir + barrel) it must ship the same
+ * proof-of-behavior siblings as any component: `<Name>.<role><ext>` for each
+ * role. Also flags the hybrid shape: a flat `<Name><ext>` at the root that
+ * already carries a sibling proof file — those belong inside `<Name>/`.
+ */
+declare function createUiPrimitiveShapeRule(options?: UiPrimitiveShapeOptions): IMetaRule;
+
+/**
+ * Options for {@link createWorkspaceGraphParityRule}.
+ *
+ * De-projected from nightcore, which hardcoded the `@nightcore` scope and a
+ * `src` source directory: both are options. All scope-sensitive regexes are
+ * rebuilt from the configured `scope`.
+ */
+interface WorkspaceGraphParityOptions {
+    /** npm scope of workspace packages. Default `'@nightcore'`. */
+    readonly scope?: string;
+    /** `package.json` globs to enforce parity for. Default packages + apps. */
+    readonly packageGlobs?: readonly string[];
+    /** Source directory (relative to each package) to scan for imports. Default `'src'`. */
+    readonly srcDir?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Workspace dependency-graph parity. For each workspace package:
+ *  (a) every `<scope>/<pkg>` imported in the source dir must be declared as a
+ *      `workspace:*` dependency in package.json, and
+ *  (b) its tsconfig.json `references` must mirror exactly those workspace deps.
+ * So a new cross-package edge can never be half-wired (imported but undeclared,
+ * or declared but missing from the TS project graph).
+ */
+declare function createWorkspaceGraphParityRule(options?: WorkspaceGraphParityOptions): IMetaRule;
+
+/** Raw physical line count, `wc -l` semantics (a trailing newline adds no line). */
+declare function countLines(text: string): number;
+
+/**
+ * Every rule factory keyed by its default rule id, for convenient iteration
+ * (e.g. registering all rules, or discovering the catalog). Each value is a
+ * factory callable with no arguments (all options default). The
+ * `file-size-ratchet` factory is keyed once here but is meant to be instantiated
+ * MULTIPLE times, once per capped area, each with its own `id`.
+ *
+ * A `RuleFactory` accepts an optional options object and returns an
+ * {@link IMetaRule}; the concrete options type is per-factory (see each
+ * `create*` export). `as const` preserves each factory's precise type at the
+ * call site while still allowing zero-argument iteration.
+ */
+declare const RULE_FACTORIES: {
+    readonly 'agents-doc-presence': typeof createAgentsDocPresenceRule;
+    readonly 'canonical-helpers-single-home': typeof createCanonicalHelpersSingleHomeRule;
+    readonly 'file-size-ratchet': typeof createFileSizeRatchetRule;
+    readonly 'layer-rank': typeof createLayerRankRule;
+    readonly 'no-cloned-component-folders': typeof createNoClonedComponentFoldersRule;
+    readonly 'no-warn-severity': typeof createNoWarnSeverityRule;
+    readonly 'package-shape': typeof createPackageShapeRule;
+    readonly 'test-runner-segregation': typeof createTestRunnerSegregationRule;
+    readonly 'test-sibling-enforcement': typeof createTestSiblingEnforcementRule;
+    readonly 'test-workspace-enrollment': typeof createTestWorkspaceEnrollmentRule;
+    readonly 'ui-primitive-shape': typeof createUiPrimitiveShapeRule;
+    readonly 'workspace-graph-parity': typeof createWorkspaceGraphParityRule;
+};
+/** The catalog rule ids (keys of {@link RULE_FACTORIES}). */
+declare const RULE_IDS: (keyof typeof RULE_FACTORIES)[];
+/** Instantiate every catalog rule with its default options. */
+declare function createAllRules(): IMetaRule[];
+
+export { type AgentsDocPresenceOptions, type CanonicalHelpersSingleHomeOptions, type FileSizeRatchetOptions, type LayerRankOptions, type NoClonedComponentFoldersOptions, type NoWarnSeverityOptions, type PackageShapeOptions, RULE_FACTORIES, RULE_IDS, type TestRunnerSegregationOptions, type TestSiblingEnforcementOptions, type TestWorkspaceEnrollmentOptions, type UiPrimitiveShapeOptions, type WorkspaceGraphParityOptions, countLines, createAgentsDocPresenceRule, createAllRules, createCanonicalHelpersSingleHomeRule, createFileSizeRatchetRule, createLayerRankRule, createNoClonedComponentFoldersRule, createNoWarnSeverityRule, createPackageShapeRule, createTestRunnerSegregationRule, createTestSiblingEnforcementRule, createTestWorkspaceEnrollmentRule, createUiPrimitiveShapeRule, createWorkspaceGraphParityRule };