Code reference detail
package.json
package.json
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| monorepo | The workspace is a pnpm monorepo ( `packages\*`, extension webviews, and `site` ) per ["../pnpm-workspace.yaml"] and [development_core.pnpm]. TypeScript project references build in order language → analytical → mcp → cli → extension per ["../tsconfig.build.json"]. Living requirements for the product live in this `reqlan rq` folder. Root orchestration ( Langium generate, package builds, Cursor skill sync ) lives in ["../package.json"]. Why libraries are separate packages ( and how Changesets sees them ): [package_versioning]. | 0.040 | ||
| scope | These requirements describe the cross-package system architecture of the reqlan monorepo: language definition, language server, ideas index, editor product, and companion tools. They are distinct from [extension_scope.scope], which bounds only the VS Code extension and LSP product surface. Language concepts live in [ontology]; syntax truth lives in [syntax]; editor module contracts live under extension / module. Grouped as [workspace_packages], [language_runtime], and [product_map]. | 0.040 | ||
| check | done | `reqlan check` should run perform the following checks: - ensure all rq [reference] point to real nodes, unless rq ignored with [comment_reference_ignore]. - this tests rqcomments point to real parts of the namespace, that code references exist, and that rq references exists. - report unresolved imports: [check_unresolved_imports]. - report a comment reference with invalid syntax: [code_comment_syntax_errors]. - report a qualified reference whose file is not on disk: [check_qualified_missing_file]. - report a qualified reference whose `.rq` file does not declare the idea: [check_qualified_missing_idea]. - it should really just be a wrapper of the [index] and return the issues ( as a pipe, terminal output, or json ). Issue order: [check_order_by_target]. Sparse wildcards: [check_wildcard_sparse] via flags [check_wildcard_zero] and [check_wildcard_one]. Path globs: [check_glob_patterns]. Skip missing targets: [check_skip_targets] [check_skip_gitignored_targets]. CLI: ["../cli/cli_package.rq".commands]. MCP: ["../extension/agent/skills-and-mcp.rq".mcp_check]. CI: [check_meta_implementation]. Site demo: ["../site/site.rq".broken_links_showcase]. | 1.000 | |
| check_meta_implementation | done | [check] is a step in the sequential GitHub CI job after one workspace build. Pull requests use ["../../.github/workflows/ci.yml"]. Main uses the same workflow through ["../../.github/workflows/release.yml"] ( ["../distribution/distribution.rq".ci_gate] ). The job installs workspace packages once ( `pnpm install --frozen-lockfile` ), asserts `@reqlan/*` resolve under `packages/` ( ["../../scripts/assert-workspace-reqlan.mjs"] ), compiles crates and TypeScript, then runs crate tests, `node packages/cli/bin/cli.js check`, and JS / TS tests against that build. Do not install `@reqlan/cli` or other `@reqlan/*` packages from npm. Platform natives in this workspace come from `packages/analytical-native/` via `packageExtensions` in ["../../pnpm-workspace.yaml"], not from the registry. Do not call a global `reqlan` binary. Do not run a second install before check. GitHub and Azure pass `--skip-gitignored-targets` because gitignored files are not in a CI checkout ( [check_skip_gitignored_targets] ). Azure uses the same workspace CLI after its package build on `ext/v*` tags. Related: [check] [check_skip_targets] [check_skip_gitignored_targets] ["../distribution/distribution.rq".ci_gate] | 0.355 | |
| analytical_rust_port | in-progress | Port ["../core-architecture.rq".analytical_package] to Rust: lexer, parser ( index path ), extractor, SQLite index, search, and export. `@reqlan/analytical` remains the published JS facade ( `createAnalysisRuntime` / `AnalysisApi` / Zustand host state ). Native work lives in a `crates/` Cargo workspace and ships as per-architecture binaries per [distribution.rust_binary_distribution]. The editor language server is [lsp_rust.language_server_rust]. This analytical port does not replace that process. Component plans: [rust_crate_layout], [lexer_rust], [parser_rust], [parser_align], [indexer.indexer_rust], [search_rust], [export_rust], [native_bridge], [cutover]. | 0.243 | |
| rust_crate_layout | done | Cargo workspace at repo-root `crates/` ( not inside `packages/analytical` ), crates: - `reqlan-parse` — lexer, parser, AST, recovery, parse budget - `reqlan-index` — extract, rusqlite store, mtime sync, diagnostics - `reqlan-search` — fuzzy / contextual / semantic ranking - `reqlan-export` — snapshot + html / md / json / csv writers; embed existing HTML JS assets - `reqlan-analytical` — facade matching `AnalysisApi` + `WorkspaceIndex` operations - `reqlan-napi` — Node binding for the core engine ( [native_bridge] ) - `reqlan-lsp` — editor language server ( [lsp_rust.language_server_rust] ) Mature crates only ( rusqlite, napi ): no experimental parser generators for the lexer. Golden tests compare Rust extract against Langium on the frozen [golden_corpus], plus the language-test fixtures ported into `reqlan-parse` / `reqlan-index` tests. Format: ["../development/commit.rq".rust_fmt]. Root `pnpm test` runs `test:js` then `test:rust` from ["../../package.json"]. `test:rust` is `cargo test --workspace --exclude reqlan-napi`. GitHub CI compiles crates once, then runs `cargo test` as its own step so crate tests reuse that build ( ["../distribution/distribution.rq".ci_gate] ). | 0.138 | |
| scope | extension build steps for local development and CI | 0.040 | ||
| typescript_compile | done | Langium writes `packages/language/src/generated` ( ast, grammar, module ). That directory is gitignored. `tsc -b tsconfig.build.json` fails on a clean checkout if those files are missing. Root script `build:tsc` is `langium:generate` then that `tsc -b`. Full `pnpm run build` starts with `build:tsc`. GitHub CI, Azure package build, and npm deploy use `build:tsc` so compile matches a clean local build ( [distribution.prerelease_tests], [distribution.ci_gate], [distribution.npm_distribution] ). GitHub CI compiles the TypeScript workspace once in the sequential job, then reuses that emit for [check.check] and package tests ( [check.check_meta_implementation] ). `langium generate` validates ["../../packages/language/langium-config.json"] against the langium-cli schema. langium-cli 4. 3. 0 does not set schema `$id`. jsonschema 1. 5. 0 then throws `ERR_INVALID_URL` for `#/$defs/languageItem` on Node 24. The workspace pins jsonschema 1. 4. 1 for langium-cli in ["../../pnpm-workspace.yaml"] until a langium-cli release includes that `$id`. | 0.045 | |
| rust_fmt | done | CI runs `cargo fmt --all` in write mode on all crates ( [rust_port.rust_crate_layout], [rustfmt_toml] ). Format is a chore, not a gate: an unformatted tree does not fail the job. On same-repo pull requests, if fmt changes files, CI commits `chore: cargo fmt` and pushes to the PR branch. Fork PRs and `workflow_call` ( release ) only format the working tree; they do not push. Recursion stops because: ( 1 ) pushes with the default `GITHUB_TOKEN` do not start new workflow runs; ( 2 ) a second run finds no diff after fmt, so it does not commit again. Pull requests and the release workflow share the same sequential CI job ( ["../distribution/distribution.rq".ci_gate] ). Git pre-commit runs the same formatter in write mode so local commits stay formatted. Skip when no crate Rust is staged, format in place and restage, skip merge / rebase, `SKIP_RUST_FMT=1` escape hatch. [workspace_package] `prepare` sets `core.hooksPath` to `.githooks`. | 0.081 | |
| pnpm_val | done | Root `pnpm run val` chains `check`, then `test`, then `build` ( ["../../package.json"] ). Use for local / ingestion validation ( ["../ingest/ingest.rq"._file] ). | 0.046 | |
| scope | these requirements describe the actual development of the reqlan language and tooling itself | 0.040 | ||
| npm_distribution | in-progress | npm publishing runs only when a `language/v*`, `analytical/v*`, `cli/v*`, or `mcp/v*` tag is pushed. Tags are created by ["./distribution.rq".deployment_flow]; the npm workflow does not publish on ordinary commits. The workflow builds platform binaries when `@reqlan/analytical` was bumped ( `analytical/v*` tag, or `analytical_tag` from the release workflow ). It does not use `github.event_name == 'workflow_call'` for that gate: in a reusable workflow that name is the caller event ( `push` ), and `npm_ref` is the first language / analytical / cli / mcp tag, so a language bump would skip natives. It then publishes each package in sequence with `pnpm --filter <pkg> publish --access public --no-git-checks`. The sequence is language, then all platform packages for [native_targets], then `@reqlan/analytical`, then cli, then mcp. The workflow does not publish `@reqlan/analytical` until every platform package of that `@reqlan/analytical` version is on the npm registry or was published in the same job ( [rust_binary_distribution] ). ["../../scripts/require-natives-published.mjs"] enforces that gate from the analytical package. json version ( not Changesets ). Before each package publishes, ["../../scripts/skip-already-published.mjs"] with `--filter <pkg>` checks the public npm registry and skips that step when the version is already published ( sets `should_publish=false` ). That avoids re-attempting already-published versions under OIDC. Auth uses npm trusted publishing ( OIDC ) from GitHub Actions — no long-lived `NPM_TOKEN`. Workflow requirements: `permissions.id-token: write`, Node ≥ 22. 14 with npm ≥ 11. 5. 1, registry `https://registry.npmjs.org`. Each of `@reqlan/language`, `@reqlan/analytical`, `@reqlan/cli`, `@reqlan/mcp`, and every `@reqlan/analytical-<platform>-<arch>` platform package must have a Trusted Publisher on npmjs. com for GitHub Actions with org / user `littletuna4`, repository `reqlan`, workflow filename `deploy-npm.yml`, allowed action `npm publish`. Package `repository.url` must match `https://github.com/littletuna4/reqlan.git`. Provenance attestations are generated automatically for public packages from this public repo. Bootstrap: first publish of each scoped package can be done locally ( you must be logged in to npm as an `@reqlan` org member ) with `pnpm --filter @reqlan/language publish --access public --no-git-checks`, then platform packages, then analytical, then cli, then mcp — or wait for the trusted-publisher CI path after packages exist and Trusted Publisher is configured. Note: Packages must be `private: true` to skip local `changeset publish` ( `pnpm run release:npm` ), as with `reqlan-extension`. Platform packages are in the Changesets `ignore` list ( `@reqlan/analytical-*` ). Git `@reqlan/analytical` does not list them as `optionalDependencies`. ["../../scripts/prepare-native-packages.mjs"] `--publish-versions` writes pinned optionalDependencies for the npm checkout only. CI publishes platform packages per-package after binaries are built and does not use `changeset publish` for those tarballs. Published packages declare `publishConfig.access: public`. Trusted Publisher is configured on npmjs. com for each `@reqlan/analytical-<platform>-<arch>` package | 0.266 | |
| prerelease_tests | done | JS / TS package tests ( `pnpm run test:js` ) run after the shared TypeScript compile ( `pnpm run build:tsc` ) from this git checkout. GitHub CI runs them in the same job as crate tests and ["../core_analysis/check.rq".check], after that compile ( ["./distribution.rq".ci_gate] ). This job runs on every pull request and on main before versioning. Host native addon is required because analytical and language tests load `reqlan-napi`. The host release build compiles `reqlan-napi` only. Crate tests compile `reqlan-lsp`. That binary ships in the VSIX, not in this host package. Azure runs `pnpm run test:js` before VSIX publish ( [extension_distribution] ). Local `pnpm run test` runs `test:js` then `test:rust` ( ["../core_analysis/rust_port.rq".rust_crate_layout] ). The implementation lives in ["../../.github/workflows/ci.yml"]; ["../../.github/workflows/release.yml"] calls it with `workflow_call` as part of ["./distribution.rq".ci_gate]. Related: ["../core_analysis/check.rq".check_meta_implementation] | 0.069 | |
| stopgap | Stopgap distribution is at https://marketplace.visualstudio.com/manage/publishers/reqlan | 0.040 | ||
| repo_license | done | The repository root must declare the same licence as the publishable packages and crates. SPDX id: `AGPL-3.0-only`. The root must hold a `LICENSE` file with the GNU Affero General Public License version 3 text. The extension package `LICENSE` must use the same text as the root `LICENSE`. Package metadata must set `"license": "AGPL-3.0-only"` for the workspace root and for every publishable package under `packages/`. The Rust workspace must set `license = "AGPL-3.0-only"` in ["../../crates/Cargo.toml"]. | 0.040 |
Reference labels
"../../package.json", "../package.json", ../../package.json, ../package.json