wild-semantic-layer

A small PNPM monorepo for @madebywild/semantic-layer: a Dendron-style semantic documentation layer that validates a Markdown vault like source code.

The package provides:

• semantic-layer check - validate frontmatter, hierarchy, schemas, wikilinks, TypeScript/JavaScript symbol references, freshness, and configured invariants.
• semantic-layer index - regenerate vault/HIERARCHY.md, vault/.semantic-layer/code-refs.json, and the single-file SQLite vault index.
• semantic-layer init - scaffold a working vault and config.
• semantic-layer refine - stage, list, promote, or reject evolutionary self-improvement refinement candidates.
• semantic-layer search - full-text + vector search over the vault index.
• semantic-layer graph - explore backlinks, hierarchy, code impact, and cycles.

See the package README for the consumer-facing reference: packages/semantic-layer/README.md.

Agent Prompt Fragment

### Semantic Layer

Pre task:

- If `vault/HIERARCHY.md` is missing or stale, run `semantic-layer index`.
- Read `vault/HIERARCHY.md` first, then open only the `vault/*.md` notes relevant
  to the task. Each row carries a rough token estimate; for large notes, prefer
  `semantic-layer search "<query>" --json` to load only the matching section
  instead of the whole note.
- Follow wikilinks and `code_refs` from relevant notes before changing code.

Post task:

- Create, update, or delete `vault/*.md` notes and `*.schema.yml` files for any
  behavior, API, architecture, or operational knowledge changed by the task.
- Split notes that have grown large (a few hundred lines or more) into dotted
  sub-notes (for example `system.architecture.auth.md`) interlinked with
  wikilinks, keeping the parent note as a short overview that links down.
- Keep frontmatter current, including `last_verified`, `ttl_days`, `code_refs`,
  wikilinks, schema children, and configured external invariants.
- Stage significant non-assistant inputs with `semantic-layer refine stage` when
  they may refine the graph but should not be trusted directly yet.
- Promote staged refinements only after updating the trusted vault, then reject
  shallow, faulty, secret-bearing, or obsolete staged inputs with a reason.
- Run `semantic-layer check` and `semantic-layer index`; do not hand off until
  both pass or the exact failures are reported.

Workspace

packages/semantic-layer  reusable package and CLI
apps/demo                live consumer app with a real vault
tests/unit               focused rule and helper coverage
tests/integration        source-level API workflow coverage
tests/integration-container  integration suite on supported Linux/Node runtimes
tests/e2e                blackbox CLI/package tests using Testcontainers

Commands

pnpm install
pnpm build
pnpm demo
pnpm test
pnpm test:coverage
pnpm test:e2e
pnpm check
pnpm check:release

Use PNPM 11.1.1, as declared in package.json. pnpm demo builds the package, validates and indexes the demo vault, then runs the demo app.

pnpm test runs the Vitest workspace. pnpm test:coverage runs unit and integration tests with coverage thresholds against packages/semantic-layer/src. pnpm check runs formatting, linting, typecheck, measured coverage, the e2e package test, and the demo showcase. Release work additionally runs pnpm check:release, which repeats those gates and adds the Linux container integration matrix.

Deployment

The package is published to npm as @madebywild/semantic-layer by .github/workflows/publish.yml.

Publishing and GitHub releases are driven by semver git tags:

• merge or push the version bump to main
• create a semver tag on that main commit, such as v0.1.0
• push the tag with git push origin v0.1.0

The workflow installs dependencies with PNPM 11.1.1 on Node.js 24, runs the full pnpm check release gate, builds packages/semantic-layer, checks whether the current package.json version already exists on npm, and publishes only missing versions from semver tag pushes with pnpm publish --access public --no-git-checks. The release tag must match v0.0.0 format and must equal the package version, for example package version 0.1.0 must be published from tag v0.1.0. The tagged commit must already be contained in origin/main.

After the npm publish step succeeds, or if that exact npm version already exists, the workflow creates the matching GitHub Release from the same tag with generated release notes. Do not create a GitHub Release manually first; the git tag is the release source of truth.

The workflow expects the repository secret NPM_TOKEN to contain an npm token with publish access to the @madebywild scope. Bump packages/semantic-layer/package.json before publishing a new release; npm will not accept republishing an existing version. The package is configured for public scoped publishing through publishConfig.access: public.