Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 70 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,16 @@ on:
push:
branches: [main]
pull_request:
branches: [main]
# replay stack: pull requests based on replay/** branches are checked too (remove when the replay is finished)
branches: [main, 'replay/**']

permissions:
contents: read

concurrency:
# Key PR runs by number so they cannot cancel the push run for a merged commit.
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
gitleaks:
Expand Down Expand Up @@ -69,6 +70,66 @@ jobs:
annotations: true
version: ${{ env.ZIZMOR_VERSION }}

changes:
name: Changes
runs-on: ubuntu-latest
timeout-minutes: 5
outputs:
code: ${{ steps.diff.outputs.code }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
- id: diff
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: |
set -eu
code=true
if [ -n "${BASE_SHA:-}" ] && ! git diff --name-only "$BASE_SHA"...HEAD | grep -qvE '^(docs/|.*\.md$|LICENSE$)'; then code=false; fi
echo "code=$code" >> "$GITHUB_OUTPUT"

static:
name: Static checks
needs: changes
if: needs.changes.outputs.code == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
runs-on: ${{ format('runs-on={0}-{1}-static/runner=4cpu-linux-x64', github.run_id, github.run_attempt) }}
Comment thread
omercnet marked this conversation as resolved.
Resolved
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci --ignore-scripts
- run: npm run lint
- run: npm run typecheck
- run: npm run build

unit:
name: Unit tests
needs: changes
if: needs.changes.outputs.code == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
runs-on: ${{ format('runs-on={0}-{1}-unit/runner=4cpu-linux-x64', github.run_id, github.run_attempt) }}
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci --ignore-scripts
- name: Fresh-runner preflight (IPv6 loopback)
run: |
getent ahostsv6 localhost >/dev/null || sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=0
node -e "require('node:net').createServer().listen(0,'::1',function(){this.close()})"
- run: npm test

ci-required:
name: CI Required
runs-on: ubuntu-latest
Expand All @@ -77,15 +138,20 @@ jobs:
needs:
- gitleaks
- workflow-policy
- changes
- static
- unit
steps:
- name: Verify every needed job succeeded
env:
NEEDS_JSON: ${{ toJSON(needs) }}
run: |
set -eu
# Strict success-only semantics: a skipped or failed job fails the gate.
# A failed or cancelled job always fails the gate. A skipped job passes only when the changes job
# reported a documents-only change (code=false): anything else that is skipped fails.
code=$(jq -r '.changes.outputs.code // "true"' <<< "$NEEDS_JSON")
jq -r 'to_entries[] | if .value.result == "success" then "OK \(.key)" else "FAIL \(.key) (result=\(.value.result))" end' <<< "$NEEDS_JSON"
if jq -e '[ to_entries[] | select(.value.result != "success") ] | length > 0' <<< "$NEEDS_JSON" >/dev/null; then
if jq -e --arg code "$code" '[ to_entries[] | select(.value.result != "success") | select(.value.result != "skipped" or $code == "true") ] | length > 0' <<< "$NEEDS_JSON" >/dev/null; then
echo ""
echo "::error::One or more required jobs did not succeed. CI gate failing."
exit 1
Expand Down
5 changes: 5 additions & 0 deletions .github/zizmor.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
rules:
unpinned-uses:
config:
policies:
"*": hash-pin
1 change: 1 addition & 0 deletions .nvmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
26
7 changes: 7 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,13 @@ Grimoire is developed in the open, through small pull requests into `main`.
and all review threads must be resolved.
- Pull requests from outside the project are welcome, but reviews may take a
while.
- Workflow runs for pull requests from forks need a maintainer's approval and
run only the cheap checks on GitHub-hosted runners; the heavy jobs (on the
project's own runners) run only for branches in this repository, so
`CI Required` stays red for a fork pull request.
- To merge a contribution from a fork, a maintainer who has reviewed its
commit pushes it to a branch in this repository and opens a pull request
from that branch, so that every job runs before the merge.
- Never commit secrets or credentials.
- Contributions are accepted under the same licence as the project, the
Apache License 2.0 (inbound equals outbound); there is no contributor
Expand Down
185 changes: 185 additions & 0 deletions eslint.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
import { defineConfig, globalIgnores } from "eslint/config";
import tseslint from "typescript-eslint";

// Provider modules the core must never import (R2.19, R12.34).
const forbiddenModules = [
"@aws-sdk",
"@descope",
"@hocuspocus",
"@hono",
"pg",
"kysely",
"pg-boss",
"hono",
"ws",
"crossws",
"pino",
"rate-limiter-flexible",
"yjs",
"y-protocols",
];
const forbiddenImportPatterns = forbiddenModules.flatMap((m) => [m, `${m}/*`]);
const forbiddenSourceRegex = `^(?:${forbiddenModules.map((m) => m.replace(/[-/]/g, "\\$&")).join("|")})(?:$|[^\\w-])`;
const importMessage =
"packages/core must not import provider SDKs or runtime libraries; use a port interface (R2.19).";
const envMessage =
"packages/core must not read process.env in packages/core; only the config adapter reads the environment (R2.19).";

const envRules = [
{
selector: "MemberExpression[object.name='process'][property.name='env']",
message: envMessage,
},
{
selector: "MemberExpression[object.name='process'][property.value='env']",
message: envMessage,
},
{
selector: "MemberExpression[object.property.name='process'][property.name='env']",
message: envMessage,
},
{
selector: "VariableDeclarator[init.name='process'] > ObjectPattern > Property[key.name='env']",
message: envMessage,
},
];

// Server-only libraries: never in the browser client or the shared libraries (R11.1).
const serverOnlyModules = ["hono", "@hono", "@hocuspocus/server", "kysely", "pg", "pino", "pg-boss", "crossws", "rate-limiter-flexible"];
const serverOnlyPatterns = serverOnlyModules.flatMap((m) => [m, `${m}/*`]);
const serverOnlyMessage = "Server-only library: not allowed here; the browser client and shared libraries stay provider-free (R11.1).";
const adapterPackage = (name) => `@tektum/grimoire-adapter-${name}`;
const adaptersExcept = (name) => ["@tektum/grimoire-adapter-*", `!${adapterPackage(name)}`];
const adapterLayerMessage =
"An adapter may import only @tektum/grimoire-core and its own library: never another adapter or anything under apps/ (R2.18).";
const escapeRegex = (s) => s.replace(/[-/]/g, "\\$&");
const dynamicRulesFor = (sourceRegex, message) => [
{ selector: `ImportExpression[source.value=/${sourceRegex}/]`, message },
{ selector: `CallExpression[callee.name='require'][arguments.0.value=/${sourceRegex}/]`, message },
// A template literal without expressions is a plain string: refuse it by module name too.
{ selector: `ImportExpression[source.type='TemplateLiteral'][source.expressions.length=0][source.quasis.0.value.cooked=/${sourceRegex}/]`, message },
{
selector: `CallExpression[callee.name='require'][arguments.0.type='TemplateLiteral'][arguments.0.expressions.length=0][arguments.0.quasis.0.value.cooked=/${sourceRegex}/]`,
message,
},
];
const dynamicImportRules = dynamicRulesFor(forbiddenSourceRegex, importMessage);
const serverOnlyRegex = `^(?:${serverOnlyModules.map(escapeRegex).join("|")})(?:$|[^\\w-])`;
const appsRegex = "^@tektum\\/grimoire-(?:server|web)(?:$|\\/)";
const allAdaptersRegex = "^@tektum\\/grimoire-adapter-";
const adapterNames = ["auth-descope", "auth-dev", "auth-fake", "collab-hocuspocus", "config-env", "db-kysely", "logger-json", "markdown-milkdown"];

// Packages whose imports are restricted the same way: no adapters, no apps, no server-only libraries.
const noAdaptersNoServerOnly = (message) => ({
patterns: [
{ group: serverOnlyPatterns, message: serverOnlyMessage },
{ group: ["@tektum/grimoire-adapter-*", "@tektum/grimoire-server", "@tektum/grimoire-server/*", "@tektum/grimoire-web", "@tektum/grimoire-web/*"], message },
],
});
const noAdaptersNoServerOnlySyntax = (message) => [
...dynamicRulesFor(serverOnlyRegex, serverOnlyMessage),
...dynamicRulesFor(`${allAdaptersRegex}|${appsRegex}`, message),
];

const webMessage = "apps/web may not import adapters or apps/server; it may use @tektum/grimoire-core (contracts are silent, so core is allowed) (R11.1).";
const libMessage = "Shared libraries may not import adapters, apps or server-only libraries (R2.18, R11.1).";
const composeMessage =
"Only apps/server/src/composition.ts constructs adapters; elsewhere import adapter packages as types only (contracts section 1, R2.18).";

// Relative specifiers that name another package's directory (the scan test in packages/core/test/boundaries is the
// authority: it resolves every relative specifier and fails when it leaves the package).
const relativeMessage = "Do not reach into another package by a relative path; import it by package name (R2.18).";
// Anchored to relative specifiers (`./` or `../`): a bare package subpath such as `crossws/adapters/node` must not match.
const relativePatterns = [{ regex: "^\\.{1,2}\\/(?:.*\\/)?(?:packages|apps|adapters)(?:\\/|$)", message: relativeMessage }];
// Indirect loaders would bypass every import rule: createRequire, process.mainModule, eval and Function.
const loaderMessage = "Indirect module loading and code evaluation bypass the import rules; use a literal import (R2.18).";
// The whole module is banned (not just the name): `import m from "node:module"; m.createRequire` would pass importNames.
const loaderPaths = ["node:module", "module"].map((name) => ({ name, message: loaderMessage }));
const restrictedImports = (patterns = [], paths = []) => [
"error",
{ paths: [...paths, ...loaderPaths], patterns: [...patterns, ...relativePatterns] },
];

// Only string literals (and expression-free templates, which the module rules above read as strings) may be imported
// dynamically, so the module rules cannot be bypassed.
const nonLiteralMessage = "Dynamic import() and require() take a plain string literal, so the import rules can see the module.";
const nonLiteralRules = [
{
selector: "ImportExpression:not([source.type='Literal']):not([source.type='TemplateLiteral'][source.expressions.length=0])",
message: nonLiteralMessage,
},
{
selector:
"CallExpression[callee.name='require']:not([arguments.0.type='Literal']):not([arguments.0.type='TemplateLiteral'][arguments.0.expressions.length=0])",
message: nonLiteralMessage,
},
];
nonLiteralRules.push(
{ selector: "MemberExpression[object.name='process'][property.name='mainModule']", message: loaderMessage },
{ selector: "MemberExpression[object.name='process'][property.value='mainModule']", message: loaderMessage },
{ selector: "CallExpression[callee.name='eval']", message: loaderMessage },
{ selector: "CallExpression[callee.name='Function']", message: loaderMessage },
{ selector: "NewExpression[callee.name='Function']", message: loaderMessage },
{ selector: "MemberExpression[object.name='globalThis'][property.name=/^(?:eval|Function)$/]", message: loaderMessage },
);
// Our own code that genuinely imports a computed path (each reasoned here; both are the only such files).
const nonLiteralExempt = [
"packages/adapters/db-kysely/src/index.ts", // loads migration files by path for Kysely's migration provider
"packages/core/test/boundaries/reference-excluded.test.ts", // imports the repository's vitest.config.js by file URL
];
const scope = (files, imports, syntax, exempt = []) => [
{ files, ignores: exempt, rules: { "no-restricted-imports": imports, "no-restricted-syntax": ["error", ...syntax, ...nonLiteralRules] } },
...(exempt.length
? [{ files: exempt, rules: { "no-restricted-imports": imports, "no-restricted-syntax": ["error", ...syntax] } }]
: []),
];

export default defineConfig([
globalIgnores(["reference/**", "**/node_modules/**", "**/dist/**", "**/coverage/**", "packages/core/test/boundaries/fixtures/**"]),
tseslint.configs.recommended,
// Every workspace package: no relative reach into other packages, no computed dynamic imports.
...scope(["apps/**", "packages/**"], restrictedImports(), [], nonLiteralExempt),
...scope(
["packages/core/**"],
restrictedImports(
[{ group: forbiddenImportPatterns, message: importMessage }],
[
{ name: "process", message: envMessage },
{ name: "node:process", message: envMessage },
],
),
[...envRules, ...dynamicImportRules],
nonLiteralExempt.filter((f) => f.startsWith("packages/core/")),
),
// Adapters: core and own library only.
...adapterNames.flatMap((name) =>
scope(
[`packages/adapters/${name}/**`],
restrictedImports([
{ group: adaptersExcept(name), message: adapterLayerMessage },
{ group: ["@tektum/grimoire-server", "@tektum/grimoire-server/*", "@tektum/grimoire-web", "@tektum/grimoire-web/*"], message: adapterLayerMessage },
]),
dynamicRulesFor(`^@tektum\\/grimoire-adapter-(?!${escapeRegex(name)}(?:$|\\/))|${appsRegex}`, adapterLayerMessage),
nonLiteralExempt.filter((f) => f.startsWith(`packages/adapters/${name}/`)),
),
),
// apps/web: no server-only libraries, adapters or apps/server.
...scope(["apps/web/**"], restrictedImports(noAdaptersNoServerOnly(webMessage).patterns), noAdaptersNoServerOnlySyntax(webMessage)),
...scope(
["packages/editor-schema/**", "packages/api-client/**"],
restrictedImports(noAdaptersNoServerOnly(libMessage).patterns),
noAdaptersNoServerOnlySyntax(libMessage),
),
// apps/server: adapters only as types, except in composition.ts (the one place adapters are constructed).
{
files: ["apps/server/src/**"],
ignores: ["apps/server/src/composition.ts", "apps/server/src/cli.ts"],
rules: {
"no-restricted-imports": restrictedImports([{ group: ["@tektum/grimoire-adapter-*"], allowTypeImports: true, message: composeMessage }]),
"no-restricted-syntax": ["error", ...dynamicRulesFor(allAdaptersRegex, composeMessage), ...nonLiteralRules],
},
},
// composition.ts and cli.ts (the migration command line, a second composition root; reported to the manager in
// M1-T02c) construct adapters, so only the relative-path and computed-import rules apply to them.
...scope(["apps/server/src/composition.ts", "apps/server/src/cli.ts"], restrictedImports(), []),
]);
2 changes: 2 additions & 0 deletions mise.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
[tools]
node = "26"
Loading