@comity-dev/semgrep-rules 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+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,49 @@
+# @comity-dev/semgrep-rules
+
+## Purpose
+
+Reusable Semgrep rule set for Comity structural source-code patterns. Semgrep is well-suited to **structural patterns** that ESLint cannot express cleanly: class shape, interface structure, method signatures, prohibited implementation patterns.
+
+## Scope
+
+The canonical rule files live under `./rules/` as YAML. The package also exports a loader that produces a single combined Semgrep config suitable for a single `--config` invocation.
+
+## Ownership
+
+Owned by `comity-development`. Consumed by `@comity-dev/validate` which actually invokes the `semgrep` binary.
+
+The rule set targets **runtime** Core Modules and Adapters only. It does NOT apply to Development tooling packages (`comity.layer: "dev-tooling"`), which legitimately use Node APIs (`process.env`, etc.) that the rules forbid for runtime code.
+
+## Public API
+
+```ts
+import {
+  listRuleFiles,
+  loadRule,
+  loadAllRules,
+  buildSemgrepConfig,
+} from "@comity-dev/semgrep-rules";
+```
+
+The `./rules` subpath exposes the raw YAML rule files:
+
+```ts
+import rulePath from "@comity-dev/semgrep-rules/rules/<file>.yaml";
+```
+
+## Relationship to Comity Standards
+
+- `adapters.md` §11 — Adapter contract implementation shape.
+- `errors.md` — error class shape.
+- `modules.md` — module surface shape.
+
+## Development
+
+```bash
+pnpm build
+pnpm test
+```
+
+## Tool availability
+
+The `semgrep` binary is **optional**. When missing, the validator reports `TOOL-UNAVAILABLE` rather than fabricating PASS. Install via `pip install semgrep` or set `SEMGREP_BIN` to an absolute path.

package/dist/build-config.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Builds a single combined Semgrep config file from all canonical rule
+ * files. Semgrep's CLI accepts a single `--config`; the validate engine
+ * writes the combined content to a temp file and invokes semgrep with
+ * that path.
+ */
+export declare function buildSemgrepConfig(): Promise<string>;

package/dist/build-config.js

@@ -0,0 +1,19 @@
+import { readFile } from "node:fs/promises";
+import { listRuleFiles } from "./filesystem.js";
+/**
+ * Builds a single combined Semgrep config file from all canonical rule
+ * files. Semgrep's CLI accepts a single `--config`; the validate engine
+ * writes the combined content to a temp file and invokes semgrep with
+ * that path.
+ */
+export async function buildSemgrepConfig() {
+    const files = await listRuleFiles();
+    const ruleBlocks = [];
+    for (const f of files) {
+        const text = await readFile(f, "utf8");
+        // Strip the top-level `rules:` line; we want just the array entries.
+        const body = text.replace(/^\s*rules:\s*\n/m, "");
+        ruleBlocks.push(body.trimEnd());
+    }
+    return `rules:\n${ruleBlocks.join("\n")}\n`;
+}

package/dist/filesystem.d.ts

@@ -0,0 +1,11 @@
+import { type ParsedSemgrepRule } from "./parse-yaml.js";
+export interface SemgrepRule extends ParsedSemgrepRule {
+    /** The absolute path of the rule file from which this rule was loaded. */
+    file: string;
+}
+/** Returns the canonical rule file paths under `./rules/`. */
+export declare function listRuleFiles(): Promise<string[]>;
+/** Loads and parses a single Semgrep rule file. */
+export declare function loadRule(filePath: string): Promise<SemgrepRule[]>;
+/** Loads every rule in the package and returns them as a flat array. */
+export declare function loadAllRules(): Promise<SemgrepRule[]>;

package/dist/filesystem.js

