Semgrep Architecture Guardrails

Purpose

This note records the Codira-owned Semgrep guardrails introduced for issue #13.

It exists to:

• classify which rules are enforced now
• record the current allowlisted architectural debt explicitly
• define the removal condition for each temporary exception

Rule Status Matrix

Enforced now

• codira.arch.no-storage-import-in-analyzers
• codira.arch.no-registry-import-in-analyzers
• codira.arch.no-backend-import-in-analyzers
• codira.arch.no-sqlite3-in-analyzers
• codira.arch.require-analyzer-capability-declaration
• codira.arch.no-host-ast-in-python-analysis
• codira.arch.no-duckdb-executemany-in-support
• codira.arch.no-duckdb-returning-id-in-support
• codira.arch.no-store-analysis-in-duckdb-full-index-bulk
• codira.arch.no-vector-store-normal-path-in-duckdb-full-index-bulk
• codira.arch.no-core-schema-ddl-import-in-backends
• codira.arch.require-fresh-full-index-embedding-flush
• codira.arch.require-duckdb-full-index-vector-preservation
• codira.arch.no-direct-config-load-in-query-hot-path
• codira.arch.no-mutation-in-mcp
• codira.plugins.no-broad-except-exception
• codira.plugins.require-shared-plugin-json-schema-helper
• codira.det.no-random-without-explicit-seed

Enforced with allowlist

• codira.plugins.no-core-storage-import
• codira.arch.no-sqlite3-outside-allowed-layers
• codira.arch.no-backend-package-import-outside-allowed-layers

Documented future rules

• forbid codira.registry imports outside the current core query/indexing entry points
• forbid direct backend/vector-store/embedding-engine resolution in query hot paths once those paths are fully migrated to the command-scoped runtime context

This broader rule is not enforced yet because the current core implementation still owns transitional responsibilities that would produce noisy findings.

codira.arch.no-direct-config-load-in-query-hot-path

Rationale: Benchmark campaign 20260627T201446 showed repeated effective-config loading and TOML parsing as a measurable ctx overhead. Query hot paths should receive configuration through command-scoped runtime state instead of parsing config files directly.

Removal condition: No removal planned while query commands remain performance-sensitive.

codira.arch.no-mutation-in-mcp

Rationale: The local MCP contract is read-only. Its request handlers must not refresh an index, purge vectors, mutate filesystem state, invoke OS mutation APIs, or launch subprocesses. Configuration-preset generation is intentionally outside this guard because it is an explicit local CLI file-writing workflow, not an MCP request handler.

Removal condition: No removal planned while MCP advertises a read-only contract.

codira.arch.no-store-analysis-in-duckdb-full-index-bulk

Rationale: DuckDB full-index persistence must stay on the backend-native bulk path. Calling the legacy per-file _store_analysis helper from persist_full_index would reintroduce the row-oriented write shape that benchmark profiling identified as the DuckDB full-index bottleneck.

Removal condition: No removal planned while DuckDB remains a supported full-index backend.

codira.arch.no-vector-store-normal-path-in-duckdb-full-index-bulk

Rationale: DuckDB vector-store full-index persistence must replace a complete materialized vector set through a native bulk path. Delegating to the normal store_vectors method would preserve stale rows and reintroduce the slower per-batch write shape in full rebuilds.

Removal condition: No removal planned while DuckDB remains a supported vector-store backend.

Allowlisted Exceptions

The complete current lint, external-Semgrep exception, and rule review is in lint and Semgrep hygiene policy. This document retains the architectural-debt rationale for the three allowlisted rules.

codira.plugins.no-core-storage-import

packages/codira-backend-sqlite/src/codira_backend_sqlite/sqlite_storage.py

Rationale: This package-local seam centralizes SQLite bootstrap/path imports so the production backend no longer imports codira.storage directly.

Removal condition: Remove this allowlist entry when SQLite bootstrap/path ownership no longer delegates to core storage helpers.

packages/codira-backend-duckdb/src/codira_backend_duckdb/repo_storage.py

Rationale: This package-local seam centralizes the production DuckDB backend's remaining generic repository-storage imports for .codira directory and metadata ownership.

Removal condition: Remove this allowlist entry when those storage-path/metadata helpers no longer delegate to core storage helpers.

codira.arch.no-sqlite3-outside-allowed-layers

packages/codira-backend-sqlite/src/codira_backend_sqlite/__init__.py

Rationale: This is the production SQLite backend implementation.

Removal condition: No removal planned while SQLite remains a supported backend.

packages/codira-backend-sqlite/src/codira_backend_sqlite/sqlite_storage.py

Rationale: This module owns SQLite database path resolution, schema bootstrap, and schema refresh behavior for the production SQLite backend.

Removal condition: No removal planned while SQLite remains a supported backend.

packages/codira-backend-sqlite/src/codira_backend_sqlite/sqlite_support.py

Rationale: This module is now the package-owned SQLite persistence helper layer and imports sqlite3 as part of the supported production backend.

Removal condition: No removal planned while SQLite remains a supported backend.

packages/codira-backend-sqlite/src/codira_backend_sqlite/sqlite_artifact_persistence.py

Rationale: This package-local layer persists analyzed artifacts, relationships, and their embedding payloads for the supported SQLite backend.

Removal condition: No removal planned while SQLite remains a supported backend.

packages/codira-backend-sqlite/src/codira_backend_sqlite/sqlite_write_session.py

Rationale: This package-local write-session layer owns SQLite transactions and deferred embedding buffers for the supported production backend.

Removal condition: No removal planned while SQLite remains a supported backend.

packages/codira-vector-store-sqlite/src/codira_vector_store_sqlite/__init__.py

Rationale: This is the production SQLite vector-store implementation and owns the separated .codira/embeddings.db schema.

Removal condition: No removal planned while SQLite remains a supported vector store.

codira.arch.no-backend-package-import-outside-allowed-layers

packages/codira-backend-sqlite/src/codira_backend_sqlite/__init__.py

Rationale: The SQLite backend package now imports its helper implementation from the package-local sqlite_storage and sqlite_support modules.

Removal condition: Remove this allowlist entry when the backend module no longer needs a separate package-local helper module.

packages/codira-backend-sqlite/src/codira_backend_sqlite/sqlite_write_session.py

Rationale: This package-local session implementation imports SQLite persistence helpers to own write-session buffering and transaction behavior.

Removal condition: No removal planned while SQLite remains a supported backend.

DuckDB backend and query modules

Rationale: codira_backend_duckdb.__init__ and duckdb_query_backend are the production DuckDB package seams that import their own package-local backend modules.

Removal condition: Remove these allowlist entries when the DuckDB implementation no longer has separate backend and query modules.

examples/plugins/codira_demo_backend/src/codira_demo_backend/__init__.py

Rationale: The example backend intentionally demonstrates extension by reusing the SQLite backend implementation.

Removal condition: Remove this allowlist entry when the example backend becomes standalone or is replaced.

Local Commands

Repository validation:

uv run python scripts/validate_repo.py

Direct Semgrep scan:

uv run python scripts/run_repo_tool.py semgrep scan --config semgrep/rules --metrics=off --disable-version-check --exclude fixtures .