dlinter-ts-react 0.2.0 → 0.3.1

package/README.md

@@ -132,13 +132,21 @@ bun run validate    # typecheck + test
 
 The repo self-hosts its own gate (lefthook: fallow audit + typecheck + test). Contributions follow strict TDD — a rule without a failing test proving it fires is a disabled rule — and conventional commits.
 
-### Releasing
+### Self-governance
+
+This package enforces its own rules on itself. A permanent test (`src/__tests__/self-governance.test.ts`, part of `bun run validate`) lints `src/**` with the universal subset of the shipped rules — strict colocation, folder ownership, pure barrels, exported-variable JSDoc, `max-lines` — plus a layer contract on import direction:
 
-Releases are automated with [release-please](https://github.com/googleapis/release-please): conventional commits on `main` drive the next semver (`fix:` → patch, `feat:` → minor, `feat!:`/`BREAKING CHANGE:` → major). The bot maintains a Release PR with the computed version and CHANGELOG; **merging that PR** cuts the GitHub release and publishes to npm with provenance — after the tarball end-to-end gate passes.
+```
+src/index.ts → src/configs/ → src/plugin.ts → src/rules/     (src/cli/ is a standalone bin)
+```
+
+Every commit and release must pass the same architecture this package sells. Two documented exceptions: rule modules are exported const objects (the ESLint plugin contract requires it), and the package entrypoints (`main`, `bin`) are composition modules, not barrels.
+
+### Releasing
 
-Manual escape hatch: pushing a `v*` tag triggers the same publish pipeline directly.
+Releases are automated with [release-please](https://github.com/googleapis/release-please): conventional commits on `main` drive the next semver (`fix:` → patch, `feat:` → minor, `feat!:`/`BREAKING CHANGE:` → major). The bot maintains a Release PR with the computed version and CHANGELOG; **merging that PR** cuts the GitHub release and publishes to npm — after the tarball end-to-end gate passes.
 
-Requires the `NPM_TOKEN` secret in the repository settings.
+Publishing authenticates via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC): no tokens, nothing to rotate, provenance built in. The trusted publisher is configured in the package settings on npmjs.com, bound to this repository's `release-please.yml` workflow. Emergency escape hatch: publish locally with `npm publish` (2FA OTP applies).
 
 ## Roadmap
 

package/dist/cli/index.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { existsSync, writeFileSync } from "node:fs";
 import path from "node:path";
-//#region src/cli/init.ts
+//#region src/cli/init/init.constants.ts
+/** Default lefthook pre-commit gate scaffolded into consumer projects. */
 const lefthookTemplate = `pre-commit:
   parallel: false
   jobs:
@@ -14,6 +15,8 @@ const lefthookTemplate = `pre-commit:
     - name: test
       run: npm run test
 `;
+//#endregion
+//#region src/cli/init/init.ts
 /**
 * Scaffolds the dlinter pre-commit gate into a consumer project. Existing
 * files are never overwritten — a hand-tuned gate always wins over the template.

package/dist/index.d.mts

@@ -1106,7 +1106,7 @@ interface Directive {
   justification?: string;
 }
 //#endregion
-//#region src/configs/recommended.types.d.ts
+//#region src/configs/recommended/recommended.types.d.ts
 /**
  * Consumer-defined infrastructure edge: which import specifiers and runtime
  * globals count as "infrastructure" that views must never touch directly.
@@ -1130,7 +1130,7 @@ interface RecommendedConfigOptions {
   readonly tsconfigPath?: string;
 }
 //#endregion
-//#region src/configs/recommended.d.ts
+//#region src/configs/recommended/recommended.d.ts
 /**
  * Builds the full governance preset: bundled third-party plugin stack plus
  * every dlinter architecture rule, composed with the glob topology proven in

package/dist/index.mjs

@@ -1,6 +1,5 @@
 import tsParser from "@typescript-eslint/parser";
 import js from "@eslint/js";
-import tsPlugin from "@typescript-eslint/eslint-plugin";
 import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
 import checkFilePlugin from "eslint-plugin-check-file";
 import { createNodeResolver, importX } from "eslint-plugin-import-x";
@@ -11,6 +10,7 @@ import reactHooksPlugin from "eslint-plugin-react-hooks";
 import sonarjsPlugin from "eslint-plugin-sonarjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
 //#region src/configs/dumb-ui.ts
 /**
 * Dumb UI preset: every `.tsx` file is presentational. Side effects live in
@@ -33,9 +33,13 @@ function createDumbUiConfig(plugin) {
 	}];
 }
 //#endregion
-//#region src/rules/composition-only-delivery.ts
+//#region src/rules/composition-only-delivery/composition-only-delivery.constants.ts
+/** Matches every built-in React hook name, including bare `use`. */
 const reactHookNamePattern = "^use(State|Reducer|Effect|LayoutEffect|InsertionEffect|SyncExternalStore|Memo|Callback|Ref|Context|Transition|DeferredValue|ImperativeHandle|DebugValue|Id|Optimistic|ActionState)?$";
+/** Matches module specifiers that resolve to a custom `use-*` hook file. */
 const customHookModulePattern = /(^|\/)use-[^/]+$/u;
+//#endregion
+//#region src/rules/composition-only-delivery/composition-only-delivery.ts
 /**
 * Delivery Layer Rule: delivery files (App.tsx, app/**) compose feature
 * entrypoints — they never orchestrate. No React hooks, no custom hook
@@ -76,13 +80,16 @@ const compositionOnlyDelivery = {
 	}
 };
 //#endregion
-//#region src/rules/folder-ownership.ts
+//#region src/rules/folder-ownership/folder-ownership.constants.ts
+/** Role-file suffixes a split main module may own next to its entrypoint. */
 const roleSuffixes = [
 	".constants.ts",
 	".helpers.ts",
 	".schema.ts",
 	".types.ts"
 ];
+//#endregion
+//#region src/rules/folder-ownership/folder-ownership.ts
 /**
 * Split Module Ownership Rule: when a main module splits into role files
 * (`*.helpers.ts`, `*.types.ts`, `*.constants.ts`, `*.schema.ts`), the whole
@@ -124,8 +131,11 @@ const folderOwnership = {
 	}
 };
 //#endregion
-//#region src/rules/hook-anatomy.ts
+//#region src/rules/hook-anatomy/hook-anatomy.constants.ts
+/** Selector prefix targeting the body of every exported `use*` hook declaration. */
 const hookBlock = "ExportNamedDeclaration > FunctionDeclaration[id.name=/^use[A-Z0-9]/] > BlockStatement";
+//#endregion
+//#region src/rules/hook-anatomy/hook-anatomy.ts
 /**
 * Hook Anatomy Rule: exported hooks follow one ordering — derived state
 * (useMemo) before callbacks (useCallback) before effects (useEffect) — and
@@ -243,8 +253,11 @@ const noInfrastructureInView = {
 	}
 };
 //#endregion
-//#region src/rules/no-view-effects.ts
+//#region src/rules/no-view-effects/no-view-effects.constants.ts
+/** Matches the React effect hooks that are forbidden inside view components. */
 const effectHookPattern = /^use(?:Effect|LayoutEffect)$/u;
+//#endregion
+//#region src/rules/no-view-effects/no-view-effects.ts
 /**
 * Dumb UI Rule: view components (.tsx) must stay presentational. Side effects
 * belong in the colocated `use-*.ts` hook, never in the view itself.
@@ -299,8 +312,11 @@ const pureIndexBarrel = {
 	}
 };
 //#endregion
-//#region src/rules/readonly-props.ts
+//#region src/rules/readonly-props/readonly-props.constants.ts
+/** Selector fragment matching parameters annotated with a bare `*Props` type reference. */
 const propsBoundary = "[typeAnnotation.typeAnnotation.type=\"TSTypeReference\"][typeAnnotation.typeAnnotation.typeName.name=/Props$/]";
+//#endregion
+//#region src/rules/readonly-props/readonly-props.ts
 /**
 * Type Contract Rule: component props are immutable. Parameters use
 * `Readonly<Props>` at the function boundary, and every field of a `*Props`
@@ -366,7 +382,11 @@ const requireExportedVariableJsdoc = {
 	}
 };
 //#endregion
-//#region src/rules/strict-colocation.ts
+//#region src/rules/strict-colocation/strict-colocation.constants.ts
+/**
+* Every check id the rule can enforce; the `checks` option narrows this set
+* for role files that legitimately own a subset of declaration kinds.
+*/
 const allChecks = [
 	"root-variable",
 	"root-helper-function",
@@ -376,13 +396,86 @@ const allChecks = [
 	"inline-type-alias",
 	"zod-import"
 ];
+/** Matches `zod` itself and any `zod/*` subpath import. */
 const zodImportPattern = /^zod(?:\/.*)?$/u;
 //#endregion
+//#region src/rules/strict-colocation/strict-colocation.helpers.ts
+/**
+* Collects every identifier a module exports through specifier statements —
+* `export default App` and `export { App }` — so root function declarations
+* exported that way are recognized as main modules rather than helpers.
+*/
+function collectSpecifierExportedNames(program) {
+	const names = /* @__PURE__ */ new Set();
+	for (const statement of program.body) {
+		if (statement.type === "ExportDefaultDeclaration" && statement.declaration.type === "Identifier") names.add(statement.declaration.name);
+		if (statement.type === "ExportNamedDeclaration" && statement.declaration === null) {
+			for (const specifier of statement.specifiers) if (specifier.local.type === "Identifier") names.add(specifier.local.name);
+		}
+	}
+	return names;
+}
+/**
+* Builds the visitor fragment owned by each check id; the rule merges the
+* fragments for whichever checks its options enable.
+*/
+function createCheckVisitors(context) {
+	return {
+		"root-variable": { "Program > VariableDeclaration": (node) => {
+			context.report({
+				node,
+				messageId: "rootVariable"
+			});
+		} },
+		"root-helper-function": { "Program > FunctionDeclaration": (node) => {
+			if (node.type === "FunctionDeclaration" && node.parent.type === "Program") {
+				const exportedNames = collectSpecifierExportedNames(node.parent);
+				if (node.id !== null && exportedNames.has(node.id.name)) return;
+			}
+			context.report({
+				node,
+				messageId: "rootHelperFunction"
+			});
+		} },
+		"exported-const": { "Program > ExportNamedDeclaration > VariableDeclaration": (node) => {
+			context.report({
+				node,
+				messageId: "exportedConst"
+			});
+		} },
+		"default-arrow-export": { "Program > ExportDefaultDeclaration > ArrowFunctionExpression": (node) => {
+			context.report({
+				node,
+				messageId: "defaultArrowExport"
+			});
+		} },
+		"inline-interface": { TSInterfaceDeclaration: (node) => {
+			context.report({
+				node,
+				messageId: "inlineInterface"
+			});
+		} },
+		"inline-type-alias": { TSTypeAliasDeclaration: (node) => {
+			context.report({
+				node,
+				messageId: "inlineTypeAlias"
+			});
+		} },
+		"zod-import": { ImportDeclaration: (node) => {
+			if (node.type === "ImportDeclaration" && zodImportPattern.test(String(node.source.value))) context.report({
+				node,
+				messageId: "zodImport"
+			});
+		} }
+	};
+}
+//#endregion
 //#region src/plugin.ts
 /**
-* Plugin core shared by every preset: metadata plus the dlinter rule registry.
-* Presets receive this object so config factories never import the package
-* entrypoint back (which would create a module cycle).
+* Plugin core shared by every preset: metadata plus the dlinter rule registry
+* keyed by published rule name. Presets receive this object so config
+* factories never import the package entrypoint back (which would create a
+* module cycle).
 */
 const pluginBase = {
 	meta: {
@@ -423,49 +516,9 @@ const pluginBase = {
 			create(context) {
 				const configuredChecks = context.options[0]?.checks ?? allChecks;
 				const enabled = new Set(configuredChecks);
+				const checkVisitors = createCheckVisitors(context);
 				const visitor = {};
-				if (enabled.has("root-variable")) visitor["Program > VariableDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "rootVariable"
-					});
-				};
-				if (enabled.has("root-helper-function")) visitor["Program > FunctionDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "rootHelperFunction"
-					});
-				};
-				if (enabled.has("exported-const")) visitor["Program > ExportNamedDeclaration > VariableDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "exportedConst"
-					});
-				};
-				if (enabled.has("default-arrow-export")) visitor["Program > ExportDefaultDeclaration > ArrowFunctionExpression"] = (node) => {
-					context.report({
-						node,
-						messageId: "defaultArrowExport"
-					});
-				};
-				if (enabled.has("inline-interface")) visitor["TSInterfaceDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "inlineInterface"
-					});
-				};
-				if (enabled.has("inline-type-alias")) visitor["TSTypeAliasDeclaration"] = (node) => {
-					context.report({
-						node,
-						messageId: "inlineTypeAlias"
-					});
-				};
-				if (enabled.has("zod-import")) visitor["ImportDeclaration"] = (node) => {
-					if (node.type === "ImportDeclaration" && zodImportPattern.test(String(node.source.value))) context.report({
-						node,
-						messageId: "zodImport"
-					});
-				};
+				for (const check of allChecks) if (enabled.has(check)) Object.assign(visitor, checkVisitors[check]);
 				return visitor;
 			}
 		}