@@ -0,0 +1,28 @@
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSemgrepYaml } from "./parse-yaml.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const RULES_DIR = join(__dirname, "..", "rules");
+/** Returns the canonical rule file paths under `./rules/`. */
+export async function listRuleFiles() {
+    const entries = await readdir(RULES_DIR);
+    return entries
+        .filter((f) => f.endsWith(".yaml"))
+        .map((f) => join(RULES_DIR, f));
+}
+/** Loads and parses a single Semgrep rule file. */
+export async function loadRule(filePath) {
+    const text = await readFile(filePath, "utf8");
+    return parseSemgrepYaml(text).map((r) => ({ ...r, file: filePath }));
+}
+/** Loads every rule in the package and returns them as a flat array. */
+export async function loadAllRules() {
+    const files = await listRuleFiles();
+    const all = [];
+    for (const f of files) {
+        const rules = await loadRule(f);
+        all.push(...rules);
+    }
+    return all;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { buildSemgrepConfig } from "./build-config.js";
+export { listRuleFiles, loadAllRules, loadRule } from "./filesystem.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { buildSemgrepConfig } from "./build-config.js";
+export { listRuleFiles, loadAllRules, loadRule } from "./filesystem.js";

package/dist/parse-yaml.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal helper for parsing Semgrep YAML rule files.
+ *
+ * The YAML format we target is a strict subset:
+ *   rules:
+ *     - id: <name>
+ *       severity: <level>
+ *       languages: [<lang>]
+ *       message: |
+ *         <text>
+ *       pattern: |
+ *         <pattern>
+ *
+ * We do not use a YAML library because the canonical rule files are
+ * authored by the Development repository and follow a known shape.
+ */
+export interface ParsedSemgrepRule {
+    id: string;
+    severity: string | null;
+    languages: string[] | null;
+    message: string | null;
+    raw: string;
+}
+export declare function parseSemgrepYaml(text: string): ParsedSemgrepRule[];

package/dist/parse-yaml.js

@@ -0,0 +1,36 @@
+/**
+ * Internal helper for parsing Semgrep YAML rule files.
+ *
+ * The YAML format we target is a strict subset:
+ *   rules:
+ *     - id: <name>
+ *       severity: <level>
+ *       languages: [<lang>]
+ *       message: |
+ *         <text>
+ *       pattern: |
+ *         <pattern>
+ *
+ * We do not use a YAML library because the canonical rule files are
+ * authored by the Development repository and follow a known shape.
+ */
+export function parseSemgrepYaml(text) {
+    const ruleBlockRe = /^[ \t]{2}- id:\s*(.+?)\n((?:^(?![ \t]{2}- id:|rules:|---).*\n?)*)/gm;
+    const rules = [];
+    let match;
+    while ((match = ruleBlockRe.exec(text)) !== null) {
+        const id = (match[1] ?? "").trim();
+        const body = match[2] ?? "";
+        const severityMatch = body.match(/^\s*severity:\s*(.+)$/m);
+        const languagesMatch = body.match(/languages:\s*\[(.+?)\]/m);
+        const messageMatch = body.match(/message:\s*\|?\s*\n((?:[ \t]+.+\n?)*)/m);
+        rules.push({
+            id,
+            severity: severityMatch?.[1]?.trim() ?? null,
+            languages: languagesMatch?.[1]?.split(",").map((s) => s.trim()) ?? null,
+            message: messageMatch?.[1]?.trim() ?? null,
+            raw: `  - id: ${id}\n${body}`,
+        });
+    }
+    return rules;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@comity-dev/semgrep-rules",
+  "version": "0.1.0",
+  "description": "Reusable Semgrep rules for Comity structural source-code patterns. Development tooling.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "comity": {
+    "layer": "dev-tooling"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./rules": "./rules/"
+  },
+  "files": [
+    "./dist",
+    "./rules"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/rules/adapter-contract-shape.yaml

@@ -0,0 +1,38 @@
+rules:
+  - id: comity-adapter-must-declare-implements
+    languages: [typescript]
+    severity: ERROR
+    message: |
+      A Technology Adapter MUST `implements` exactly one Core Module contract.
+      The implementing class is the structural binding between the technology
+      and the contract.
+        - adapters.md §11
+        - ADR-007
+    pattern: |
+      class $NAME implements $I {
+        ...
+      }
+    pattern-not: |
+      class $NAME implements $I {
+        constructor(...args) { ... }
+        ...
+      }
+    metadata:
+      category: comity-architecture
+      standard: adapters.md
+      section: 11
+
+  - id: comity-adapter-no-raw-error-throw
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Adapters MAY throw platform errors, but the boundary they expose to Core
+      Modules MUST use Result<T, E>. Throwing raw Error from a Core-facing
+      method breaks the Result contract.
+        - errors.md §6
+    pattern: |
+      throw new Error($MSG);
+    metadata:
+      category: comity-architecture
+      standard: errors.md
+      section: 6

package/rules/composition-shape.yaml

@@ -0,0 +1,42 @@
+rules:
+  - id: comity-no-static-state-in-core
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Core Modules MUST NOT use static class state. Composition owns wiring;
+      static state in Core breaks testability.
+        - architecture-principles.md
+    pattern: |
+      class $NAME {
+        ...
+        static $F: $T = $V;
+        ...
+      }
+    paths:
+      include:
+        - "**/packages/**/src/**/*.ts"
+      exclude:
+        - "**/packages/*/adapters/**"
+        - "**/node_modules/**"
+    metadata:
+      category: comity-architecture
+      standard: architecture-principles.md
+
+  - id: comity-no-singleton-instance
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Comity avoids singletons. Provide composition facades via the kernel's
+      `composition` module instead.
+        - architecture-principles.md
+    pattern: |
+      export const $NAME = new $CLASS(...$ARGS);
+    paths:
+      include:
+        - "**/packages/**/src/index.ts"
+        - "**/packages/**/src/contracts/index.ts"
+      exclude:
+        - "**/node_modules/**"
+    metadata:
+      category: comity-architecture
+      standard: architecture-principles.md

package/rules/core-domain-no-crypto.yaml

@@ -0,0 +1,77 @@
+rules:
+  - id: comity-core-no-process-env
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Core Modules MUST NOT read `process.env` directly — environment access
+      belongs in adapters. Inject configuration via composition facades.
+        - architecture-validation.md §4
+        - configuration.md
+    pattern: process.env[$KEY]
+    paths:
+      include:
+        - "**/packages/**/src/**/*.ts"
+      exclude:
+        - "**/packages/*/adapters/**"
+        - "**/node_modules/**"
+    metadata:
+      category: comity-architecture
+      standard: configuration.md
+
+  - id: comity-core-no-fs
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Core Modules MUST NOT import Node's `fs` API. File system access belongs
+      in adapters.
+        - architecture-validation.md §4
+        - adapters.md §11
+    pattern: import { ... } from "node:fs"
+    paths:
+      include:
+        - "**/packages/**/src/**/*.ts"
+      exclude:
+        - "**/packages/*/adapters/**"
+        - "**/node_modules/**"
+    metadata:
+      category: comity-architecture
+      standard: adapters.md
+      section: 11
+
+  - id: comity-core-no-fs-promises
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Core Modules MUST NOT import `node:fs/promises`. File system access belongs
+      in adapters.
+        - architecture-validation.md §4
+        - adapters.md §11
+    pattern: import { ... } from "node:fs/promises"
+    paths:
+      include:
+        - "**/packages/**/src/**/*.ts"
+      exclude:
+        - "**/packages/*/adapters/**"
+        - "**/node_modules/**"
+    metadata:
+      category: comity-architecture
+      standard: adapters.md
+      section: 11
+
+  - id: comity-no-console-log
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Core Modules MUST NOT use `console.log` for telemetry. Use the framework's
+      logger abstraction.
+        - coding.md
+    pattern: console.log(...$ARGS)
+    paths:
+      include:
+        - "**/packages/**/src/**/*.ts"
+      exclude:
+        - "**/packages/*/adapters/**"
+        - "**/node_modules/**"
+    metadata:
+      category: comity-architecture
+      standard: coding.md

package/rules/error-class-shape.yaml

@@ -0,0 +1,47 @@
+rules:
+  - id: comity-error-class-must-extend-base-error
+    languages: [typescript]
+    severity: ERROR
+    message: |
+      Every Comity error class MUST extend `@comity/primitives/errors/BaseError`
+      or a documented domain base. Standalone Error classes lose the structured
+      `code` field and break cross-package error handling.
+        - errors.md §6
+        - public-api.md §3.1
+    patterns:
+      - pattern: |
+          class $NAME extends Error { ... }
+      - pattern-not: |
+          class $NAME extends BaseError { ... }
+      - pattern-not: |
+          class $NAME extends $BASE { ... }
+      - pattern-not-inside: |
+          /** ... */
+          ...
+          class $NAME { ... }
+    metadata:
+      category: comity-architecture
+      standard: errors.md
+      section: 6
+
+  - id: comity-error-class-must-have-code-field
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      A Comity error class SHOULD expose a stable `code` field for cross-package
+      error matching.
+        - errors.md §6
+    pattern: |
+      class $NAME extends BaseError {
+        ...
+      }
+    pattern-not: |
+      class $NAME extends BaseError {
+        ...
+        readonly code: $T;
+        ...
+      }
+    metadata:
+      category: comity-architecture
+      standard: errors.md
+      section: 6

package/rules/module-shape.yaml

@@ -0,0 +1,43 @@
+rules:
+  - id: comity-module-no-default-export
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Comity Core Modules MUST use named exports, not default exports. Default
+      exports obscure the public surface and break tree-shaking guarantees.
+        - public-api.md §3
+        - architecture-validation.md §4
+    pattern: export default $X
+    paths:
+      include:
+        - "**/packages/**/src/index.ts"
+        - "**/packages/**/src/contracts/index.ts"
+      exclude:
+        - "**/node_modules/**"
+    metadata:
+      category: comity-architecture
+      standard: public-api.md
+      section: 3
+
+  - id: comity-module-must-have-internal-marker
+    languages: [typescript]
+    severity: INFO
+    message: |
+      Files intended to be internal-only SHOULD be located under an `internal/`
+      or `lazy/` directory; the ESLint rule `@comity/no-forbidden-deep-import`
+      enforces the reverse — consumers MUST NOT reach into these paths.
+        - public-api.md §3.2
+    patterns:
+      - pattern: |
+          /** @internal */
+          ...
+      - pattern-not-inside: |
+          /** @internal */
+          ...
+          ...
+          /** @internal */
+          ...
+    metadata:
+      category: comity-architecture
+      standard: public-api.md
+      section: "3.2"

package/rules/value-object-shape.yaml

@@ -0,0 +1,56 @@
+rules:
+  - id: comity-value-object-must-be-readonly
+    languages: [typescript]
+    severity: WARNING
+    message: |
+      Value objects MUST be immutable. All fields SHOULD be `readonly`.
+        - domain-modeling.md
+    pattern: |
+      class $NAME {
+        ...
+        constructor(...) {
+          ...
+          this.$F = $V;
+          ...
+        }
+      }
+    pattern-not: |
+      class $NAME {
+        ...
+        constructor(...) {
+          ...
+          this.$F: readonly $T = $V;
+          ...
+        }
+      }
+    paths:
+      include:
+        - "**/packages/**/src/domain/**/*.ts"
+      exclude:
+        - "**/node_modules/**"
+    metadata:
+      category: comity-domain-modeling
+      standard: domain-modeling.md
+
+  - id: comity-entity-must-emit-events
+    languages: [typescript]
+    severity: INFO
+    message: |
+      Domain entities SHOULD expose a typed event surface via the `@comity/primitives/events`
+      primitive, not raw EventEmitter.
+        - events.md
+    pattern: |
+      class $NAME {
+        ...
+        new EventEmitter();
+        ...
+      }
+    paths:
+      include:
+        - "**/packages/**/src/domain/**/*.ts"
+        - "**/packages/**/src/core/**/*.ts"
+      exclude:
+        - "**/node_modules/**"
+    metadata:
+      category: comity-events
+      standard: events.md