@brighterly/lib-fe-codestyle 0.5.2 → 1.0.1

package/dist/invariants/self-test.d.ts

@@ -1,46 +0,0 @@
-/**
- * The generic half of the self-test: prove every rule still fires on a violating fixture
- * and stays quiet on a clean one.
- *
- * This exists because a rule that has silently stopped matching finds nothing — which is
- * indistinguishable from a clean codebase. The scan alone can print PASS while a rule is
- * dead.
- *
- * Only the harness lives here. The FIXTURES map and any repo-specific assertions stay with
- * the app that owns them and arrive through `fixtures` and `extraChecks` — the original
- * imported the app's funnel queries directly, which is exactly the coupling the package
- * boundary removes.
- */
-import type { Rule } from './types.js';
-/**
- * One fixture case. `bad` must produce >=1 finding, `good` must produce none.
- * `excluded: true` asserts the FILE is matched by the rule's own `exclude` list —
- * the case never runs the check; it proves the exclusion glob is right.
- */
-export interface FixtureCase {
-    file: string;
-    bad?: string;
-    good?: string;
-    excluded?: true;
-}
-/** A rule may declare one case or an array (multi-check rules need one `bad` per check). */
-export type Fixture = FixtureCase | FixtureCase[];
-export interface SelfTestInput {
-    rules: Rule[];
-    fixtures: Record<string, Fixture>;
-    /**
-     * Rule ids exempt from the fixture requirement — registry and graph rules that read real
-     * repo files rather than a synthetic source, so a fixture cannot express them.
-     */
-    skip?: string[];
-    /** Repo-specific assertions; each returns failure messages. May be async — the
-     *  domain cases they express usually need to await a rule's own check(). */
-    extraChecks?: (() => string[] | Promise<string[]>)[];
-}
-export interface SelfTestResult {
-    ok: boolean;
-    failures: string[];
-    /** Rule ids that were actually exercised against a fixture. */
-    checked: string[];
-}
-export declare const runSelfTest: (input: SelfTestInput) => Promise<SelfTestResult>;

package/dist/invariants/self-test.js

@@ -1,84 +0,0 @@
-/**
- * The generic half of the self-test: prove every rule still fires on a violating fixture
- * and stays quiet on a clean one.
- *
- * This exists because a rule that has silently stopped matching finds nothing — which is
- * indistinguishable from a clean codebase. The scan alone can print PASS while a rule is
- * dead.
- *
- * Only the harness lives here. The FIXTURES map and any repo-specific assertions stay with
- * the app that owns them and arrive through `fixtures` and `extraChecks` — the original
- * imported the app's funnel queries directly, which is exactly the coupling the package
- * boundary removes.
- */
-import { matchesAny, stripCodeComments } from './util.js';
-/** Run one rule against a synthetic single-file context. */
-const runRule = async (rule, file, source, extra = {}) => {
-    const ctx = {
-        file,
-        source,
-        code: stripCodeComments(source, file),
-        read: () => null,
-        allFiles: [],
-        settings: {},
-        ...extra,
-    };
-    return (await rule.check(ctx)) ?? [];
-};
-export const runSelfTest = async (input) => {
-    const { rules, fixtures, skip = [], extraChecks = [] } = input;
-    const failures = [];
-    const checked = [];
-    for (const rule of rules) {
-        if (skip.includes(rule.id))
-            continue;
-        const declared = fixtures[rule.id];
-        if (!declared) {
-            failures.push(`${rule.id}: no self-test fixture — every rule needs one`);
-            continue;
-        }
-        const cases = Array.isArray(declared) ? declared : [declared];
-        // Declared, not fired: a dead snippet reports once, on its own line. `misplaced`
-        // mutes the two floors — an out-of-scope path already has its own message and
-        // the floors would only tell the author to add cases they already declared.
-        let declaredBad = false;
-        let declaredGood = false;
-        let misplaced = false;
-        for (const fx of cases) {
-            if (fx.excluded) {
-                if (!matchesAny(fx.file, rule.scope))
-                    failures.push(`${rule.id}: ${fx.file} is declared excluded but is not in the rule's scope (${rule.scope.join(', ')}) — the exclusion is doing no work`);
-                if (!rule.exclude || !matchesAny(fx.file, rule.exclude))
-                    failures.push(`${rule.id}: ${fx.file} is declared excluded but the rule's exclude list (${(rule.exclude ?? []).join(', ') || 'none'}) does not match it`);
-                if (fx.bad !== undefined)
-                    failures.push(`${rule.id}: ${fx.file} is excluded — the runner never checks it, so a 'bad' snippet proves nothing; drop it`);
-                continue;
-            }
-            if (!matchesAny(fx.file, rule.scope)) {
-                failures.push(`${rule.id}: fixture path ${fx.file} is outside the rule's own scope (${rule.scope.join(', ')})`);
-                misplaced = true;
-                continue;
-            }
-            if (fx.bad !== undefined) {
-                declaredBad = true;
-                const bad = await runRule(rule, fx.file, fx.bad);
-                if (bad.length === 0)
-                    failures.push(`${rule.id}: violating fixture at ${fx.file} produced no finding — the check is a no-op:\n${fx.bad}`);
-            }
-            if (fx.good !== undefined) {
-                declaredGood = true;
-                const good = await runRule(rule, fx.file, fx.good);
-                if (good.length > 0)
-                    failures.push(`${rule.id}: clean fixture at ${fx.file} produced ${good.length} false positive(s): ${good.map(g => g.message).join('; ')}`);
-            }
-        }
-        if (!misplaced && !declaredGood)
-            failures.push(`${rule.id}: no case proves the rule stays quiet — at least one 'good' snippet is required`);
-        if (!misplaced && !declaredBad)
-            failures.push(`${rule.id}: no case declares a 'bad' snippet — an 'excluded' case never runs the check, and a 'good'-only fixture cannot prove the rule still matches`);
-        checked.push(rule.id);
-    }
-    for (const check of extraChecks)
-        failures.push(...(await check()));
-    return { ok: failures.length === 0, failures, checked };
-};

