feat(boundaries): config-driven boundary-violations recipe

[SutuSebastian]

Summary

• New boundaries: [{name, from_glob, to_glob, action?}] config field + boundary_rules table populated by an index-time reconciler from .codemap/config.
• Bundled boundary-violations recipe joins dependencies × boundary_rules via SQLite GLOB; --format sarif / annotations light up via the existing file_path alias.
• Sweeps stale codemap.config.ts references to .codemap/config.{ts,js,json} across docs, agent surfaces, JSDoc, and CLI help. Historical changesets and the intentional legacy-migration mention in src/config.ts are preserved.

Test plan

• bun run check (798 tests + golden scenarios)
• bun src/index.ts query --recipe boundary-violations --json → [] with no boundaries declared
• bun src/index.ts query --recipes-json | jq '.[] | select(.id == \"boundary-violations\")'
• bun test src/application/boundary-rules.test.ts src/config.test.ts

Notes

• Schema bump 8 → 9; boundary_rules is config-derived (in dropAll) so the next index pass re-fills it. No migration required.
• action field is optional in the user-facing config (Zod) and filled to "deny" by the resolver — keeps defineConfig({ boundaries: [{name, from_glob, to_glob}] }) ergonomic.
• v1 only honours 'deny'; 'allow' reserves the slot for future whitelist semantics. CHECK constraint pins the column.

Summary by CodeRabbit

Release Notes

• New Features

  • Introduced architecture-boundary rules to detect forbidden dependency edges. Configure rules in your project config with glob patterns, then run codemap query --recipe boundary-violations to identify violations. Supports SARIF and GitHub annotations output.

• Documentation

  • Updated configuration file path references and added boundary-violations recipe documentation with setup examples.

[changeset-bot]

🦋 Changeset detected

Latest commit: db92aa7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stainless-code/codemap	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@SutuSebastian has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 40 minutes and 24 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ce6f65d5-4343-4568-b448-0aa15db686fd

📥 Commits

Reviewing files that changed from the base of the PR and between d3407b0 and db92aa7.

📒 Files selected for processing (7)

• docs/architecture.md
• docs/plans/c9-plugin-layer.md
• src/api.ts
• src/application/boundary-rules.test.ts
• src/application/run-index.ts
• src/db.ts
• templates/recipes/boundary-violations.md

📝 Walkthrough

Walkthrough

CodeMap now supports config-driven architecture boundary rules. The feature adds a boundaries configuration array to .codemap/config.ts, creates a boundary_rules database table reconciled on each index pass, and introduces a boundary-violations recipe that joins dependencies against these rules using SQLite GLOB matching to detect forbidden import edges.

Changes

Architecture Boundary Rules

