oxlint-plugin-boundary-interfaces 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Siekierski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# oxlint-plugin-boundary-interfaces
+
+Enforce architectural boundaries with a per-folder public interface.
+
+**A folder containing an `interface.json` is a bounded context.** Code outside that folder may
+only import the paths the manifest lists; everything else in the folder is internal. A folder with
+no `interface.json` is unrestricted — so you adopt one context at a time.
+
+Generic: no hardcoded directory layout or alias. Import specifiers are resolved with the project's
+`tsconfig.json` `compilerOptions.paths`, plus normal relative resolution.
+
+## The manifest — `interface.json`
+
+```json
+{ "public": ["components/Button.tsx", "values/*", "lib/**"] }
+```
+
+Paths are relative to the folder, without extension.
+
+- exact — `hooks/useGraphConfig`
+- `/*` — one level (`values/source`, not `values/nested/x`)
+- `/**` — any depth
+
+## Rule — `boundary-interfaces/boundary-interfaces`
+
+When a file outside a context imports a path not in that context's `public` list, it reports a
+diagnostic. Same-context imports are never checked. Nested contexts work: the nearest ancestor
+`interface.json` defines the boundary.
+
+### oxlint
+
+```jsonc
+// .oxlintrc.json
+{
+  "jsPlugins": [
+    { "name": "boundary-interfaces", "specifier": "oxlint-plugin-boundary-interfaces" }
+  ],
+  "rules": {
+    "boundary-interfaces/boundary-interfaces": "warn"
+  }
+}
+```
+
+### Options
+
+```jsonc
+["warn", {
+  "manifestName": "interface.json",                 // default
+  "exemptImporters": ["/__tests__/", "/__fixtures__/"] // importer-path substrings exempt from the rule
+}]
+```
+
+## Dead-public check — `boundary-interfaces-check`
+
+Per-file linting can't tell whether a public path is used *anywhere else*. This CLI scans the repo
+and warns for any `public` entry that no other context imports (dead public surface). Exits non-zero
+on findings — wire it into CI / pre-push.
+
+```bash
+boundary-interfaces-check          # scans ./src
+boundary-interfaces-check packages # scans a given root
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "oxlint-plugin-boundary-interfaces",
+  "version": "0.1.0",
+  "description": "oxlint/ESLint plugin: a folder with an interface.json is a bounded context; outsiders may only import the paths it lists.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "boundary-interfaces-check": "src/check.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "oxlint",
+    "eslint",
+    "boundaries",
+    "architecture",
+    "bounded-context",
+    "domain"
+  ],
+  "author": "Adam Siekierski",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AdamSiekierski/oxlint-plugin-boundary-interfaces.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AdamSiekierski/oxlint-plugin-boundary-interfaces/issues"
+  },
+  "homepage": "https://github.com/AdamSiekierski/oxlint-plugin-boundary-interfaces#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/check.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import {
+  findContext,
+  getAliases,
+  isInside,
+  loadJson,
+  resolveSpecifier,
+  stripExt,
+} from './lib.js';
+
+// Repo scan: warn for public interface entries that no *other* context imports.
+// Per-file linting can't see repo-wide usage, so this lives outside the oxlint rule.
+
+const projectRoot = process.cwd();
+const scanRoot = process.argv[2] ? path.resolve(process.argv[2]) : path.join(projectRoot, 'src');
+const manifestName = 'interface.json';
+const aliases = getAliases(projectRoot);
+
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts']);
+// ponytail: regex import scan; misses computed/dynamic specifiers. Fine for static ESM imports.
+const IMPORT_RE =
+  /(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function walk(dir, onFile) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === 'node_modules' || e.name === 'dist' || e.name.startsWith('.')) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walk(full, onFile);
+    else onFile(full);
+  }
+}
+
+const usedByContext = new Map(); // contextRoot -> Set of context-relative paths (no ext)
+const manifests = []; // absolute interface.json paths
+
+walk(scanRoot, (file) => {
+  if (path.basename(file) === manifestName) {
+    manifests.push(file);
+    return;
+  }
+  if (!SOURCE_EXTS.has(path.extname(file))) return;
+
+  const importerDir = path.dirname(file);
+  const src = readFileSync(file, 'utf8');
+  for (const m of src.matchAll(IMPORT_RE)) {
+    const spec = m[1] || m[2];
+    const target = resolveSpecifier(spec, importerDir, projectRoot, aliases);
+    if (!target) continue;
+    const ctx = findContext(target, projectRoot, manifestName);
+    if (!ctx || isInside(file, ctx.root)) continue; // external, ungoverned, or same-context
+    const rel = stripExt(path.relative(ctx.root, target)).split(path.sep).join('/');
+    if (!usedByContext.has(ctx.root)) usedByContext.set(ctx.root, new Set());
+    usedByContext.get(ctx.root).add(rel);
+  }
+});
+
+let problems = 0;
+for (const manifest of manifests) {
+  const root = path.dirname(manifest);
+  const publicList = loadJson(manifest)?.public ?? [];
+  const used = usedByContext.get(root) ?? new Set();
+  const usedArr = [...used];
+
+  for (const entry of publicList) {
+    const clean = entry.replace(/\/(\*\*?|)\s*$/, '');
+    const isGlob = entry.endsWith('/*') || entry.endsWith('/**');
+    const ok = isGlob
+      ? usedArr.some((u) => u === clean || u.startsWith(clean + '/'))
+      : used.has(stripExt(clean));
+    if (!ok) {
+      problems++;
+      console.warn(
+        `${path.relative(projectRoot, manifest)}: public entry '${entry}' is not imported by any other context.`,
+      );
+    }
+  }
+}
+
+if (problems === 0) console.log('boundary-interfaces: all public entries are used.');
+process.exit(problems > 0 ? 1 : 0);

package/src/index.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import {
+  findContext,
+  getAliases,
+  isInside,
+  matchesPublic,
+  resolveSpecifier,
+  stripExt,
+} from './lib.js';
+
+const DEFAULT_EXEMPT = ['/__tests__/', '/__fixtures__/'];
+
+const rule = {
+  meta: {
+    docs: {
+      description:
+        'Disallow importing a bounded context (a folder with interface.json) from outside, unless the path is listed in its public interface.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          manifestName: { type: 'string' },
+          exemptImporters: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const opts = context.options?.[0] ?? {};
+    const manifestName = opts.manifestName ?? 'interface.json';
+    const exempt = opts.exemptImporters ?? DEFAULT_EXEMPT;
+    const projectRoot = context.cwd;
+    const importer = context.physicalFilename || context.filename;
+    const importerNorm = importer.split(path.sep).join('/');
+
+    if (exempt.some((s) => importerNorm.includes(s))) return {};
+
+    const aliases = getAliases(projectRoot);
+    const importerDir = path.dirname(importer);
+
+    function check(node, source) {
+      if (!node || typeof source !== 'string') return;
+      const target = resolveSpecifier(source, importerDir, projectRoot, aliases);
+      if (!target) return;
+      const ctx = findContext(target, projectRoot, manifestName);
+      if (!ctx) return; // not a governed context — gradual rollout
+      if (isInside(importer, ctx.root)) return; // same context
+
+      const rel = path.relative(ctx.root, target);
+      if (matchesPublic(rel, ctx.publicList)) return;
+
+      context.report({
+        node,
+        message: `'${source}' reaches into bounded context '${path.basename(ctx.root)}', but '${stripExt(rel).split(path.sep).join('/')}' is not in its ${manifestName} public list.`,
+      });
+    }
+
+    return {
+      ImportDeclaration(node) {
+        check(node.source, node.source?.value);
+      },
+      ExportNamedDeclaration(node) {
+        if (node.source) check(node.source, node.source.value);
+      },
+      ExportAllDeclaration(node) {
+        check(node.source, node.source?.value);
+      },
+      ImportExpression(node) {
+        if (node.source?.type === 'Literal') check(node.source, node.source.value);
+      },
+    };
+  },
+};
+
+const plugin = {
+  meta: { name: 'boundary-interfaces' },
+  rules: { 'boundary-interfaces': rule },
+};
+
+export default plugin;

package/src/lib.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const jsonCache = new Map();
+const aliasCache = new Map();
+
+/** Tolerant JSON read (handles tsconfig comments + trailing commas). Cached. Returns null on failure. */
+export function loadJson(file) {
+  if (jsonCache.has(file)) return jsonCache.get(file);
+  let result = null;
+  try {
+    const txt = readFileSync(file, 'utf8')
+      // ponytail: naive JSONC strip; swap for a JSON5 parser if a real tsconfig breaks it.
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/(^|[^:"'])\/\/.*$/gm, '$1')
+      .replace(/,(\s*[}\]])/g, '$1');
+    result = JSON.parse(txt);
+  } catch {
+    result = null;
+  }
+  jsonCache.set(file, result);
+  return result;
+}
+
+/** Alias map from the project's tsconfig `compilerOptions.paths`. Cached per project root. */
+export function getAliases(projectRoot) {
+  if (aliasCache.has(projectRoot)) return aliasCache.get(projectRoot);
+  const json = loadJson(path.join(projectRoot, 'tsconfig.json'));
+  const co = json?.compilerOptions ?? {};
+  const baseUrl = co.baseUrl ? path.resolve(projectRoot, co.baseUrl) : projectRoot;
+  const out = [];
+  for (const [key, vals] of Object.entries(co.paths ?? {})) {
+    if (!Array.isArray(vals) || vals.length === 0) continue;
+    out.push({
+      prefix: key.replace(/\*$/, ''),
+      target: path.resolve(baseUrl, vals[0].replace(/\*$/, '')),
+    });
+  }
+  out.sort((a, b) => b.prefix.length - a.prefix.length); // longest prefix wins
+  aliasCache.set(projectRoot, out);
+  return out;
+}
+
+/** Resolve an import specifier to an absolute path, or null for external/bare packages. */
+export function resolveSpecifier(specifier, importerDir, projectRoot, aliases) {
+  if (specifier.startsWith('.')) return path.resolve(importerDir, specifier);
+  for (const { prefix, target } of aliases) {
+    if (specifier === prefix.replace(/\/$/, '')) return target;
+    if (specifier.startsWith(prefix)) return path.resolve(target, specifier.slice(prefix.length));
+  }
+  return null;
+}
+
+export function stripExt(p) {
+  return p.replace(/\.(m|c)?(ts|tsx|js|jsx)$/, '').replace(/\/index$/, '');
+}
+
+/** Walk up from a target file to the nearest ancestor dir holding `manifestName`. */
+export function findContext(targetPath, projectRoot, manifestName) {
+  let dir = path.dirname(targetPath);
+  while (true) {
+    const manifest = path.join(dir, manifestName);
+    if (existsSync(manifest)) {
+      return { root: dir, publicList: loadJson(manifest)?.public ?? [] };
+    }
+    if (dir === projectRoot) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function isInside(file, dir) {
+  const rel = path.relative(dir, file);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/** Does a context-relative path (no extension) match the public allow-list? Supports `/*` and `/**`. */
+export function matchesPublic(relPath, publicList) {
+  const p = stripExt(relPath).split(path.sep).join('/');
+  for (let entry of publicList) {
+    entry = entry.replace(/\/+$/, '');
+    if (entry.endsWith('/**')) {
+      const prefix = entry.slice(0, -3);
+      if (p === prefix || p.startsWith(prefix + '/')) return true;
+    } else if (entry.endsWith('/*')) {
+      const prefix = entry.slice(0, -2);
+      if (p.startsWith(prefix + '/') && !p.slice(prefix.length + 1).includes('/')) return true;
+    } else if (p === entry) {
+      return true;
+    }
+  }
+  return false;
+}