OneLinersCommand workbench
AI
Back to skills
SKILL.md

Dependency boundary reviewer

An evidence-first workflow to detect architecture boundary violations and accidental coupling.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/dependency-boundary-review/SKILL.md
Claude Code.claude/skills/dependency-boundary-review/SKILL.md
VS Code.github/skills/dependency-boundary-review/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: dependency-boundary-review
description: Finds exact forbidden import edges and concrete cycle witnesses under a supplied architecture policy. Use with a resolved graph and module ownership; keep type-only edges and unresolved dynamic imports explicit.
license: CC-BY-4.0
compatibility: Complete owned Node.js 22.13+ exercises run offline without credentials or dependencies. They do not scan, modify or delete project files.
metadata:
  author: oneliners
  version: "2.0.0"
---

# Dependency boundary reviewer

## Resolve the graph before judging its direction
Collect module ownership, allowed layer/package directions, composition exceptions, public entry points, import edges with provenance and the actual resolver/build configuration. Resolve aliases, re-exports, conditional package exports and generated modules using the project's supported tooling. Separate type-only dependencies from value imports; their architectural coupling and runtime effects are different questions. A filename prefix or a regex search over source is not a complete import resolver.

## Seven-node worked boundary review
The full example supplies seven nodes, eight edges and one unresolved dynamic expression. It analyzes this data only. Save the reviewed block as boundaries-fixture.mjs and run node boundaries-fixture.mjs with Node.js 22.13+; no source tree or packages are loaded.

```js
function reviewLayerGraph(packet) {
  if (!packet || !Array.isArray(packet.nodes) || !Array.isArray(packet.edges) || !Array.isArray(packet.unknownDynamicImports) || !packet.policy) throw new Error("explicit graph and policy required");
  const nodes = new Map(packet.nodes.map((node) => [node.id, node]));
  if (nodes.size !== packet.nodes.length || packet.nodes.some((node) => !Object.hasOwn(packet.policy, node.layer))) throw new Error("duplicate node or unknown layer");
  const violations = [];
  const runtime = new Map(packet.nodes.map((node) => [node.id, []]));
  for (const edge of packet.edges) {
    if (!nodes.has(edge.from) || !nodes.has(edge.to) || !["value", "type"].includes(edge.kind)) throw new Error("unknown endpoint or edge kind");
    const from = nodes.get(edge.from), to = nodes.get(edge.to);
    if (!packet.policy[from.layer].includes(to.layer)) violations.push({ ...edge, reason: from.layer + " may not import " + to.layer });
    if (edge.kind === "value") runtime.get(edge.from).push(edge.to);
  }
  if (packet.unknownDynamicImports.some((edge) => !nodes.has(edge.from))) throw new Error("unknown dynamic import origin");
  const visiting = new Set(), visited = new Set(), stack = [];
  function walk(id) {
    if (visiting.has(id)) return [...stack.slice(stack.indexOf(id)), id];
    if (visited.has(id)) return null;
    visiting.add(id); stack.push(id);
    for (const target of runtime.get(id)) { const found = walk(target); if (found) return found; }
    stack.pop(); visiting.delete(id); visited.add(id);
    return null;
  }
  let cycleWitness = null;
  for (const id of nodes.keys()) { cycleWitness = walk(id); if (cycleWitness) break; }
  return { violations, cycleWitness, unresolvedDynamic: packet.unknownDynamicImports.length, coverage: packet.unknownDynamicImports.length ? "INCOMPLETE_PROVIDED_GRAPH" : "PROVIDED_GRAPH_ONLY" };
}
const packet = {
  "provenance": "supplied synthetic import graph, not parsed from a real repository",
  "policy": {
    "ui": [
      "ui",
      "app",
      "domain"
    ],
    "app": [
      "app",
      "domain"
    ],
    "domain": [
      "domain"
    ],
    "infra": [
      "infra",
      "domain"
    ],
    "composition": [
      "ui",
      "app",
      "domain",
      "infra",
      "composition"
    ]
  },
  "nodes": [
    {
      "id": "ui/page",
      "layer": "ui"
    },
    {
      "id": "ui/types",
      "layer": "ui"
    },
    {
      "id": "app/service",
      "layer": "app"
    },
    {
      "id": "domain/order",
      "layer": "domain"
    },
    {
      "id": "infra/store",
      "layer": "infra"
    },
    {
      "id": "infra/plugin-loader",
      "layer": "infra"
    },
    {
      "id": "composition/root",
      "layer": "composition"
    }
  ],
  "edges": [
    {
      "from": "ui/page",
      "to": "app/service",
      "kind": "value"
    },
    {
      "from": "ui/page",
      "to": "ui/types",
      "kind": "type"
    },
    {
      "from": "app/service",
      "to": "domain/order",
      "kind": "value"
    },
    {
      "from": "app/service",
      "to": "infra/store",
      "kind": "value"
    },
    {
      "from": "domain/order",
      "to": "ui/page",
      "kind": "value"
    },
    {
      "from": "infra/store",
      "to": "domain/order",
      "kind": "value"
    },
    {
      "from": "composition/root",
      "to": "app/service",
      "kind": "value"
    },
    {
      "from": "composition/root",
      "to": "infra/store",
      "kind": "value"
    }
  ],
  "unknownDynamicImports": [
    {
      "from": "infra/plugin-loader",
      "expression": "selectedPluginPath"
    }
  ]
};
console.log(JSON.stringify(reviewLayerGraph(packet), null, 2));
```

