PostCSS dependency messages: who owns cache invalidation for dir-dependency entries across runners

Short answer

There is no runner-agnostic invalidation contract beyond the message format itself. PostCSS 8 standardizes only the shape of { type: 'dir-dependency', dir, glob } on result.messages; watching, caching, and deciding what counts as a change are entirely the runner's job. Your plugin declares intent; it cannot enforce behavior. In practice, postcss-loader translates dir-dependency into webpack's addContextDependency, which watches directory membership — so a new file matching the directory (not just mtime changes on existing files) should trigger a rebuild. But that semantic is webpack's, not PostCSS's.

Where the boundary actually sits

Think of the message as a hint with an implied contract:

• Plugin side (yours): push the message during processing (your async OnceExit is fine — messages just need to be on the result before the runner reads them). Nothing else.
• Runner side: read result.messages, register each entry with its watcher/cache layer, and re-run the transform when the watched unit changes. For dir-dependency the watched unit is directory membership plus contents, so add/remove/rename must invalidate — otherwise the message type would be indistinguishable from a plain dependency.

Because PostCSS never executes the watching, a runner that ignores dir-dependency (or ignores glob) fails silently — you get stale output with no error. That is the real risk you're identifying, and it's a runner bug/limitation, not something fixable from inside the plugin.

Absolute vs. relative paths

The format docs historically describe dir as a directory path without mandating resolution rules, and runners register it against their own watcher. The safe, de-facto convention is: always emit absolute paths, resolved from result.opts.from (falling back to process.cwd() if from is undefined):

const path = require('path');
const base = result.opts.from ? path.dirname(result.opts.from) : process.cwd();
result.messages.push({
  type: 'dir-dependency',
  dir: path.resolve(base, templatesDir),
  glob: '**/*.html'
});

Relative paths resolve against whatever the runner happens to use as its working directory, which differs between postcss-loader, gulp-postcss, and the PostCSS CLI. Absolute paths remove that variable entirely.

Do you need per-file dependency fallback?

For a webpack/postcss-loader setup on maintained versions: no — context dependencies are handled, and adding hundreds of individual dependency messages adds watcher overhead for no gain. The defensive enumeration is only worth it if you must support runners with known spotty dir-dependency support (some older gulp/grunt wrappers). A pragmatic middle ground: emit the dir-dependency, and document which runners you've verified.

Verify your actual setup in two minutes

Don't trust the matrix — test the runner you ship with:

1. Log the message inside your plugin to confirm dir is absolute.
2. Run webpack in watch mode, then add a new file matching the glob (not just edit an existing one). If a rebuild fires and the new file's content appears, the runner honors directory-membership semantics.
3. Repeat with a rename/delete. If only edits trigger rebuilds, that runner treats it as a file list and you need the per-file fallback for correctness.

One caveat: in one-shot (non-watch) builds there is no cache to invalidate, so none of this matters until a persistent cache or watcher is involved — with webpack's persistent caching, though, the context dependency is exactly what keeps the cache honest across restarts.