Skip to content

Commit 37e306a

Browse files
authored
chore: npm workspaces, TypeScript, lint and test runner, with the first core ports (#3)
* chore: npm workspaces, TypeScript, lint and test runner, with the first core ports * fix(core): let callers override descopeMaxTokenLifetimeSeconds in the fake config * docs: maintainers read workflow-related changes before approving fork runs
1 parent 73188fc commit 37e306a

22 files changed

Lines changed: 3213 additions & 4 deletions

‎.github/workflows/ci.yml‎

Lines changed: 70 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,16 @@ on:
77
push:
88
branches: [main]
99
pull_request:
10-
branches: [main]
10+
# replay stack: pull requests based on replay/** branches are checked too (remove when the replay is finished)
11+
branches: [main, 'replay/**']
1112

1213
permissions:
1314
contents: read
1415

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

2021
jobs:
2122
gitleaks:
@@ -69,6 +70,66 @@ jobs:
6970
annotations: true
7071
version: ${{ env.ZIZMOR_VERSION }}
7172

73+
changes:
74+
name: Changes
75+
runs-on: ubuntu-latest
76+
timeout-minutes: 5
77+
outputs:
78+
code: ${{ steps.diff.outputs.code }}
79+
steps:
80+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
81+
with:
82+
fetch-depth: 0
83+
persist-credentials: false
84+
- id: diff
85+
env:
86+
BASE_SHA: ${{ github.event.pull_request.base.sha }}
87+
run: |
88+
set -eu
89+
code=true
90+
if [ -n "${BASE_SHA:-}" ] && ! git diff --name-only "$BASE_SHA"...HEAD | grep -qvE '^(docs/|.*\.md$|LICENSE$)'; then code=false; fi
91+
echo "code=$code" >> "$GITHUB_OUTPUT"
92+
93+
static:
94+
name: Static checks
95+
needs: changes
96+
if: needs.changes.outputs.code == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
97+
runs-on: ${{ format('runs-on={0}-{1}-static/runner=4cpu-linux-x64', github.run_id, github.run_attempt) }}
98+
timeout-minutes: 10
99+
steps:
100+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
101+
with:
102+
persist-credentials: false
103+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
104+
with:
105+
node-version-file: .nvmrc
106+
cache: npm
107+
- run: npm ci --ignore-scripts
108+
- run: npm run lint
109+
- run: npm run typecheck
110+
- run: npm run build
111+
112+
unit:
113+
name: Unit tests
114+
needs: changes
115+
if: needs.changes.outputs.code == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
116+
runs-on: ${{ format('runs-on={0}-{1}-unit/runner=4cpu-linux-x64', github.run_id, github.run_attempt) }}
117+
timeout-minutes: 10
118+
steps:
119+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
120+
with:
121+
persist-credentials: false
122+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
123+
with:
124+
node-version-file: .nvmrc
125+
cache: npm
126+
- run: npm ci --ignore-scripts
127+
- name: Fresh-runner preflight (IPv6 loopback)
128+
run: |
129+
getent ahostsv6 localhost >/dev/null || sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=0
130+
node -e "require('node:net').createServer().listen(0,'::1',function(){this.close()})"
131+
- run: npm test
132+
72133
ci-required:
73134
name: CI Required
74135
runs-on: ubuntu-latest
@@ -77,15 +138,20 @@ jobs:
77138
needs:
78139
- gitleaks
79140
- workflow-policy
141+
- changes
142+
- static
143+
- unit
80144
steps:
81145
- name: Verify every needed job succeeded
82146
env:
83147
NEEDS_JSON: ${{ toJSON(needs) }}
84148
run: |
85149
set -eu
86-
# Strict success-only semantics: a skipped or failed job fails the gate.
150+
# A failed or cancelled job always fails the gate. A skipped job passes only when the changes job
151+
# reported a documents-only change (code=false): anything else that is skipped fails.
152+
code=$(jq -r '.changes.outputs.code // "true"' <<< "$NEEDS_JSON")
87153
jq -r 'to_entries[] | if .value.result == "success" then "OK \(.key)" else "FAIL \(.key) (result=\(.value.result))" end' <<< "$NEEDS_JSON"
88-
if jq -e '[ to_entries[] | select(.value.result != "success") ] | length > 0' <<< "$NEEDS_JSON" >/dev/null; then
154+
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
89155
echo ""
90156
echo "::error::One or more required jobs did not succeed. CI gate failing."
91157
exit 1

‎.github/zizmor.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
rules:
2+
unpinned-uses:
3+
config:
4+
policies:
5+
"*": hash-pin

‎.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
26

‎CONTRIBUTING.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,21 @@ Grimoire is developed in the open, through small pull requests into `main`.
1010
and all review threads must be resolved.
1111
- Pull requests from outside the project are welcome, but reviews may take a
1212
while.
13+
- Workflow runs for pull requests from forks need a maintainer's approval and
14+
run only the cheap checks on GitHub-hosted runners; the heavy jobs (on the
15+
project's own runners) run only for branches in this repository, so
16+
`CI Required` stays red for a fork pull request.
17+
- To merge a contribution from a fork, a maintainer who has reviewed its
18+
commit pushes it to a branch in this repository and opens a pull request
19+
from that branch, so that every job runs before the merge.
1320
- Never commit secrets or credentials.
1421
- Contributions are accepted under the same licence as the project, the
1522
Apache License 2.0 (inbound equals outbound); there is no contributor
1623
agreement.
1724

1825
To report a security issue, do not open a public issue: follow
1926
[SECURITY.md](SECURITY.md).
27+
28+
## For maintainers
29+
30+
Workflow runs from outside contributors are held until a maintainer approves them, and that approval is the security boundary. Before approving workflow runs for an outside pull request, read every change under `.github/` and to any script the workflows run (`Makefile`, `package.json` scripts, `tools/`); if such a pull request needs the heavy jobs, a maintainer pushes the reviewed commit to a branch in this repository.

‎eslint.config.js‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
import { defineConfig, globalIgnores } from "eslint/config";
2+
import tseslint from "typescript-eslint";
3+
4+
// Provider modules the core must never import (R2.19, R12.34).
5+
const forbiddenModules = [
6+
"@aws-sdk",
7+
"@descope",
8+
"@hocuspocus",
9+
"@hono",
10+
"pg",
11+
"kysely",
12+
"pg-boss",
13+
"hono",
14+
"ws",
15+
"crossws",
16+
"pino",
17+
"rate-limiter-flexible",
18+
"yjs",
19+
"y-protocols",
20+
];
21+
const forbiddenImportPatterns = forbiddenModules.flatMap((m) => [m, `${m}/*`]);
22+
const forbiddenSourceRegex = `^(?:${forbiddenModules.map((m) => m.replace(/[-/]/g, "\\$&")).join("|")})(?:$|[^\\w-])`;
23+
const importMessage =
24+
"packages/core must not import provider SDKs or runtime libraries; use a port interface (R2.19).";
25+
const envMessage =
26+
"packages/core must not read process.env in packages/core; only the config adapter reads the environment (R2.19).";
27+
28+
const envRules = [
29+
{
30+
selector: "MemberExpression[object.name='process'][property.name='env']",
31+
message: envMessage,
32+
},
33+
{
34+
selector: "MemberExpression[object.name='process'][property.value='env']",
35+
message: envMessage,
36+
},
37+
{
38+
selector: "MemberExpression[object.property.name='process'][property.name='env']",
39+
message: envMessage,
40+
},
41+
{
42+
selector: "VariableDeclarator[init.name='process'] > ObjectPattern > Property[key.name='env']",
43+
message: envMessage,
44+
},
45+
];
46+
47+
// Server-only libraries: never in the browser client or the shared libraries (R11.1).
48+
const serverOnlyModules = ["hono", "@hono", "@hocuspocus/server", "kysely", "pg", "pino", "pg-boss", "crossws", "rate-limiter-flexible"];
49+
const serverOnlyPatterns = serverOnlyModules.flatMap((m) => [m, `${m}/*`]);
50+
const serverOnlyMessage = "Server-only library: not allowed here; the browser client and shared libraries stay provider-free (R11.1).";
51+
const adapterPackage = (name) => `@tektum/grimoire-adapter-${name}`;
52+
const adaptersExcept = (name) => ["@tektum/grimoire-adapter-*", `!${adapterPackage(name)}`];
53+
const adapterLayerMessage =
54+
"An adapter may import only @tektum/grimoire-core and its own library: never another adapter or anything under apps/ (R2.18).";
55+
const escapeRegex = (s) => s.replace(/[-/]/g, "\\$&");
56+
const dynamicRulesFor = (sourceRegex, message) => [
57+
{ selector: `ImportExpression[source.value=/${sourceRegex}/]`, message },
58+
{ selector: `CallExpression[callee.name='require'][arguments.0.value=/${sourceRegex}/]`, message },
59+
// A template literal without expressions is a plain string: refuse it by module name too.
60+
{ selector: `ImportExpression[source.type='TemplateLiteral'][source.expressions.length=0][source.quasis.0.value.cooked=/${sourceRegex}/]`, message },
61+
{
62+
selector: `CallExpression[callee.name='require'][arguments.0.type='TemplateLiteral'][arguments.0.expressions.length=0][arguments.0.quasis.0.value.cooked=/${sourceRegex}/]`,
63+
message,
64+
},
65+
];
66+
const dynamicImportRules = dynamicRulesFor(forbiddenSourceRegex, importMessage);
67+
const serverOnlyRegex = `^(?:${serverOnlyModules.map(escapeRegex).join("|")})(?:$|[^\\w-])`;
68+
const appsRegex = "^@tektum\\/grimoire-(?:server|web)(?:$|\\/)";
69+
const allAdaptersRegex = "^@tektum\\/grimoire-adapter-";
70+
const adapterNames = ["auth-descope", "auth-dev", "auth-fake", "collab-hocuspocus", "config-env", "db-kysely", "logger-json", "markdown-milkdown"];
71+
72+
// Packages whose imports are restricted the same way: no adapters, no apps, no server-only libraries.
73+
const noAdaptersNoServerOnly = (message) => ({
74+
patterns: [
75+
{ group: serverOnlyPatterns, message: serverOnlyMessage },
76+
{ group: ["@tektum/grimoire-adapter-*", "@tektum/grimoire-server", "@tektum/grimoire-server/*", "@tektum/grimoire-web", "@tektum/grimoire-web/*"], message },
77+
],
78+
});
79+
const noAdaptersNoServerOnlySyntax = (message) => [
80+
...dynamicRulesFor(serverOnlyRegex, serverOnlyMessage),
81+
...dynamicRulesFor(`${allAdaptersRegex}|${appsRegex}`, message),
82+
];
83+
84+
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).";
85+
const libMessage = "Shared libraries may not import adapters, apps or server-only libraries (R2.18, R11.1).";
86+
const composeMessage =
87+
"Only apps/server/src/composition.ts constructs adapters; elsewhere import adapter packages as types only (contracts section 1, R2.18).";
88+
89+
// Relative specifiers that name another package's directory (the scan test in packages/core/test/boundaries is the
90+
// authority: it resolves every relative specifier and fails when it leaves the package).
91+
const relativeMessage = "Do not reach into another package by a relative path; import it by package name (R2.18).";
92+
// Anchored to relative specifiers (`./` or `../`): a bare package subpath such as `crossws/adapters/node` must not match.
93+
const relativePatterns = [{ regex: "^\\.{1,2}\\/(?:.*\\/)?(?:packages|apps|adapters)(?:\\/|$)", message: relativeMessage }];
94+
// Indirect loaders would bypass every import rule: createRequire, process.mainModule, eval and Function.
95+
const loaderMessage = "Indirect module loading and code evaluation bypass the import rules; use a literal import (R2.18).";
96+
// The whole module is banned (not just the name): `import m from "node:module"; m.createRequire` would pass importNames.
97+
const loaderPaths = ["node:module", "module"].map((name) => ({ name, message: loaderMessage }));
98+
const restrictedImports = (patterns = [], paths = []) => [
99+
"error",
100+
{ paths: [...paths, ...loaderPaths], patterns: [...patterns, ...relativePatterns] },
101+
];
102+
103+
// Only string literals (and expression-free templates, which the module rules above read as strings) may be imported
104+
// dynamically, so the module rules cannot be bypassed.
105+
const nonLiteralMessage = "Dynamic import() and require() take a plain string literal, so the import rules can see the module.";
106+
const nonLiteralRules = [
107+
{
108+
selector: "ImportExpression:not([source.type='Literal']):not([source.type='TemplateLiteral'][source.expressions.length=0])",
109+
message: nonLiteralMessage,
110+
},
111+
{
112+
selector:
113+
"CallExpression[callee.name='require']:not([arguments.0.type='Literal']):not([arguments.0.type='TemplateLiteral'][arguments.0.expressions.length=0])",
114+
message: nonLiteralMessage,
115+
},
116+
];
117+
nonLiteralRules.push(
118+
{ selector: "MemberExpression[object.name='process'][property.name='mainModule']", message: loaderMessage },
119+
{ selector: "MemberExpression[object.name='process'][property.value='mainModule']", message: loaderMessage },
120+
{ selector: "CallExpression[callee.name='eval']", message: loaderMessage },
121+
{ selector: "CallExpression[callee.name='Function']", message: loaderMessage },
122+
{ selector: "NewExpression[callee.name='Function']", message: loaderMessage },
123+
{ selector: "MemberExpression[object.name='globalThis'][property.name=/^(?:eval|Function)$/]", message: loaderMessage },
124+
);
125+
// Our own code that genuinely imports a computed path (each reasoned here; both are the only such files).
126+
const nonLiteralExempt = [
127+
"packages/adapters/db-kysely/src/index.ts", // loads migration files by path for Kysely's migration provider
128+
"packages/core/test/boundaries/reference-excluded.test.ts", // imports the repository's vitest.config.js by file URL
129+
];
130+
const scope = (files, imports, syntax, exempt = []) => [
131+
{ files, ignores: exempt, rules: { "no-restricted-imports": imports, "no-restricted-syntax": ["error", ...syntax, ...nonLiteralRules] } },
132+
...(exempt.length
133+
? [{ files: exempt, rules: { "no-restricted-imports": imports, "no-restricted-syntax": ["error", ...syntax] } }]
134+
: []),
135+
];
136+
137+
export default defineConfig([
138+
globalIgnores(["reference/**", "**/node_modules/**", "**/dist/**", "**/coverage/**", "packages/core/test/boundaries/fixtures/**"]),
139+
tseslint.configs.recommended,
140+
// Every workspace package: no relative reach into other packages, no computed dynamic imports.
141+
...scope(["apps/**", "packages/**"], restrictedImports(), [], nonLiteralExempt),
142+
...scope(
143+
["packages/core/**"],
144+
restrictedImports(
145+
[{ group: forbiddenImportPatterns, message: importMessage }],
146+
[
147+
{ name: "process", message: envMessage },
148+
{ name: "node:process", message: envMessage },
149+
],
150+
),
151+
[...envRules, ...dynamicImportRules],
152+
nonLiteralExempt.filter((f) => f.startsWith("packages/core/")),
153+
),
154+
// Adapters: core and own library only.
155+
...adapterNames.flatMap((name) =>
156+
scope(
157+
[`packages/adapters/${name}/**`],
158+
restrictedImports([
159+
{ group: adaptersExcept(name), message: adapterLayerMessage },
160+
{ group: ["@tektum/grimoire-server", "@tektum/grimoire-server/*", "@tektum/grimoire-web", "@tektum/grimoire-web/*"], message: adapterLayerMessage },
161+
]),
162+
dynamicRulesFor(`^@tektum\\/grimoire-adapter-(?!${escapeRegex(name)}(?:$|\\/))|${appsRegex}`, adapterLayerMessage),
163+
nonLiteralExempt.filter((f) => f.startsWith(`packages/adapters/${name}/`)),
164+
),
165+
),
166+
// apps/web: no server-only libraries, adapters or apps/server.
167+
...scope(["apps/web/**"], restrictedImports(noAdaptersNoServerOnly(webMessage).patterns), noAdaptersNoServerOnlySyntax(webMessage)),
168+
...scope(
169+
["packages/editor-schema/**", "packages/api-client/**"],
170+
restrictedImports(noAdaptersNoServerOnly(libMessage).patterns),
171+
noAdaptersNoServerOnlySyntax(libMessage),
172+
),
173+
// apps/server: adapters only as types, except in composition.ts (the one place adapters are constructed).
174+
{
175+
files: ["apps/server/src/**"],
176+
ignores: ["apps/server/src/composition.ts", "apps/server/src/cli.ts"],
177+
rules: {
178+
"no-restricted-imports": restrictedImports([{ group: ["@tektum/grimoire-adapter-*"], allowTypeImports: true, message: composeMessage }]),
179+
"no-restricted-syntax": ["error", ...dynamicRulesFor(allAdaptersRegex, composeMessage), ...nonLiteralRules],
180+
},
181+
},
182+
// composition.ts and cli.ts (the migration command line, a second composition root; reported to the manager in
183+
// M1-T02c) construct adapters, so only the relative-path and computed-import rules apply to them.
184+
...scope(["apps/server/src/composition.ts", "apps/server/src/cli.ts"], restrictedImports(), []),
185+
]);

‎mise.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[tools]
2+
node = "26"

0 commit comments

Comments
 (0)