Layer / File(s)	Summary
Configuration Schema src/config.ts, src/config.test.ts	Added optional boundaries array (Zod-validated) with name, from_glob, to_glob, and action ("deny" or "allow"; defaults to "deny"). ResolvedCodemapConfig gains boundaries property. Tests verify defaulting and validation behavior.
Database Schema & Reconciliation src/db.ts	Schema version bumped 8→9. New boundary_rules table with columns name (PK), from_glob, to_glob, action (CHECK constraint). Exported reconcileBoundaryRules(db, rules) clears and repopulates the table; dropAll() now drops boundary_rules.
Runtime Access & Index Integration src/runtime.ts, src/application/run-index.ts	New getBoundaryRules() accessor exposes config boundaries. runCodemapIndex calls reconcileBoundaryRules() at the start of each index pass (after FTS5 handling), before branching into full/files/incremental modes.
Query Recipe & SQL templates/recipes/boundary-violations.{sql,md}	New SQL template joins dependencies to boundary_rules on action = 'deny' using GLOB predicates for from_glob and to_glob, returning path pairs and rule name. Markdown doc covers config shape, CLI invocation, SARIF/annotations output, and v1 scope/exclusions.
Boundary Rules Tests src/application/boundary-rules.test.ts	Test suite (150+ lines) verifies: table starts empty, reconciliation inserts rows, reconciliation is idempotent, action CHECK constraint, and boundary-violations query correctly joins and filters on GLOB match.
Configuration Path Standardization src/api.ts, src/cli/bootstrap-codemap.ts, src/cli/cmd-mcp.ts, src/application/audit-engine.ts, docs/*, templates/*, .agents/*, README.md	Updated config file path references throughout from codemap.config.ts/.json to .codemap/config.ts/.json; also updated roadmap to remove "Boundary violations" backlog item (now implemented) and corrected config path references in FTS5 and audit documentation.
Example Configuration & Documentation codemap.config.example.json, docs/architecture.md, docs/glossary.md, docs/roadmap.md, .agents/rules/codemap.md, .agents/skills/codemap/SKILL.md, .changeset/boundary-violations.md	Updated example config with a boundaries entry; documented boundary-rules schema, reconciliation behavior, SARIF formatting, and recipe usage in architecture and glossary; removed boundary-violations from backlog; updated CLI reference and skill documentation.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant ConfigResolver
    participant IndexEngine
    participant Database
    participant QueryEngine

    User->>CLI: codemap index
    CLI->>ConfigResolver: resolveCodemapConfig()
    ConfigResolver->>ConfigResolver: validate & default boundaries (action="deny")
    ConfigResolver-->>CLI: resolved config with boundaries[]

    CLI->>IndexEngine: runCodemapIndex(config)
    IndexEngine->>Database: reconcileBoundaryRules(db, config.boundaries)
    Database->>Database: DROP & INSERT into boundary_rules
    Database-->>IndexEngine: rules reconciled

    IndexEngine->>IndexEngine: index files & dependencies
    IndexEngine-->>CLI: indexing complete

    User->>CLI: codemap query --recipe boundary-violations --format sarif
    CLI->>QueryEngine: execute boundary-violations.sql
    QueryEngine->>Database: SELECT from dependencies JOIN boundary_rules ON GLOB(from_glob, from_path) AND GLOB(to_glob, to_path)
    Database-->>QueryEngine: matching violation rows
    QueryEngine->>QueryEngine: format as SARIF (from_path as location, rule_name in output)
    QueryEngine-->>CLI: SARIF report
    CLI-->>User: boundary violations output

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• stainless-code/codemap#23: Modifies src/application/run-index.ts and src/db.ts similarly; both PRs adjust the index engine and database schema/handling.
• stainless-code/codemap#15: Touches the same core files (src/application/run-index.ts, src/db.ts); related changes to indexing and database infrastructure.

Suggested labels

enhancement, documentation

Poem

🐰 Boundaries drawn with careful GLOB,
Config rules that block and throb,
Dependencies checked at every pass,
Violations found—violations amassed!
A recipe to keep code neat,
Architecture now complete! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(boundaries): config-driven boundary-violations recipe' clearly and concisely summarizes the main change: a new feature adding boundary-driven violation detection via configuration.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/boundary-violations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/architecture.md (1)

184-184: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Schema version not updated to 9.

This line still reads **8** but the PR bumps SCHEMA_VERSION to 9. The boundary_rules section was added just below, but the version header was missed. As per coding guidelines, documentation files must be kept up-to-date with code changes.

📝 Proposed fix

-Current schema version: **8** — see [Schema Versioning](`#schema-versioning`) for details.
+Current schema version: **9** — see [Schema Versioning](`#schema-versioning`) for details.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/architecture.md` at line 184, The docs show the schema version as **8**
but the code bump changed SCHEMA_VERSION to 9; update the displayed version
number in the architecture.md header from 8 to 9 and ensure the new
boundary_rules section is referenced in the Schema Versioning description so the
docs match the SCHEMA_VERSION constant and recent schema changes.

🧹 Nitpick comments (1)

src/db.ts (1)

364-375: ⚡ Quick win

Make reconcileBoundaryRules atomic.

If an insert fails after Line 368 (for example, duplicate name), boundary_rules can be left partially rebuilt. Wrapping this in a savepoint keeps the table all-or-nothing.

💡 Proposed change

 export function reconcileBoundaryRules(
   db: CodemapDatabase,
   rules: ReadonlyArray<BoundaryRuleRow>,
 ) {
-  db.run("DELETE FROM boundary_rules");
-  if (rules.length === 0) return;
-  for (const rule of rules) {
-    db.run(
-      "INSERT INTO boundary_rules (name, from_glob, to_glob, action) VALUES (?, ?, ?, ?)",
-      [rule.name, rule.from_glob, rule.to_glob, rule.action],
-    );
-  }
+  db.run("SAVEPOINT reconcile_boundary_rules");
+  try {
+    db.run("DELETE FROM boundary_rules");
+    for (const rule of rules) {
+      db.run(
+        "INSERT INTO boundary_rules (name, from_glob, to_glob, action) VALUES (?, ?, ?, ?)",
+        [rule.name, rule.from_glob, rule.to_glob, rule.action],
+      );
+    }
+    db.run("RELEASE SAVEPOINT reconcile_boundary_rules");
+  } catch (error) {
+    db.run("ROLLBACK TO SAVEPOINT reconcile_boundary_rules");
+    db.run("RELEASE SAVEPOINT reconcile_boundary_rules");
+    throw error;
+  }
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/db.ts` around lines 364 - 375, reconcileBoundaryRules currently deletes
all rows and then inserts new ones without transactional protection; wrap the
delete-and-insert sequence in a transaction/savepoint so the update is atomic:
begin a transaction (or SAVEPOINT), execute the DELETE and all INSERTs inside a
try block, and on success COMMIT (or RELEASE SAVEPOINT); on any error ROLLBACK
(or ROLLBACK TO SAVEPOINT) and rethrow or return the error. Update the function
reconcileBoundaryRules to use
db.run("BEGIN")/db.run("COMMIT")/db.run("ROLLBACK") or equivalent transaction
API around the existing db.run calls so the table is not left partially rebuilt.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/plans/c9-plugin-layer.md`:
- Line 30: Update the doc sentence that currently references
`.codemap/config.ts` and `plugins: [...]` to use broader, consistent terminology
that reflects supported config variants; replace the explicit
`.codemap/config.ts` mention with a canonical form such as
`.codemap/config.{ts,js,json}` or "`.codemap/config.*`" (and keep the `plugins:
[...]` example) so the documentation matches the new config surface and uses
consistent wording across docs.

In `@src/api.ts`:
- Around line 34-35: Update the public API JSDoc for the configFile property in
src/api.ts to explicitly list .js alongside .ts and .json (e.g.,
`.codemap/config.{ts,js,json}`) so callers know JS config files are supported;
modify the comment block that documents the configFile and config properties
(look for the JSDoc referencing "configFile" and "config") to include .js in the
supported formats and keep the existing phrasing about CLI `--config`.

In `@src/application/run-index.ts`:
- Around line 117-119: The call to reconcileBoundaryRules(db,
getBoundaryRules()) runs before indexFiles(...) which (via indexFiles ->
dropAll(...) -> db.dropTable('boundary_rules')) wipes the reconciled table; move
the reconcileBoundaryRules call to after the full rebuild completes by invoking
reconcileBoundaryRules(db, getBoundaryRules()) only after indexFiles(db, files,
true, ...) returns so the reconciled boundary_rules data is not dropped by
dropAll; update the call site in run-index.ts accordingly.

In `@templates/recipes/boundary-violations.md`:
- Line 45: Update the line in templates/recipes/boundary-violations.md that
claims "src/ui/* matches one level only": replace it with a clarification that
SQLite GLOB's `*` crosses `/` boundaries so `src/ui/*` will match files at any
depth (e.g. `src/ui/components/Button.tsx`), and add the recommended pattern to
match a single path segment such as `src/ui/[^/]*`; also remove the incorrect
parenthetical about "no `**` recursion" or reword it to state that GLOB has no
special `**` semantics and depth must be controlled with explicit character
classes or segment patterns.

---

Outside diff comments:
In `@docs/architecture.md`:
- Line 184: The docs show the schema version as **8** but the code bump changed
SCHEMA_VERSION to 9; update the displayed version number in the architecture.md
header from 8 to 9 and ensure the new boundary_rules section is referenced in
the Schema Versioning description so the docs match the SCHEMA_VERSION constant
and recent schema changes.

---

Nitpick comments:
In `@src/db.ts`:
- Around line 364-375: reconcileBoundaryRules currently deletes all rows and
then inserts new ones without transactional protection; wrap the
delete-and-insert sequence in a transaction/savepoint so the update is atomic:
begin a transaction (or SAVEPOINT), execute the DELETE and all INSERTs inside a
try block, and on success COMMIT (or RELEASE SAVEPOINT); on any error ROLLBACK
(or ROLLBACK TO SAVEPOINT) and rethrow or return the error. Update the function
reconcileBoundaryRules to use
db.run("BEGIN")/db.run("COMMIT")/db.run("ROLLBACK") or equivalent transaction
API around the existing db.run calls so the table is not left partially rebuilt.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 12311da2-33fb-4bb9-af68-44275652c1a7

📥 Commits

Reviewing files that changed from the base of the PR and between edee493 and d3407b0.

📒 Files selected for processing (25)

• .agents/rules/codemap.md
• .agents/skills/codemap/SKILL.md
• .changeset/boundary-violations.md
• README.md
• codemap.config.example.json
• docs/architecture.md
• docs/glossary.md
• docs/plans/c9-plugin-layer.md
• docs/roadmap.md
• src/api.ts
• src/application/audit-engine.ts
• src/application/boundary-rules.test.ts
• src/application/run-index.ts
• src/cli/bootstrap-codemap.ts
• src/cli/cmd-mcp.ts
• src/config.test.ts
• src/config.ts
• src/db.ts
• src/runtime.ts
• templates/agents/rules/codemap.md
• templates/agents/skills/codemap/SKILL.md
• templates/recipes/boundary-violations.md
• templates/recipes/boundary-violations.sql
• templates/recipes/text-in-deprecated-functions.md
• templates/recipes/text-in-deprecated-functions.sql

[SutuSebastian]

@coderabbitai both fact-checked and applied in db92aa7:

• T5 (outside-diff: docs/architecture.md schema version): ✅ confirmed — SCHEMA_VERSION = 9 in src/db.ts, doc lagged at 8. Bumped.
• T6 (nitpick: reconcileBoundaryRules atomicity): ✅ confirmed real risk — Zod doesn't dedupe name but the schema enforces name TEXT PRIMARY KEY, so a config typo (duplicate name) would throw mid-loop after DELETE already ran, leaving the table partially populated. Wrapped the body in SAVEPOINT reconcile_boundary_rules with ROLLBACK TO on error. Works inside or outside an open transaction, so callers don't need to coordinate. New regression test rolls back on duplicate name — preserves prior good state (atomic) confirms the prior row survives a failed reconcile.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@SutuSebastian: Both fixes look excellent — thank you for the thorough follow-through!

• T5: Good catch on the doc lag — keeping docs/architecture.md in sync with SCHEMA_VERSION avoids confusion when readers cross-reference the schema table docs against the source.
• T6: The SAVEPOINT approach is the right call here. Using a named savepoint (reconcile_boundary_rules) means the atomicity guarantee holds regardless of whether the caller is already inside a transaction, which is a robust design. The regression test covering the "duplicate name → rollback → prior state preserved" scenario is exactly the kind of test that would catch a future refactor accidentally removing the savepoint.

Both changes are well-executed. 🎉

---

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!