@@ -488,8 +541,13 @@ function downgradeRuleSeverities(rules) {
 	}));
 }
 //#endregion
-//#region src/configs/recommended.ts
+//#region src/configs/recommended/recommended.constants.ts
+/**
+* The @typescript-eslint plugin object types its rules more richly than core
+* ESLint's Plugin contract; the runtime shape is compatible.
+*/
 const typescriptPlugin = tsPlugin;
+/** Extensions the import-x node resolver probes when resolving specifiers. */
 const importXExtensions = [
 	".js",
 	".jsx",
@@ -497,15 +555,20 @@ const importXExtensions = [
 	".tsx",
 	".d.ts"
 ];
+/** Globs identifying test files, which stay outside the architecture contract. */
 const productionTestGlobs = [
 	"**/__tests__/**/*.{ts,tsx}",
 	"**/*.test.{ts,tsx}",
 	"src/test/**/*.{ts,tsx}",
 	"test/**/*.{ts,tsx}"
 ];
+/** Globs for repository automation scripts that run under Node. */
 const nodeScriptGlobs = ["scripts/**/*.{js,mjs,cjs}"];
+/** Globs for application source that runs in the browser. */
 const sourceBrowserGlobs = ["src/**/*.{ts,tsx,js,jsx}"];
+/** Files exempt from the public-documentation contract: tests and documented-invalid fixtures. */
 const documentationExemptGlobs = [...productionTestGlobs, "**/*.invalid.{ts,tsx,js,jsx}"];
+/** Files that are not governed main modules: exempt files plus barrels and role files. */
 const governedMainModuleExemptGlobs = [
 	...documentationExemptGlobs,
 	"**/index.ts",
@@ -514,6 +577,7 @@ const governedMainModuleExemptGlobs = [
 	"**/*.schema.ts",
 	"**/*.types.ts"
 ];
+/** AST selector contexts that `jsdoc/require-jsdoc` treats as public documentation surface. */
 const documentationContexts = [
 	"ExportNamedDeclaration > FunctionDeclaration",
 	"ExportNamedDeclaration > TSInterfaceDeclaration",
@@ -522,6 +586,7 @@ const documentationContexts = [
 	"ExportDefaultDeclaration > ArrowFunctionExpression",
 	"ExportDefaultDeclaration > CallExpression > ArrowFunctionExpression"
 ];
+/** Full dlinter rule map at severity "off" — the final reset applied to test files. */
 const allDlinterRulesOff = {
 	"dlinter/composition-only-delivery": "off",
 	"dlinter/folder-ownership": "off",
@@ -533,6 +598,8 @@ const allDlinterRulesOff = {
 	"dlinter/require-exported-variable-jsdoc": "off",
 	"dlinter/strict-colocation": "off"
 };
+//#endregion
+//#region src/configs/recommended/recommended.ts
 /**
 * Builds the full governance preset: bundled third-party plugin stack plus
 * every dlinter architecture rule, composed with the glob topology proven in
@@ -741,7 +808,11 @@ function createRecommendedConfig(options = {}) {
 			files: ["src/**/*.helpers.ts"],
 			ignores: productionTestGlobs,
 			plugins: { dlinter: pluginBase },
-			rules: { "dlinter/strict-colocation": ["error", { checks: ["inline-interface", "inline-type-alias"] }] }
+			rules: { "dlinter/strict-colocation": ["error", { checks: [
+				"root-variable",
+				"inline-interface",
+				"inline-type-alias"
+			] }] }
 		},
 		{
 			files: productionTestGlobs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dlinter-ts-react",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Deterministic architecture governance for TypeScript + React projects: custom ESLint rules, architecture-concept presets, and pre-commit gate scaffolding.",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,7 @@
     }
   },
   "bin": {
-    "dlinter": "./dist/cli/index.mjs"
+    "dlinter": "dist/cli/index.mjs"
   },
   "files": [
     "dist"
@@ -54,6 +54,7 @@
     "typescript": ">=5.0.0 <6.1.0"
   },
   "devDependencies": {
+    "@types/estree": "^1.0.9",
     "@types/node": "^26.1.1",
     "eslint": "^10.6.0",
     "fallow": "^3.3.0",