Appearance
Forbid one layer to use another
You end with a law in which the business logic may not import the HTTP handlers. lawcheck check fails on the line that imports one.
The outputs below come from a repository with three files:
src/api/orders.tsimportssrc/core/price.ts;src/core/price.ts;src/core/orders.sql.
The build writes src/generated/schema.ts, into a folder that .gitignore names. The law gives src/api/ the type api and src/core/ the type core (Types for an existing project).
1. Give core a may_use list
may_use names the types whose files a type's files may use. The files of a type may use each other only when its list names the type itself. Add the list to core in .lawcheck/law.yaml:
yaml
lawcheck: 0.1.0
types:
api:
about: The HTTP handlers.
paths: ["src/api/**"]
core:
about: The business logic.
paths: ["src/core/**"]
may_use: [core]api has no list. Its files may use any file. A type written inside another type is its subtype. A subtype without a list takes the list of its nearest parent that has one.
2. See the list a file gets
text
$ lawcheck explain src/core/price.tsoutput
src/core/price.ts
type: core (core) The business logic.
matched: core by "src/core/**"
may use: core
uses: read as typescript
rules: none
waivers: noneThe uses line says Lawcheck reads the imports of this file as TypeScript.
3. Write a file that breaks the list
Write src/core/discount.ts:
ts
import { order } from '../api/orders';
export const discount = order;4. Check it
text
$ lawcheck check src/core/discount.tsoutput
lawcheck: FAIL 1 error in 1 named file
src/core/discount.ts:1 error[forbidden-use] core may not use api (src/api/orders.ts); its may_use is [core]
why: a type's may_use names every type its files may use
next: fix src/core/discount.ts:1The finding gives four things:
- the line of the import;
- the type of the file;
- the type and the path of the file it imports;
- the
may_uselist ofcore.
check exits 1. lawcheck check src/core/discount.ts judges the file you name, changed or not. On a branch, lawcheck check without a path judges the file once it differs from the base.
5. Fix the import
You can fix the import in two ways:
- keep the list and take the import out;
- write
may_use: [core, api], ifcoremay useapiafter all.
This example keeps the list. Write src/core/discount.ts again, without the import of api:
ts
import { price } from './price';
export const discount = price;6. Check it again
text
$ lawcheck check src/core/discount.tsoutput
lawcheck: PASS 1 named file7. Add an import of a file git does not list
Add an import of the schema the build writes:
ts
import { price } from './price';
import { schema } from '../generated/schema';
export const discount = price + schema;8. Check it with the new import
text
$ lawcheck check src/core/discount.tsoutput
lawcheck: PASS 1 named file, 1 unresolved useThe import points into the repository. git lists no file there, since .gitignore names src/generated/. Lawcheck cannot tell which type the use reaches. It counts such a use as unresolved. An unresolved use never fails a run, since Lawcheck checks it against no may_use list. The first line of the output gives the count.
9. List the unresolved uses
text
$ lawcheck check src/core/discount.ts --jsonThe unresolved list of the output holds the use:
output
"unresolved": [
{
"file": "src/core/discount.ts",
"line": 2,
"what": "../generated/schema",
"answer": "none",
"reason": "unfollowed",
"candidates": [],
"debt": false
}
],unfollowed means the use names a place of the repository that holds no file git lists. Languages and uses lists every answer and reason. A use of an installed package or of the standard library points outside the repository. Lawcheck does not count such a use.
10. Check the whole folder
text
$ lawcheck check src/coreoutput
lawcheck: PASS 1 warning in 3 named files, 1 unresolved use
.lawcheck/law.yaml:7 warning[uses-not-read] 1 file of type core is not read for uses: 1 .sql
why: a restriction that cannot be checked is not shown as keptLawcheck reads the uses of twelve languages. A reader is the part of Lawcheck that reads the uses of one language. Lawcheck has no reader for .sql files. It cannot check a .sql file of core against the list. It warns once for the type, at the line of core in the law. The warning never fails a run.
11. Leave the .sql files out of core
Give core these paths:
yaml
paths: ["src/core/**", "!src/core/**/*.sql"]12. Check the folder again
text
$ lawcheck check src/coreoutput
lawcheck: PASS 3 named files, 1 unresolved useAfter this step, the .sql files have no type. Lawcheck checks them against no may_use list. A script rule can check what they use (Write a script rule).
If it goes wrong
- The finding says
core may not use src/util/x.ts, which has no type: amay_uselist names types, so it cannot allow a file without a type. Give the file a type and list that type, or move the file under a type the list names. - A file of
coreuses another file ofcore, and the check fails: the list must namecoreitself. - An import you expected to fail passes, and the first line counts no unresolved use: the readers miss some forms, such as
import()of a variable. Languages and uses lists them. - An unresolved use with the answer
ambiguous: the use could name several files of different types. The listcandidatesnames those files. Lawcheck judges the use against none of them.
Next: Write a script rule