Appearance
Types for an existing project
You end with a law whose types cover the folders of an existing project. No file falls in two types. One type takes its files by their text. lawcheck explain says for any path which type it has, and why.
The outputs below come from a repository with scripts/release.mjs and five files under src/:
src/api/orders.ts;src/core/price.ts;src/core/price.test.ts, which testssrc/core/price.ts;src/db/orders.ts;src/generated/schema.ts, which a code generator writes.
Its top folder is the root of the law: you ran lawcheck init there (The first type and the first rule).
1. See the files without a type
text
$ lawcheck explain .output
./ 8 files
no type 8 filesexplain with a folder counts the files git lists below it, by type. The two files init wrote count too.
2. Describe the folders as types
Give each folder of src/ a type. A type under the types key of another type is a subtype. Lawcheck tests a subtype on a file only after the file matched its parent. Under the parent source, api takes the .ts files of src/api/ and no other file. Write this into .lawcheck/law.yaml:
yaml
lawcheck: 0.1.0
types:
source:
about: Everything that ships.
paths: ["src/**/*.ts"]
types:
api:
about: The HTTP handlers.
paths: ["src/api/**"]
core:
about: The business logic.
paths: ["src/core/**"]
db:
about: The database access.
paths: ["src/db/**"]
script:
about: The release scripts.
paths: ["scripts/**"]3. See the files of each type
text
$ lawcheck explain .output
./ 8 files
source 1 file
api 1 file
core 2 files
db 1 file
script 1 file
no type 2 filesThe file of source is src/generated/schema.ts. It matches src/**/*.ts and no subtype. The two files without a type are the files of .lawcheck/. No rule judges a file without a type.
4. See why a file has its type
text
$ lawcheck explain src/api/orders.tsoutput
src/api/orders.ts
type: api (source > api) The HTTP handlers.
matched: source by "src/**/*.ts", api by "src/api/**"
may use: any file; no type on the way up has may_use
rules: none
waivers: noneThe type line gives the chain from the top-level type down to the type of the file: source > api. The matched line gives the pattern that matched at each level. The rules of every type in the chain bind the file.
5. List the files of one type
text
$ lawcheck explain --type coreoutput
type core (source > core) The business logic.
paths: src/core/**
may use: any file; no type on the way up has may_use
rules: none
subtypes: none
files: 2
src/core/price.test.ts
src/core/price.tscore holds the test of src/core/price.ts too. The next step gives the tests a type, because they need rules of their own.
6. Add a type for the tests
Add these lines at the end of .lawcheck/law.yaml, under types, beside source and script:
yaml
test:
about: The tests.
paths: ["src/**/*.test.ts"]7. Run a check
text
$ lawcheck checkoutput
lawcheck: ERROR 1 error
src/core/price.test.ts error[type-overlap] the file matches the types 'source' and 'test' of one level
why: a file has one type, so the rules that bind it are never in doubt
next: narrow the paths or content of the types that overlap in .lawcheck/law.yaml, then run lawcheck checksrc/core/price.test.ts matches the two top-level types source and test. A file has one type. Every run stops with exit 2 until one of the two types leaves the file out (type-overlap).
8. Leave the tests out of source
A pattern that starts with ! excludes the files it matches. Give source these paths:
yaml
paths: ["src/**/*.ts", "!src/**/*.test.ts"]9. See the type of the test
text
$ lawcheck explain src/core/price.test.tsoutput
src/core/price.test.ts
type: test (test) The tests.
matched: test by "src/**/*.test.ts"
may use: any file; no type on the way up has may_use
rules: none
waivers: none10. Leave the generated file out
The code generator writes src/generated/schema.ts again on every build, so a fix by hand in that file lasts until the next build. Leave the file out of the law with a second exclusion in the paths of source:
yaml
paths: ["src/**/*.ts", "!src/**/*.test.ts", "!src/generated/**"]11. See the generated file
text
$ lawcheck explain src/generated/schema.tsoutput
src/generated/schema.ts
type: none: no type's paths match it, so no rule judges it12. See the type of a file you have not written yet
explain takes a path that does not exist. It answers with the law a new file there would get:
text
$ lawcheck explain src/api/refunds.tsoutput
src/api/refunds.ts (does not exist yet)
type: api (source > api) The HTTP handlers.
matched: source by "src/**/*.ts", api by "src/api/**"
may use: any file; no type on the way up has may_use
rules: none13. Write a test beside the code
A test can sit beside the code, under a name that no pattern tells apart from the code. Write one such test, src/core/rounding.ts:
ts
import { test } from 'node:test';
import { price } from './price';
test('a price is a whole number', () => price);14. Give the tests beside the code a type by their text
With a content expression, a type takes only the files whose text matches it. Put such a type under the type that takes the file by its paths, because Lawcheck tests a subtype only on the files that matched its parent. In .lawcheck/law.yaml, replace the three lines of core with these:
yaml
core:
about: The business logic.
paths: ["src/core/**"]
types:
core-test:
about: The tests beside the business logic.
paths: ["src/core/**"]
content: "from 'node:test'"If you put the type with content beside core, every run stops with type-overlap. Both types of that level match the test, because core takes it by its paths alone.
15. See the type a file gets by its text
text
$ lawcheck explain src/core/rounding.tsoutput
src/core/rounding.ts
type: core-test (source > core > core-test) The tests beside the business logic.
matched: source by "src/**/*.ts", core by "src/core/**", core-test by "src/core/**" and content "from 'node:test'"
may use: any file; no type on the way up has may_use
rules: none
waivers: noneThe matched line names the pattern and the content that gave the file the type core-test. src/core/price.ts holds no from 'node:test'. It keeps the type core.
The law file describes every key of a type and every form of a pattern.
If it goes wrong
- Lawcheck prints
type-overlapfor two subtypes that match one file, such asapiandcore: add a!pattern to one of them, as Leave the tests out of source does. - Lawcheck prints
type-overlapfor a type withcontentand a type beside it: move the type withcontentunder the type that takes the file by its paths, as Give the tests beside the code a type by their text does. - Lawcheck prints
law-invalid, and the message says the patternholds ** beside other characters in one segment:**stands for a whole segment. Writesrc/api/**/*.ts, neversrc/api/**.ts. - A file of
src/api/v1/getssourceand noapi, with the patternsrc/api/*:*stops at a/. Writesrc/api/**. explainsays the file matches the paths of a type but not its content: the type has acontentexpression. The text of the file does not match it.explainanswersgit ignores it, so Lawcheck never sees it:.gitignorenames the file. No type takes a file that git ignores.explain --typeprints the errorusage, and the message ends with the nearest type id, such as(did you mean 'core'?):--typetakes the id of a type of the law.