## Findings, alternatives and coverage limits
Two policy violations: app/service → infra/store bypasses the declared application→domain-only rule; domain/order → ui/page makes the domain depend on presentation. The rule is this fixture owner's policy, not a universal Node/TypeScript rule. Composition/root → infra/store is allowed by its explicit composition-root exception.

Concrete runtime-edge cycle witness: ui/page → app/service → domain/order → ui/page. This is one deterministic witness, not exhaustive enumeration of all cycles. The ui/page → ui/types edge is type-only: it participates in this owner's layer policy but is excluded from the runtime-edge cycle walk. Do not call every type-only dependency a runtime initialization cycle.

The unresolved selectedPluginPath import means INCOMPLETE_PROVIDED_GRAPH. Removing the two bad edges gives no cycle in the supplied runtime edges, but does not prove the real application or unresolved loader is acyclic. No module was imported, repository parsed or compiler run by this graph exercise.

Smallest proposed alternatives: move the domain-needed contract out of ui/page into the domain contract, preserving callers; inject the storage implementation from composition/root through an application-owned port rather than importing infra/store directly. Check actual interfaces/runtime behavior before implementing those suggestions. Re-run the graph and real build after each separately reviewed edge change. A green typecheck alone is not enforcement of this exact policy.

## Make a finding reproducible
Report source module, resolved target, edge kind, source location when actually available, violated rule, impact and smallest compliant alternative. Keep an allowed control so the rule does not reject every infrastructure import. Distinguish a forbidden edge without a cycle from a real cycle witness; either may require action for different reasons. Test both removal of the violating edge and an unrelated allowed dependency to avoid weakening the policy just to pass the checker.

## Enforce the chosen contract at the right layer
[TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) can help organize build boundaries, but a references list is not this custom import-policy checker. [Node package entry points](https://nodejs.org/api/packages.html#package-entry-points) define supported package interfaces and conditions; not every file in a package is a supported entry point. Do not change package exports or compiler configuration as an incidental review step. Missing runtime/dynamic targets remain unknown until the actual loader/configuration is inspected.

## Handoff and stop conditions
Return explicit policy/version, known and unresolved edges, precise violations, cycle witness scope, allowed controls, proposed port/contract location, integration checks and owner. Do not claim performance, successful import initialization or security isolation from this graph alone. Do not run untrusted package scripts, install a dependency scanner or rewrite module ownership without separate authority. Preserve the current public API and loading behavior while requesting the missing graph evidence.

Real example

Input

Review the supplied graph against its explicit owner policy, including its unresolved dynamic import. Do not claim to have scanned a repository.

{
  "provenance": "supplied synthetic import graph, not parsed from a real repository",
  "policy": {
    "ui": [
      "ui",
      "app",
      "domain"
    ],
    "app": [
      "app",
      "domain"
    ],
    "domain": [
      "domain"
    ],
    "infra": [
      "infra",
      "domain"
    ],
    "composition": [
      "ui",
      "app",
      "domain",
      "infra",
      "composition"
    ]
  },
  "nodes": [
    {
      "id": "ui/page",
      "layer": "ui"
    },
    {
      "id": "ui/types",
      "layer": "ui"
    },
    {
      "id": "app/service",
      "layer": "app"
    },
    {
      "id": "domain/order",
      "layer": "domain"
    },
    {
      "id": "infra/store",
      "layer": "infra"
    },
    {
      "id": "infra/plugin-loader",
      "layer": "infra"
    },
    {
      "id": "composition/root",
      "layer": "composition"
    }
  ],
  "edges": [
    {
      "from": "ui/page",
      "to": "app/service",
      "kind": "value"
    },
    {
      "from": "ui/page",
      "to": "ui/types",
      "kind": "type"
    },
    {
      "from": "app/service",
      "to": "domain/order",
      "kind": "value"
    },
    {
      "from": "app/service",
      "to": "infra/store",
      "kind": "value"
    },
    {
      "from": "domain/order",
      "to": "ui/page",
      "kind": "value"
    },
    {
      "from": "infra/store",
      "to": "domain/order",
      "kind": "value"
    },
    {
      "from": "composition/root",
      "to": "app/service",
      "kind": "value"
    },
    {
      "from": "composition/root",
      "to": "infra/store",
      "kind": "value"
    }
  ],
  "unknownDynamicImports": [
    {
      "from": "infra/plugin-loader",
      "expression": "selectedPluginPath"
    }
  ]
}

Expected result

Two policy violations: app/service → infra/store bypasses the declared application→domain-only rule; domain/order → ui/page makes the domain depend on presentation. The rule is this fixture owner's policy, not a universal Node/TypeScript rule. Composition/root → infra/store is allowed by its explicit composition-root exception.

Concrete runtime-edge cycle witness: ui/page → app/service → domain/order → ui/page. This is one deterministic witness, not exhaustive enumeration of all cycles. The ui/page → ui/types edge is type-only: it participates in this owner's layer policy but is excluded from the runtime-edge cycle walk. Do not call every type-only dependency a runtime initialization cycle.

The unresolved selectedPluginPath import means INCOMPLETE_PROVIDED_GRAPH. Removing the two bad edges gives no cycle in the supplied runtime edges, but does not prove the real application or unresolved loader is acyclic. No module was imported, repository parsed or compiler run by this graph exercise.

Smallest proposed alternatives: move the domain-needed contract out of ui/page into the domain contract, preserving callers; inject the storage implementation from composition/root through an application-owned port rather than importing infra/store directly. Check actual interfaces/runtime behavior before implementing those suggestions. Re-run the graph and real build after each separately reviewed edge change. A green typecheck alone is not enforcement of this exact policy.

Source evidence

Agent Skills specificationofficialTypeScript project referencesofficialNode.js package entry pointsofficial