package/dist/invariants/types.d.ts

@@ -1,222 +0,0 @@
-/**
- * The contracts every rule and every config entry must satisfy.
- *
- * These exist so that extending this directory fails at typecheck instead of
- * failing silently: a rule with a typo'd field, a manifest entry naming a
- * mechanism that has no resolver, a level that is not a real level. Those were
- * all silently ignored while this was plain JavaScript.
- */
-/** `error` counts toward the exit code · `warn` reports · `off` skips entirely. */
-export type Level = 'error' | 'warn' | 'off';
-/**
- * Rule ID: the family letter says where the rule came from.
- *   R — regression: a CLAUDE.md "What NOT to do" scar
- *   B — business:   the funnel-data contract, confirmed by PMM
- *   C — convention: a preference we chose, advisory by default
- *   L — linter:     covered by a built-in ESLint rule, configured elsewhere
- *   E — e2e:        end-to-end test authoring standards
- * IDs are load-bearing (`--rule=`, `invariant-ignore:`, allowlists, levels) —
- * retire one, never recycle it.
- */
-/** App-local ids are bare; shared-pack ids carry the `core/` prefix (`core/R1`). */
-export type RuleId = `${'' | 'core/'}${'R' | 'B' | 'C' | 'L' | 'E'}${number}`;
-/**
- * Meta rules. They police the escape hatch rather than the app, so they have no
- * family letter — but they are addressable exactly like any other rule
- * (`allowlists`, `levels`, `invariant-ignore`), so they belong in the ID space.
- *   IG0 — an `invariant-ignore` with no reason
- *   IG1 — a reference to a rule ID that no longer exists
- *   IG2 — an `invariant-ignore` naming a rule declared `noIgnore`
- */
-export type MetaRuleId = 'IG0' | 'IG1' | 'IG2';
-/** Anything addressable in config or a suppression comment. */
-export type AnyRuleId = RuleId | MetaRuleId;
-/** One violation. `line` is 1-based. */
-export interface Finding {
-    file: string;
-    line: number;
-    message: string;
-    /**
-     * Severity for THIS finding, when it differs from the rest of the rule's.
-     * Omit to inherit the rule's. A `levels` override in config.mts is a ceiling
-     * over this — see resolveFindingLevel in util.mts.
-     */
-    level?: Level;
-}
-/** A finding after the runner has attributed it to a rule and a level. */
-export interface ReportedFinding extends Finding {
-    ruleId: AnyRuleId;
-    level: Level;
-}
-/**
- * Every settings key a shared rule reads, documented for hover. Annotate the app's
- * `settings` const with this to get completion and the per-key contract in the IDE:
- *
- *   export const settings: SharedRuleSettings & Record<string, string> = { ... }
- *
- * All keys are optional: a missing one degrades the rule's MESSAGE (or falls back to
- * the documented default), never its firing.
- */
-export interface SharedRuleSettings {
-    /** `core/R1`/`core/R3` fix messages: how this app names its safe storage wrapper, e.g. 'safeLocalStorage from @helpers/safe-local-storage'. */
-    safeStorageModule?: string;
-    /** `core/R1`: repo-relative path of the wrapper FILE itself — the one place bare storage access belongs, auto-exempted so no app has to allowlist its own wrapper. E.g. 'app/utils/helpers/safe-local-storage.ts'. */
-    safeStorageFile?: string;
-    /** `core/R3` fix message: the guarded parse helper, e.g. 'parseStoredJson() from @helpers/safe-local-storage'. */
-    safeJsonParse?: string;
-    /** `core/C3`: the palette file that legitimately DEFINES colour literals, e.g. 'app/assets/scss/_colors.scss'. */
-    scssTokensFile?: string;
-    /** `core/C2`: root of the UI-kit tree whose component names must not be duplicated. Default 'app/components/UI'. */
-    uiKitRoot?: string;
-    /** `core/C4` fix message: the shared date-format enum, e.g. 'DateFormat from @ts-types/date/enums'. */
-    dateFormatModule?: string;
-    /** `core/C5`: where entity type folders live. Default 'app/types'. */
-    typesRoot?: string;
-    /** `core/C6` fix message: this app's typography source — a mixin in some apps ('the font() mixin from @scss/_mixins.scss'), a component in others ('the AppText component'). */
-    typographySource?: string;
-    /** `core/C7`: which `<script>` attribute order is canonical in this app. Default 'setup-first' (`<script setup lang="ts">`). */
-    scriptAttrOrder?: 'setup-first' | 'lang-first';
-    /** The consumer file whose `invariant-ignore:` strings are self-test FIXTURE DATA, not real suppressions — the engine skips ignore-parsing it entirely, replacing per-file IG0/IG1 allowlist boilerplate. E.g. 'invariants/self-test.mts'. */
-    selfTestFile?: string;
-}
-/** What a rule's `check` receives. */
-export interface RuleContext {
-    /** Repo-relative path of the file under inspection. */
-    file: string;
-    /** Raw file contents. */
-    source: string;
-    /** Same contents with comment bodies blanked, line numbers preserved. */
-    code: string;
-    /** Read any other repo-relative file (cached). Returns null if unreadable. */
-    read: (rel: string) => string | null;
-    /** Every scanned file in the repo minus the `unmaintained` paths — for rules that resolve references. */
-    allFiles: string[];
-    /**
-     * Every scanned file INCLUDING the `unmaintained` paths. Undefined unless the rule declares
-     * `seesUnmaintained` — the exclusion is meant to be invisible to a rule, and this is the one
-     * declared way through it.
-     */
-    scanned?: string[];
-    /**
-     * App-specific paths a SHARED rule needs, supplied by `config.settings`. This is how a
-     * portable rule learns where this app keeps its SCSS tokens or its UI-kit root, without
-     * the rule becoming a factory. The known keys are documented on `SharedRuleSettings`.
-     */
-    settings: Readonly<SharedRuleSettings & Record<string, string>>;
-}
-/** A `once: true` rule reads its own inputs, so it gets no per-file fields. */
-export type OnceRuleContext = Pick<RuleContext, 'read' | 'allFiles' | 'scanned'> & Partial<RuleContext>;
-interface BaseRule {
-    id: RuleId;
-    /** Short description — appears in the report and the README inventory. */
-    title: string;
-    level: Level;
-    /** The silent-failure mode. A rule without a why gets deleted by future-you. */
-    why: string;
-    /** What to do instead. */
-    fix: string;
-    /** Glob patterns this rule applies to. */
-    scope: string[];
-    /** Glob patterns to skip within scope. */
-    exclude?: string[];
-    /**
-     * The rule cannot be suppressed with `invariant-ignore`; a comment naming it is
-     * itself a finding (IG2). For rules whose author is an AI: exceptions are made by
-     * a human in the rulebook (rule + fixture), never by the agent in the file under
-     * check — an AI writes a plausible reason for free.
-     * Honoured by the runner: the suppression lookup skips such rules, and the IG2
-     * block reports the attempt.
-     */
-    noIgnore?: boolean;
-    /** Set when `check` returns a promise, so the runner awaits it. */
-    async?: boolean;
-    /**
-     * Hand this rule `scanned` — every file, the `unmaintained` paths included — where every other
-     * rule gets only `allFiles`. The exclusion exists so rules that model the component contract
-     * never meet a tree that does not follow it; a rule asking a different question may opt out,
-     * and says so here.
-     */
-    seesUnmaintained?: boolean;
-}
-/** Runs once per matching file. */
-export interface FileRule extends BaseRule {
-    once?: false;
-    check: (ctx: RuleContext) => Finding[] | Promise<Finding[]>;
-}
-/**
- * Runs once per invocation if any file in `scope` is in the candidate set, for
- * rules that read several files themselves (registry and graph checks).
- */
-export interface OnceRule extends BaseRule {
-    once: true;
-    check: (ctx: OnceRuleContext) => Finding[] | Promise<Finding[]>;
-}
-/**
- * The two shapes are separate so a per-file rule cannot accidentally be handed a
- * context without `source`, and a `once` rule cannot claim to receive one.
- */
-export type Rule = FileRule | OnceRule;
-/** Per-rule, per-file exemptions. The value is the reason — required. */
-export type Allowlists = Partial<Record<AnyRuleId, Record<string, string>>>;
-/**
- * Severity overrides, keyed by rule ID. The reason is MANDATORY: once four repos share a
- * rule pack, a bare `levels.X = 'off'` is how a shared rule gets silenced invisibly.
- * Read it through `levelOverrideOf` rather than indexing directly.
- */
-export type Levels = Partial<Record<AnyRuleId, {
-    level: Level;
-    reason: string;
-}>>;
-/**
- * Retired rule IDs and why. A numeric gap records only that *something* existed;
- * this records what, so a stale reference gets a useful message instead of
- * "unknown rule". Never delete an entry — that is the point of it.
- */
-export type RetiredRules = Record<string, string>;
-/** Everything rule IG0/IG1 needs, passed in so the check stays pure and testable. */
-export interface DanglingRefInput {
-    /** IDs of rules currently loaded. */
-    live: Set<string>;
-    retired: RetiredRules;
-    allowlists: Allowlists;
-    levels: Levels;
-    /** Every `invariant-ignore` comment found in the scanned set. */
-    ignores: {
-        file: string;
-        line: number;
-        ids: string[];
-    }[];
-    /** Where allowlists/levels live, for the finding location. */
-    configFile?: string;
-    /** Contents of `configFile`, so a stale key can be reported on its own line. */
-    configSource?: string;
-    /** Answers "does this repo-relative file exist?" — enables the allowlist-path staleness check. */
-    pathExists?: (path: string) => boolean;
-}
-/** An invariant a built-in ESLint rule already covers. */
-export interface LinterOwnedRule {
-    id: RuleId;
-    eslintRule: string;
-    level: Level;
-    title: string;
-    why: string;
-}
-/**
- * Areas the validator deliberately does not look at.
- *
- * Not an allowlist: an allowlist exempts one FILE from one RULE, and the file is
- * still part of the funnel model. This removes a whole subtree from the scanned
- * set and a whole funnel from `query.funnels()`, so no rule — present or future —
- * can see it. That is the right shape for a design system in flux, and the wrong
- * shape for anything we intend to keep correct.
- *
- * Every entry carries a reason, and the CLI prints the totals on every run: an
- * exclusion nobody can see is how a validator quietly stops covering the repo.
- */
-export interface Unmaintained {
-    /** Glob patterns dropped from the scanned file set → reason. */
-    paths: Record<string, string>;
-    /** WRAP_STEPS keys hidden from `query.funnels()` → reason. */
-    funnels: Record<string, string>;
-}
-export {};