allowedExternalfunctionno test imports itfunction allowedExternal(allowed: readonly Allowed[], specifier: string): booleanWhether a specifier is one of the packages a unit may import.
The import check of Kanon (commons 0033-kanon FR-004, FR-006, FR-011): given a table and the files of a library, every import of every file as data: which unit each file is in, and a finding for each import that does not follow the table. It reads every import, relative or by package name, because an import by package name is invisible to a check of relative imports; it resolves the library's own package name through exports, as Node and the compiler do. Lifted from the checks of commons/data and commons/headless, which each kept a table of their own.
Pure: it is given the files and the exports map and returns findings, which a program holds against a baseline. A file in no unit of the table is layers/unclassified, so that a surface or a dialect cannot appear without its row saying what it may import.
import { importFindings } from "@intellectual-frontiers/kanon";
const table = {
package: "@intellectual-frontiers/x",
units: [
{ folder: "src/governance/", layer: "governance" },
{ folder: "src/logical/", layer: "logical" },
],
} as const;
importFindings(table, [{ path: "src/governance/a.ts", text: 'import { b } from "@intellectual-frontiers/x/logical";\n' }], { "./logical": "./src/logical/mod.ts" }).map((f) => f.rule); // ["layers/above"]allowedExternalfunctionno test imports itfunction allowedExternal(allowed: readonly Allowed[], specifier: string): booleanWhether a specifier is one of the packages a unit may import.
ExportsMaptypetype ExportsMap = Readonly<Record<string, string | { readonly [condition: string]: string }>>;An exports map: each subpath to its target, a string or an object of conditions of strings.
escapesRootfunctionno test imports itfunction escapesRoot(from: string, specifier: string): booleanWhether a relative specifier climbs out of the library's root from the file that imports it.
Findingtypeno test imports ittype Finding = {
readonly rule: Rule;
readonly file: string;
readonly line: number;
readonly message: string;
readonly key: string;
};A finding: its code, the file and line, one sentence, and a key that a baseline of findings can hold (<rule> <file> <about>).
familyOffunctionfunction familyOf(rule: Rule): "family" | "instances" | "kanon" | "layers" | "plugins"The family of a code: the import check's or the model's; an exhaustive match, so that a code added to the union fails to compile here until it is placed.
findingfunctionno test imports itfunction finding(rule: Rule, file: string, line: number, message: string, about?: string | undefined): FindingMake a finding with its key.
importFindingsfunctionfunction importFindings(table: Table, files: readonly SourceFile[], exportsMap: Readonly<Record<string, string | { readonly [condition: string]: string; }>>): readonly Finding[]Every finding of the import check over a library's files (0033-kanon FR-011).
| Parameter | What it is |
|---|---|
table | the library's table |
files | each file of the library the check reads, its path from the library with / and its text |
exportsMap | the exports of the library's package.json, each subpath (./logical) to its file (./src/logical/mod.ts) |
Returns: the findings, in the order of the files
Placedtypeno test imports ittype Placed = { readonly name: string; readonly unit: Unit };The unit a file is in, as the table holds it: the unit's name (its folder, and for an instance the folder under it) and the row it comes from.
resolveImportfunctionno test imports itfunction resolveImport(from: string, specifier: string): stringThe path a relative specifier names, from the file that imports it.
RULE_SUMMARYconstconst RULE_SUMMARY: Readonly<Record<Rule, string>>What each code means, in a sentence: a registry with an entry for every code of the closed union, which the compiler holds complete.
RULESconstconst RULES: readonly ["layers/unclassified", "layers/relative", "layers/private", "layers/external", "layers/above", "layers/around", "layers/cycle", "instances/sibling", "instances/undeclared", "plugins/inverted", "plugins/undeclared", "plugins/contract", "family/name", "kanon/dropped", "kanon/kind", "kanon/annotation", "kanon/dangling", "kanon/relation-layer", "kanon/duplicate-id"]The codes in one list, for a program that walks them.
Ruletypeno test imports ittype Rule =
| "layers/unclassified"
| "layers/relative"
| "layers/private"
| "layers/external"
| "layers/above… (434 characters)type Rule =
| "layers/unclassified"
| "layers/relative"
| "layers/private"
| "layers/external"
| "layers/above"
| "layers/around"
| "layers/cycle"
| "instances/sibling"
| "instances/undeclared"
| "plugins/inverted"
| "plugins/undeclared"
| "plugins/contract"
| "family/name"
| "kanon/dropped"
| "kanon/kind"
| "kanon/annotation"
| "kanon/dangling"
| "kanon/relation-layer"
| "kanon/duplicate-id";The codes of this check (0033-kanon FR-011); kanon/dropped is the check of a model's annotations (dropped.ts).
SourceFiletypetype SourceFile = { readonly path: string; readonly text: string };A file of the library: its path from the library's root with /, and its text.
Specifiertypeno test imports ittype Specifier = { readonly line: number; readonly specifier: string };An import of a file, with its line.
specifiersOffunctionfunction specifiersOf(text: string): readonly Specifier[]Every import of a file's text, relative or by name: static, side-effect, re-export and dynamic import(), import type included.
unitOffunctionfunction unitOf(table: Table, path: string): Placed | undefinedThe unit a file is in, from its path relative to the library with /; undefined where it is in none (layers/unclassified). The most specific folder wins.