@venizia/dev-configs 0.4.2 → 0.4.4

package/LICENSE.md

@@ -4,7 +4,7 @@ Ignis is a TypeScript Server Infrastructure framework built on [Hono](https://ho
 
 ## MIT License
 
-Copyright (c) 2025 VENIZIA Ltd. Co.
+Copyright (c) 2025 Venizia Co., Ltd.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -86,12 +86,9 @@ Ignis uses the following open-source libraries. We are grateful to the authors a
 
 ## Acknowledgments
 
-Ignis Framework is inspired by and built upon the work of many open-source projects:
+Ignis Framework is built on the work of open-source projects:
 
 - **[Hono](https://hono.dev/)** by Yusuke Wada - The ultrafast web framework that powers Ignis
-- **[LoopBack 4](https://loopback.io/)** by IBM/StrongLoop - Inspiration for the enterprise architecture patterns
-- **[NestJS](https://nestjs.com/)** by Kamil Mysliwiec - Inspiration for decorator-based controllers
-- **[InversifyJS](https://inversify.io/)** - Inspiration for the IoC container design
 
 We thank all the maintainers and contributors of these projects for their excellent work.
 

package/README.md

@@ -61,7 +61,7 @@ The two options in `compilerOptions` repeat the base on purpose - see
 
 ### Browser and React projects
 
-The presets above target a Bun or Node backend. Code that runs in a browser swaps each one for its
+The presets above target a Bun backend. Code that runs in a browser swaps each one for its
 browser version. A React project swaps it for the React version, which builds on the browser one.
 
 | Tool | Backend | Browser | React |
@@ -169,15 +169,17 @@ booleans. `BrowserOxlintConfigs.create()` and `ReactOxlintConfigs.create()` take
 | `MaxParamsOwnRule` | `venizia/max-params-own` | `build({ max: 5 })` | A function we write takes at most `max` positional parameters. Not counted: an inline callback passed to a call or a JSX prop, a signature a declared type fixes, a constructor whose parameters are all `@inject`. A hook callback counts. |
 | `NoNewErrorRule` | `venizia/no-new-error` | `error` | Throw through `getError` (or an `ApplicationError`), never `new Error(...)` / `Error(...)`. Off in tests. |
 | `NoLeakedRenderRule` | `venizia/no-leaked-render` | `error`, in `reactHouseConfigs` only | A JSX child is drawn with `cond ? <X /> : null`, never `cond && <X />`, which draws `0` when `cond` is `0`. `--fix` rewrites it. `disabled={a && b}` is a value, not a child, and passes. |
-| `ConstClassValuesRule` | `venizia/const-class-values` | off; `build({ namePattern })` | An exported type named like a logic value (`State`, `Status`, `Stage`, `Mode`, `Kind`, `Type` by default) is a const class plus `TConstValue<typeof X>`, not a union of string literals. |
+| `ConstClassValuesRule` | `venizia/const-class-values` | `warn` in both presets; `build({ severity, namePattern })` | V-C-08. A union of string literals in an exported declaration (a type alias, an interface member, a generic constraint, a parameter or return type) is a const class plus `TConstValue<typeof X>`. Not counted: `Pick`, `Omit`, `Extract`, `Exclude`, `Record` arguments and mapped-type keys, and a union with a non-string member. `namePattern` narrows it to exported type aliases whose name matches. Off in tests. |
+| `@typescript-eslint/consistent-type-assertions` | `assertionStyle: never` | `warn` in both presets | V-C-10. `as X`, `as any` and `as unknown as X` warn; `as const` and `satisfies` do not. Off in tests. |
 
-`const-class-values` is registered in the plugin but no preset turns it on: a few IGNIS types still
-break it. Enable it with `[ConstClassValuesRule.NAME]: ConstClassValuesRule.build()`.
+`const-class-values` and the cast rule only warn, so adopting them never fails a lint. Raise one to an error
+with `[ConstClassValuesRule.NAME]: ConstClassValuesRule.build({ severity: 'error' })`. The 5-parameter
+limit (V-C-02) is `venizia/max-params-own`, an error.
 
 ### namingConventionConfigs
 
 `namingConventionConfigs` (type `Linter.Config[]`) sets only `@typescript-eslint/naming-convention`, with
-the 15 LoopBack 4 selectors. It targets `.ts`, `.tsx`, `.mts` and `.cts`, and ignores `dist`, `build`,
+its 15 selectors. It targets `.ts`, `.tsx`, `.mts` and `.cts`, and ignores `dist`, `build`,
 `coverage`, `*.d.ts` and plain JavaScript. ESLint does not report unused disable comments in this
 config, because oxlint owns the other rules.
 
@@ -410,3 +412,16 @@ The root of the chain, with no IGNIS dependency: **dev-configs** -> inversion ->
 - [Source](https://github.com/VENIZIA-AI/ignis/blob/main/packages/dev-configs)
 
 MIT licensed - see [LICENSE.md](./LICENSE.md).
+
+---
+
+<p align="center">
+  <a href="https://venizia.ai">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://venizia.ai/assets/logo-white.svg">
+      <img src="https://venizia.ai/assets/logo.svg" alt="VENIZIA" height="28">
+    </picture>
+  </a>
+  <br>
+  <sub>@venizia/dev-configs is part of IGNIS, built and maintained by <a href="https://venizia.ai">VENIZIA</a>.</sub>
+</p>

package/dist/checks/catalog.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Guards dependency versions against the root `workspaces.catalog`.
+ *
+ * A catalogued dep is referenced as `catalog:` and resolved at publish time by `bun publish`, which
+ * substitutes the real range while packing. `npm publish` does NOT - it ships `catalog:` verbatim
+ * and the manifest is unresolvable for every consumer, which is how 0.1.1-9 / -6 / -4 broke.
+ */
+export interface ICatalogProblem {
+    file: string;
+    message: string;
+}
+export interface ICatalogOptions {
+    /** The repository root: where the root `package.json` and the globs resolve. Default: the current folder. */
+    root?: string;
+    /** Manifests to check, beside `packages/*\/package.json`. A glob relative to the root. */
+    globs?: string[];
+    /**
+     * Files that are not published manifests but carry `dependencies` and `devDependencies` the
+     * release resolves (a VULCAN preset): `catalog:` is allowed in their `peerDependencies`, because a
+     * library preset gives one name one catalog range. A file belongs here when its path starts with
+     * this prefix, for example `presets/`.
+     */
+    presetPrefix?: string;
+    /**
+     * Manifests outside the workspace (a wiki with its own lockfile): `catalog:` does not resolve
+     * there, so a catalogued dependency must be pinned to exactly the catalog's version instead.
+     */
+    pinned?: string[];
+}
+export interface ICatalogReport {
+    problems: ICatalogProblem[];
+    entries: number;
+    referenced: number;
+    /** Set when there is no `workspaces.catalog` to check against. */
+    noCatalog: boolean;
+}
+/** Reads the root catalog and every manifest the options name, and reports everything wrong with their ranges. */
+export declare const findCatalogProblems: (opts?: ICatalogOptions) => Promise<ICatalogReport>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/checks/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/checks/catalog.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,6GAA6G;IAC7G,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IAEnB,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;CACpB;AAcD,kHAAkH;AAClH,eAAO,MAAM,mBAAmB,GAAU,OAAM,eAAoB,KAAG,OAAO,CAAC,cAAc,CAkG5F,CAAC"}

package/dist/checks/catalog.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findCatalogProblems = void 0;
+const bun_1 = require("bun");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** `peerDependencies` are compatibility statements for consumers and stay deliberately looser than the install range. */
+const CATALOGUED_BLOCKS = ['dependencies', 'devDependencies'];
+const DEFAULT_GLOB = 'packages/*/package.json';
+/** Reads the root catalog and every manifest the options name, and reports everything wrong with their ranges. */
+const findCatalogProblems = async (opts = {}) => {
+    const { root = process.cwd(), globs = [], presetPrefix, pinned = [] } = opts;
+    const rootJson = JSON.parse(await Bun.file((0, node_path_1.join)(root, 'package.json')).text());
+    const catalog = rootJson.workspaces?.catalog ?? {};
+    if (Object.keys(catalog).length === 0) {
+        return { problems: [], entries: 0, referenced: 0, noCatalog: true };
+    }
+    const problems = [];
+    const referenced = new Set();
+    const presentPinned = pinned.filter((file) => (0, node_fs_1.existsSync)((0, node_path_1.join)(root, file)));
+    const files = new Set();
+    for (const pattern of [DEFAULT_GLOB, ...globs]) {
+        for await (const file of new bun_1.Glob(pattern).scan(root)) {
+            files.add(file);
+        }
+    }
+    for (const file of [...files, ...presentPinned]) {
+        let json;
+        try {
+            json = JSON.parse(await Bun.file((0, node_path_1.join)(root, file)).text());
+        }
+        catch (error) {
+            problems.push({
+                file,
+                message: `invalid JSON - ${error instanceof Error ? error.message : error}`,
+            });
+            continue;
+        }
+        const isPinned = presentPinned.includes(file);
+        for (const block of CATALOGUED_BLOCKS) {
+            const entriesList = Object.entries(json[block] ?? {});
+            for (const [dep, range] of entriesList) {
+                if (!(dep in catalog)) {
+                    continue;
+                }
+                referenced.add(dep);
+                if (isPinned) {
+                    if (range !== catalog[dep]) {
+                        problems.push({
+                            file,
+                            message: `${block}.${dep} is "${range}" but the catalog pins "${catalog[dep]}" - this project is outside the workspace, so pin exactly that`,
+                        });
+                    }
+                    continue;
+                }
+                if (range === 'catalog:') {
+                    continue;
+                }
+                problems.push({
+                    file,
+                    message: `${block}.${dep} is "${range}" but the catalog owns it - use "catalog:" (catalog pins ${catalog[dep]})`,
+                });
+            }
+        }
+        // A preset is not a published manifest: its markers are resolved by the release, and the library kind gives a
+        // name one catalog range, so a lib's peer takes the same marker as its dev dependency.
+        const isPreset = presetPrefix !== undefined && file.startsWith(presetPrefix);
+        // A peer resolved from the catalog would collapse to the exact install range, losing the looseness that makes it a peer.
+        const peerEntries = Object.entries(json.peerDependencies ?? {});
+        for (const [dep, range] of peerEntries) {
+            if (range !== 'catalog:' || isPreset) {
+                continue;
+            }
+            problems.push({
+                file,
+                message: `peerDependencies.${dep} uses "catalog:" - a peer range must stay hand-authored and looser than the install range`,
+            });
+        }
+    }
+    // A catalog entry nobody references is dead weight that will drift out of date unnoticed.
+    const catalogKeys = Object.keys(catalog);
+    for (const dep of catalogKeys) {
+        if (referenced.has(dep)) {
+            continue;
+        }
+        problems.push({
+            file: 'package.json',
+            message: `catalog entry "${dep}" is referenced by no workspace - drop it`,
+        });
+    }
+    return { problems, entries: catalogKeys.length, referenced: referenced.size, noCatalog: false };
+};
+exports.findCatalogProblems = findCatalogProblems;
+//# sourceMappingURL=catalog.js.map

package/dist/checks/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/checks/catalog.ts"],"names":[],"mappings":"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","sourcesContent":["import { Glob } from 'bun';\nimport { existsSync } from 'node:fs';\nimport { join } from 'node:path';\n\n/**\n * Guards dependency versions against the root `workspaces.catalog`.\n *\n * A catalogued dep is referenced as `catalog:` and resolved at publish time by `bun publish`, which\n * substitutes the real range while packing. `npm publish` does NOT - it ships `catalog:` verbatim\n * and the manifest is unresolvable for every consumer, which is how 0.1.1-9 / -6 / -4 broke.\n */\nexport interface ICatalogProblem {\n  file: string;\n  message: string;\n}\n\nexport interface ICatalogOptions {\n  /** The repository root: where the root `package.json` and the globs resolve. Default: the current folder. */\n  root?: string;\n\n  /** Manifests to check, beside `packages/*\\/package.json`. A glob relative to the root. */\n  globs?: string[];\n\n  /**\n   * Files that are not published manifests but carry `dependencies` and `devDependencies` the\n   * release resolves (a VULCAN preset): `catalog:` is allowed in their `peerDependencies`, because a\n   * library preset gives one name one catalog range. A file belongs here when its path starts with\n   * this prefix, for example `presets/`.\n   */\n  presetPrefix?: string;\n\n  /**\n   * Manifests outside the workspace (a wiki with its own lockfile): `catalog:` does not resolve\n   * there, so a catalogued dependency must be pinned to exactly the catalog's version instead.\n   */\n  pinned?: string[];\n}\n\nexport interface ICatalogReport {\n  problems: ICatalogProblem[];\n  entries: number;\n  referenced: number;\n\n  /** Set when there is no `workspaces.catalog` to check against. */\n  noCatalog: boolean;\n}\n\n/** `peerDependencies` are compatibility statements for consumers and stay deliberately looser than the install range. */\nconst CATALOGUED_BLOCKS = ['dependencies', 'devDependencies'] as const;\n\nconst DEFAULT_GLOB = 'packages/*/package.json';\n\ninterface IManifest {\n  workspaces?: { catalog?: Record<string, string> };\n  dependencies?: Record<string, string>;\n  devDependencies?: Record<string, string>;\n  peerDependencies?: Record<string, string>;\n}\n\n/** Reads the root catalog and every manifest the options name, and reports everything wrong with their ranges. */\nexport const findCatalogProblems = async (opts: ICatalogOptions = {}): Promise<ICatalogReport> => {\n  const { root = process.cwd(), globs = [], presetPrefix, pinned = [] } = opts;\n  const rootJson: IManifest = JSON.parse(await Bun.file(join(root, 'package.json')).text());\n  const catalog: Record<string, string> = rootJson.workspaces?.catalog ?? {};\n\n  if (Object.keys(catalog).length === 0) {\n    return { problems: [], entries: 0, referenced: 0, noCatalog: true };\n  }\n\n  const problems: ICatalogProblem[] = [];\n  const referenced = new Set<string>();\n  const presentPinned = pinned.filter((file) => existsSync(join(root, file)));\n\n  const files = new Set<string>();\n  for (const pattern of [DEFAULT_GLOB, ...globs]) {\n    for await (const file of new Glob(pattern).scan(root)) {\n      files.add(file);\n    }\n  }\n\n  for (const file of [...files, ...presentPinned]) {\n    let json: IManifest;\n\n    try {\n      json = JSON.parse(await Bun.file(join(root, file)).text());\n    } catch (error) {\n      problems.push({\n        file,\n        message: `invalid JSON - ${error instanceof Error ? error.message : error}`,\n      });\n      continue;\n    }\n\n    const isPinned = presentPinned.includes(file);\n\n    for (const block of CATALOGUED_BLOCKS) {\n      const entriesList = Object.entries(json[block] ?? {});\n      for (const [dep, range] of entriesList) {\n        if (!(dep in catalog)) {\n          continue;\n        }\n\n        referenced.add(dep);\n\n        if (isPinned) {\n          if (range !== catalog[dep]) {\n            problems.push({\n              file,\n              message: `${block}.${dep} is \"${range}\" but the catalog pins \"${catalog[dep]}\" - this project is outside the workspace, so pin exactly that`,\n            });\n          }\n\n          continue;\n        }\n\n        if (range === 'catalog:') {\n          continue;\n        }\n\n        problems.push({\n          file,\n          message: `${block}.${dep} is \"${range}\" but the catalog owns it - use \"catalog:\" (catalog pins ${catalog[dep]})`,\n        });\n      }\n    }\n\n    // A preset is not a published manifest: its markers are resolved by the release, and the library kind gives a\n    // name one catalog range, so a lib's peer takes the same marker as its dev dependency.\n    const isPreset = presetPrefix !== undefined && file.startsWith(presetPrefix);\n\n    // A peer resolved from the catalog would collapse to the exact install range, losing the looseness that makes it a peer.\n    const peerEntries = Object.entries(json.peerDependencies ?? {});\n    for (const [dep, range] of peerEntries) {\n      if (range !== 'catalog:' || isPreset) {\n        continue;\n      }\n\n      problems.push({\n        file,\n        message: `peerDependencies.${dep} uses \"catalog:\" - a peer range must stay hand-authored and looser than the install range`,\n      });\n    }\n  }\n\n  // A catalog entry nobody references is dead weight that will drift out of date unnoticed.\n  const catalogKeys = Object.keys(catalog);\n  for (const dep of catalogKeys) {\n    if (referenced.has(dep)) {\n      continue;\n    }\n\n    problems.push({\n      file: 'package.json',\n      message: `catalog entry \"${dep}\" is referenced by no workspace - drop it`,\n    });\n  }\n\n  return { problems, entries: catalogKeys.length, referenced: referenced.size, noCatalog: false };\n};\n"]}

package/dist/checks/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@venizia/dev-configs/checks`: the engines behind `devz check <name>`. Bun-only tooling - never
+ * import it from code a browser runs; the purity gate asserts that no browser-claimed entry reaches it.
+ */
+export * from './catalog';
+export * from './module-cycles';
+export * from './purity/manifest';
+export * from './purity/probe';
+export * from './purity/run';
+export * from './split-report';
+//# sourceMappingURL=index.d.ts.map

package/dist/checks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC"}

package/dist/checks/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `@venizia/dev-configs/checks`: the engines behind `devz check <name>`. Bun-only tooling - never
+ * import it from code a browser runs; the purity gate asserts that no browser-claimed entry reaches it.
+ */
+__exportStar(require("./catalog"), exports);
+__exportStar(require("./module-cycles"), exports);
+__exportStar(require("./purity/manifest"), exports);
+__exportStar(require("./purity/probe"), exports);
+__exportStar(require("./purity/run"), exports);
+__exportStar(require("./split-report"), exports);
+//# sourceMappingURL=index.js.map

package/dist/checks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checks/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;GAGG;AACH,4CAA0B;AAC1B,kDAAgC;AAChC,oDAAkC;AAClC,iDAA+B;AAC/B,+CAA6B;AAC7B,iDAA+B","sourcesContent":["/**\n * `@venizia/dev-configs/checks`: the engines behind `devz check <name>`. Bun-only tooling - never\n * import it from code a browser runs; the purity gate asserts that no browser-claimed entry reaches it.\n */\nexport * from './catalog';\nexport * from './module-cycles';\nexport * from './purity/manifest';\nexport * from './purity/probe';\nexport * from './purity/run';\nexport * from './split-report';\n"]}

package/dist/checks/module-cycles.d.ts

@@ -0,0 +1,22 @@
+export declare class ModuleGraph {
+    private readonly root;
+    private readonly edges;
+    private constructor();
+    static fromDirectory(opts: {
+        dir: string;
+    }): ModuleGraph;
+    /** Strongly connected components with more than one member, as repo-relative paths. */
+    cycles(): string[][];
+    private static walk;
+    private static resolveRelative;
+}
+/**
+ * `devz check module-cycles <dir> [--max <n>]`: prints the cycles of a built ESM directory and
+ * returns 1 when there are more than `max` (no bound by default), 2 on a usage error.
+ */
+export declare const runModuleCycles: (opts: {
+    args: string[];
+    print: (line: string) => void;
+    printError: (line: string) => void;
+}) => number;
+//# sourceMappingURL=module-cycles.d.ts.map

package/dist/checks/module-cycles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-cycles.d.ts","sourceRoot":"","sources":["../../src/checks/module-cycles.ts"],"names":[],"mappings":"AAaA,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFxB,OAAO;IAKP,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW;IAwBxD,uFAAuF;IACvF,MAAM,IAAI,MAAM,EAAE,EAAE;IAkDpB,OAAO,CAAC,MAAM,CAAC,IAAI;IAcnB,OAAO,CAAC,MAAM,CAAC,eAAe;CAa/B;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM;IACpC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC,KAAG,MA8BH,CAAC"}

package/dist/checks/module-cycles.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runModuleCycles = exports.ModuleGraph = void 0;
+/**
+ * Lists import cycles in a built ESM directory. bun turns every member of a
+ * cycle into a lazy initializer, and a barrel `export *` over such a member
+ * can leave its exports undefined. Usage: devz check module-cycles packages/helpers/dist/esm [--max 0]
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+// Only match import/export statements at the start of a line (after optional
+// whitespace), ignoring matches inside comments or string literals.
+const IMPORT_PATTERN = /^\s*(?:import|export)\s[^;]*?from\s+'([^']+)'|^\s*import\s+'([^']+)'/gm;
+class ModuleGraph {
+    constructor(root, edges) {
+        this.root = root;
+        this.edges = edges;
+    }
+    static fromDirectory(opts) {
+        const root = (0, node_path_1.resolve)(opts.dir);
+        const files = ModuleGraph.walk({ dir: root });
+        const edges = new Map();
+        for (const file of files) {
+            const text = (0, node_fs_1.readFileSync)(file, 'utf8');
+            const targets = new Set();
+            const matches = text.matchAll(IMPORT_PATTERN);
+            for (const match of matches) {
+                const target = ModuleGraph.resolveRelative({
+                    from: file,
+                    specifier: match[1] ?? match[2],
+                });
+                if (target) {
+                    targets.add(target);
+                }
+            }
+            edges.set(file, [...targets]);
+        }
+        return new ModuleGraph(root, edges);
+    }
+    /** Strongly connected components with more than one member, as repo-relative paths. */
+    cycles() {
+        let index = 0;
+        const stack = [];
+        const onStack = new Set();
+        const indices = new Map();
+        const lowLinks = new Map();
+        const found = [];
+        const visit = (node) => {
+            indices.set(node, index);
+            lowLinks.set(node, index);
+            index++;
+            stack.push(node);
+            onStack.add(node);
+            const nexts = this.edges.get(node) ?? [];
+            for (const next of nexts) {
+                if (!indices.has(next)) {
+                    visit(next);
+                    lowLinks.set(node, Math.min(lowLinks.get(node), lowLinks.get(next)));
+                }
+                else if (onStack.has(next)) {
+                    lowLinks.set(node, Math.min(lowLinks.get(node), indices.get(next)));
+                }
+            }
+            if (lowLinks.get(node) !== indices.get(node)) {
+                return;
+            }
+            const component = [];
+            let member;
+            do {
+                member = stack.pop();
+                onStack.delete(member);
+                component.push((0, node_path_1.relative)(this.root, member));
+            } while (member !== node);
+            if (component.length > 1) {
+                found.push(component.sort());
+            }
+        };
+        const edgesKeys = this.edges.keys();
+        for (const node of edgesKeys) {
+            if (!indices.has(node)) {
+                visit(node);
+            }
+        }
+        return found;
+    }
+    static walk(opts) {
+        const out = [];
+        const dirEntries = (0, node_fs_1.readdirSync)(opts.dir);
+        for (const name of dirEntries) {
+            const full = (0, node_path_1.join)(opts.dir, name);
+            if ((0, node_fs_1.statSync)(full).isDirectory()) {
+                out.push(...ModuleGraph.walk({ dir: full }));
+            }
+            else if (full.endsWith('.js')) {
+                out.push(full);
+            }
+        }
+        return out;
+    }
+    static resolveRelative(opts) {
+        if (!opts.specifier.startsWith('.')) {
+            return undefined;
+        }
+        const base = (0, node_path_1.resolve)((0, node_path_1.dirname)(opts.from), opts.specifier);
+        const candidates = [base, `${base}.js`, (0, node_path_1.join)(base, 'index.js')];
+        for (const candidate of candidates) {
+            if ((0, node_fs_1.existsSync)(candidate) && (0, node_fs_1.statSync)(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+}
+exports.ModuleGraph = ModuleGraph;
+/**
+ * `devz check module-cycles <dir> [--max <n>]`: prints the cycles of a built ESM directory and
+ * returns 1 when there are more than `max` (no bound by default), 2 on a usage error.
+ */
+const runModuleCycles = (opts) => {
+    const { args, print, printError } = opts;
+    const { positionals, values } = (0, node_util_1.parseArgs)({
+        args,
+        allowPositionals: true,
+        options: { max: { type: 'string' }, dist: { type: 'string' } },
+    });
+    const dir = values.dist ?? positionals[0];
+    const usage = 'usage: devz check module-cycles <built ESM dir> [--max <n>]';
+    if (!dir) {
+        printError(usage);
+        return 2;
+    }
+    let max = Number.POSITIVE_INFINITY;
+    if (values.max !== undefined) {
+        if (!/^\d+$/.test(values.max)) {
+            printError(usage);
+            return 2;
+        }
+        max = Number(values.max);
+    }
+    const cycles = ModuleGraph.fromDirectory({ dir }).cycles();
+    print(`${dir}: ${cycles.length} cycle(s)`);
+    for (const cycle of cycles) {
+        print(`  - ${cycle.join(' <-> ')}`);
+    }
+    return cycles.length > max ? 1 : 0;
+};
+exports.runModuleCycles = runModuleCycles;
+//# sourceMappingURL=module-cycles.js.map

package/dist/checks/module-cycles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-cycles.js","sourceRoot":"","sources":["../../src/checks/module-cycles.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Lists import cycles in a built ESM directory. bun turns every member of a\n * cycle into a lazy initializer, and a barrel `export *` over such a member\n * can leave its exports undefined. Usage: devz check module-cycles packages/helpers/dist/esm [--max 0]\n */\nimport { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';\nimport { dirname, join, relative, resolve } from 'node:path';\nimport { parseArgs } from 'node:util';\n\n// Only match import/export statements at the start of a line (after optional\n// whitespace), ignoring matches inside comments or string literals.\nconst IMPORT_PATTERN = /^\\s*(?:import|export)\\s[^;]*?from\\s+'([^']+)'|^\\s*import\\s+'([^']+)'/gm;\n\nexport class ModuleGraph {\n  private constructor(\n    private readonly root: string,\n    private readonly edges: Map<string, string[]>,\n  ) {}\n\n  static fromDirectory(opts: { dir: string }): ModuleGraph {\n    const root = resolve(opts.dir);\n    const files = ModuleGraph.walk({ dir: root });\n    const edges = new Map<string, string[]>();\n\n    for (const file of files) {\n      const text = readFileSync(file, 'utf8');\n      const targets = new Set<string>();\n      const matches = text.matchAll(IMPORT_PATTERN);\n      for (const match of matches) {\n        const target = ModuleGraph.resolveRelative({\n          from: file,\n          specifier: match[1] ?? match[2],\n        });\n        if (target) {\n          targets.add(target);\n        }\n      }\n      edges.set(file, [...targets]);\n    }\n\n    return new ModuleGraph(root, edges);\n  }\n\n  /** Strongly connected components with more than one member, as repo-relative paths. */\n  cycles(): string[][] {\n    let index = 0;\n    const stack: string[] = [];\n    const onStack = new Set<string>();\n    const indices = new Map<string, number>();\n    const lowLinks = new Map<string, number>();\n    const found: string[][] = [];\n\n    const visit = (node: string): void => {\n      indices.set(node, index);\n      lowLinks.set(node, index);\n      index++;\n      stack.push(node);\n      onStack.add(node);\n\n      const nexts = this.edges.get(node) ?? [];\n      for (const next of nexts) {\n        if (!indices.has(next)) {\n          visit(next);\n          lowLinks.set(node, Math.min(lowLinks.get(node)!, lowLinks.get(next)!));\n        } else if (onStack.has(next)) {\n          lowLinks.set(node, Math.min(lowLinks.get(node)!, indices.get(next)!));\n        }\n      }\n\n      if (lowLinks.get(node) !== indices.get(node)) {\n        return;\n      }\n      const component: string[] = [];\n      let member: string;\n      do {\n        member = stack.pop()!;\n        onStack.delete(member);\n        component.push(relative(this.root, member));\n      } while (member !== node);\n      if (component.length > 1) {\n        found.push(component.sort());\n      }\n    };\n\n    const edgesKeys = this.edges.keys();\n    for (const node of edgesKeys) {\n      if (!indices.has(node)) {\n        visit(node);\n      }\n    }\n\n    return found;\n  }\n\n  private static walk(opts: { dir: string }): string[] {\n    const out: string[] = [];\n    const dirEntries = readdirSync(opts.dir);\n    for (const name of dirEntries) {\n      const full = join(opts.dir, name);\n      if (statSync(full).isDirectory()) {\n        out.push(...ModuleGraph.walk({ dir: full }));\n      } else if (full.endsWith('.js')) {\n        out.push(full);\n      }\n    }\n    return out;\n  }\n\n  private static resolveRelative(opts: { from: string; specifier: string }): string | undefined {\n    if (!opts.specifier.startsWith('.')) {\n      return undefined;\n    }\n    const base = resolve(dirname(opts.from), opts.specifier);\n    const candidates = [base, `${base}.js`, join(base, 'index.js')];\n    for (const candidate of candidates) {\n      if (existsSync(candidate) && statSync(candidate).isFile()) {\n        return candidate;\n      }\n    }\n    return undefined;\n  }\n}\n\n/**\n * `devz check module-cycles <dir> [--max <n>]`: prints the cycles of a built ESM directory and\n * returns 1 when there are more than `max` (no bound by default), 2 on a usage error.\n */\nexport const runModuleCycles = (opts: {\n  args: string[];\n  print: (line: string) => void;\n  printError: (line: string) => void;\n}): number => {\n  const { args, print, printError } = opts;\n  const { positionals, values } = parseArgs({\n    args,\n    allowPositionals: true,\n    options: { max: { type: 'string' }, dist: { type: 'string' } },\n  });\n  const dir = values.dist ?? positionals[0];\n  const usage = 'usage: devz check module-cycles <built ESM dir> [--max <n>]';\n  if (!dir) {\n    printError(usage);\n    return 2;\n  }\n\n  let max = Number.POSITIVE_INFINITY;\n  if (values.max !== undefined) {\n    if (!/^\\d+$/.test(values.max)) {\n      printError(usage);\n      return 2;\n    }\n    max = Number(values.max);\n  }\n\n  const cycles = ModuleGraph.fromDirectory({ dir }).cycles();\n  print(`${dir}: ${cycles.length} cycle(s)`);\n  for (const cycle of cycles) {\n    print(`  - ${cycle.join(' <-> ')}`);\n  }\n\n  return cycles.length > max ? 1 : 0;\n};\n"]}

package/dist/checks/purity/manifest.d.ts

@@ -0,0 +1,94 @@
+export interface IPurityEntry {
+    label: string;
+    package: string;
+    /** Repository-relative path to the built file the `exports` map points at. */
+    entry: string;
+    /**
+     * Specifiers to pass through as `bun build --external`. Only for a third-party dependency whose
+     * OWN packaging is out of this gate's remit - e.g. one that relies on its `package.json` `browser`
+     * field remap, which the downstream app's bundler (Vite, ...) honours and `bun build` does not.
+     * Never for the repository's own source: an external hides that file from the module graph
+     * entirely, so using it on our own code would let a real leak through unseen rather than prove
+     * anything pure. Enforced by {@link assertNoWorkspaceExternal}, not left to this comment alone.
+     */
+    external?: string[];
+    /**
+     * This row is EXPECTED to be impure, so failing is its passing state. Derived from
+     * {@link IPurityClaim.impure} - never authored on a row directly.
+     */
+    expectImpure?: boolean;
+}
+/**
+ * A package whose published entry points carry a browser-purity claim.
+ *
+ * The ROW SET IS NEVER AUTHORED. It is read from the package's own `exports` map, so a sub-path
+ * added to a manifest is probed the moment it is published.
+ */
+export interface IPurityClaim {
+    /** Directory under `packages/`, and the token `devz check purity <token>` filters on. */
+    package: string;
+    /**
+     * Sub-paths (as spelled in `exports`) when the claim covers only PART of the published surface.
+     * Omit it and the whole surface is claimed. Every sub-path named here must still exist in
+     * `exports`; a rename fails the derivation loudly rather than quietly dropping a row.
+     */
+    subpaths?: string[];
+    /** `external` for one sub-path - see {@link IPurityEntry.external}. Keyed as spelled in `exports`. */
+    external?: Record<string, string[]>;
+    /**
+     * Entries that CANNOT be browser-pure, keyed as spelled in `exports`, valued by the conditions
+     * that are impure. The waiver is exact in BOTH directions: a listed entry that turns out to be
+     * pure fails as loudly as an unlisted one that is not. Deriving still owns the ROW SET, so a
+     * sub-path added later is claimed pure by default and has to earn its line here.
+     */
+    impure?: Record<string, string[]>;
+}
+/** What a repository may tune about the engine; everything else is the engine's contract. */
+export interface IPurityOptions {
+    /**
+     * When set, every claimed sub-path must publish its runtime entries below this prefix (for
+     * example `./dist/esm/`): a browser bundler needs an ES module, so a CommonJS-only entry makes
+     * the claim unconsumable. Omit it for a repository that publishes a single build.
+     */
+    esmEntryPrefix?: string;
+    /** Package-name prefix of this repository's own packages; an `external` may never start with it. Default `@venizia/`. */
+    workspaceScope?: string;
+}
+/**
+ * A code-level guard, not just the JSDoc on `external`: it is an escape hatch from this gate, and a
+ * hatch with no lock is one bad edit away from hiding a real leak - `external: ['@venizia/ignis-helpers']`
+ * on a red entry would silently turn it green by removing the exact root-barrel import this gate
+ * exists to catch from the module graph, rather than proving it absent.
+ *
+ * A plain `Error`, not `getError`: the engine runs from the repository root through `devz`, outside
+ * every workspace package, and has no logger to resolve.
+ */
+export declare const assertNoWorkspaceExternal: (manifest: IPurityEntry[], workspaceScope?: string) => IPurityEntry[];
+/**
+ * Exported for the tests, which have to drive a claim that no longer matches its package's
+ * `exports` map - the staleness guard is the whole point of deriving, and it cannot be asserted
+ * through a built manifest, which by construction is never stale.
+ */
+export declare const deriveEntries: (opts: {
+    claim: IPurityClaim;
+    root: string;
+}) => IPurityEntry[];
+/**
+ * A browser claim is only honest if a browser bundler can actually consume the entry. A CommonJS
+ * entry forces every consumer into a workaround, so the claim carries the obligation: every claimed
+ * sub-path must publish its runtime entries below `esmEntryPrefix`. Checked here rather than trusted
+ * to a comment, for the same reason as {@link assertNoWorkspaceExternal} - the failure is otherwise
+ * invisible until someone tries to bundle the package downstream.
+ */
+export declare const assertBrowserEsmEntry: (opts: {
+    claims: IPurityClaim[];
+    root: string;
+    esmEntryPrefix: string;
+}) => IPurityClaim[];
+/** The rows of a whole repository: every claim derived from its package's `exports`, then the guards. */
+export declare const buildManifest: (opts: {
+    claims: IPurityClaim[];
+    root: string;
+    options?: IPurityOptions;
+}) => IPurityEntry[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/checks/purity/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/checks/purity/manifest.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,sGAAsG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,yHAAyH;IACzH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAYD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,YAAY,EAAE,EACxB,iBAAgB,MAAgC,KAC/C,YAAY,EAiBd,CAAC;AAiEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KAAG,YAAY,EA8EvF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM;IAC1C,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;CACxB,KAAG,YAAY,EAiCf,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,aAAa,GAAI,MAAM;IAClC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,KAAG,YAAY,EAWf,CAAC"}