@intentset/architecture 0.8.1 → 0.9.0

package/src/extract.ts

@@ -28,6 +28,10 @@
  * Anything this module cannot read is returned as a problem, never dropped:
  * a dynamic import with a computed specifier, or a token the scanner could
  * not terminate (invariant 6).
+ *
+ * Beside each reference it records the names the reference takes, and beside
+ * the file the names the file exports itself, so a name taken through an
+ * entrypoint or a barrel can be followed to the file that defines it (VSA006).
  */
 import { LanguageVariant, SyntaxKind } from "typescript/unstable/ast";
 import { computeLineStarts, createScanner, tokenIsIdentifierOrKeyword } from "typescript/unstable/ast/scanner";
@@ -44,6 +48,37 @@ export interface RawImport {
   reexport: boolean;
   /** `export * from "x"` or `export * as ns from "x"`. */
   wildcard: boolean;
+  /**
+   * The names it takes from the module, in source order. `name` is the name
+   * in that module (`default` for a default import), `as` the local binding
+   * or, for a re-export, the name exported here. A name of `*` takes every
+   * name the module exports: a namespace import, `import X = require("x")`,
+   * `export * as ns from "x"`, a dynamic import or require (with `as` empty),
+   * and `export * from "x"` (with `as` `*`, every name but `default` under
+   * its own). A side-effect import takes none.
+   */
+  names: TakenName[];
+}
+
+export interface TakenName {
+  name: string;
+  as: string;
+  /** `import type`, `export type`, or the specifier itself marked `type`. */
+  typeOnly: boolean;
+}
+
+/** What a file exports of its own, rather than from another module by `export ... from`. */
+export interface LocalExports {
+  /** Names declared and exported here: `export function f`, `export const a`, `export default ...`. */
+  declared: string[];
+  /**
+   * `export { a as b }` with no module, and `export default a`: `name` is the
+   * local binding, `as` the exported name. Whether the binding was imported,
+   * which makes it a re-export, is for the reader of the file's imports.
+   */
+  bindings: TakenName[];
+  /** An export this reader cannot name: `export =`, `module.exports`, a destructured declaration. */
+  opaque: boolean;
 }
 
 export interface ExtractProblem {
@@ -54,6 +89,12 @@ export interface ExtractProblem {
 export interface Extraction {
   imports: RawImport[];
   problems: ExtractProblem[];
+  exports: LocalExports;
+  /**
+   * The line of the file's first JSX element or fragment, or null. Under the automatic runtime a file that renders
+   * needs no import, so this is the only sign of it (TS008).
+   */
+  jsx: number | null;
 }
 
 interface Token {
@@ -348,10 +389,14 @@ function describe(kind: SyntaxKind): string {
   }
 }
 
-/** Extract every module reference from one file. */
+/** Words that open a declaration after `export default` rather than name a binding. */
+const DECLARATION_WORDS = new Set(["function", "class", "async", "abstract", "interface", "enum", "namespace"]);
+
+/** Extract every module reference from one file, with the names each takes and the names the file exports itself. */
 export function extractImports(path: string, text: string): Extraction {
   const { tokens, problems } = tokenize(path, text);
   const imports: RawImport[] = [];
+  const exports: LocalExports = { declared: [], bindings: [], opaque: false };
   const consumed = new Set<number>();
 
   const word = (i: number, text?: string): boolean => {
@@ -365,6 +410,8 @@ export function extractImports(path: string, text: string): Extraction {
   const add = (i: number, fields: Omit<RawImport, "specifier" | "line">) => {
     imports.push({ specifier: tokens[i].value, line: tokens[i].line, ...fields });
   };
+  /** A name as written in a specifier list: an identifier, a keyword such as `default`, or a string. */
+  const nameAt = (i: number): string | null => (word(i) ? tokens[i].text : isString(i) ? tokens[i].value : null);
   /** Index of the token closing the bracket opened at i, or tokens.length. */
   const closing = (i: number, open: SyntaxKind, close: SyntaxKind): number => {
     let depth = 0;
@@ -374,27 +421,82 @@ export function extractImports(path: string, text: string): Extraction {
     }
     return tokens.length;
   };
+  /**
+   * The specifiers between braces, `a`, `type B`, `c as d`, `"e-f" as g`:
+   * `name` is the first name, `as` the second or the first again.
+   */
+  const specifiers = (open: number, close: number, typeOnly: boolean): TakenName[] => {
+    const out: TakenName[] = [];
+    let k = open + 1;
+    while (k < close) {
+      let end = k;
+      while (end < close && !is(end, SyntaxKind.CommaToken)) end++;
+      let at = k;
+      let typed = typeOnly;
+      if (word(at, "type") && end - at > 1 && !(word(at + 1, "as") && end - at === 3)) {
+        typed = true;
+        at++;
+      }
+      const name = nameAt(at);
+      if (name !== null) {
+        const alias = word(at + 1, "as") && at + 2 < end ? nameAt(at + 2) : null;
+        out.push({ name, as: alias ?? name, typeOnly: typed });
+      }
+      k = end + 1;
+    }
+    return out;
+  };
   /** Named elements between braces: true when every one is written `type X`. */
   const allTyped = (open: number, close: number): boolean => {
-    let count = 0;
-    let typed = 0;
-    let start = true;
-    for (let k = open + 1; k < close; k++) {
-      if (is(k, SyntaxKind.CommaToken)) {
-        start = true;
-        continue;
-      }
-      if (start) {
-        count++;
-        if (word(k, "type") && word(k + 1) && !word(k + 1, "as")) typed++;
-        start = false;
+    const list = specifiers(open, close, false);
+    return list.length > 0 && list.every((item) => item.typeOnly);
+  };
+  /** The bindings of `import d, * as ns, { a } from`, written between `start` and the `from` at `end`. */
+  const importBindings = (start: number, end: number, typeOnly: boolean): TakenName[] => {
+    const out: TakenName[] = [];
+    for (let k = start; k < end; k++) {
+      if (is(k, SyntaxKind.OpenBraceToken)) {
+        const close = closing(k, SyntaxKind.OpenBraceToken, SyntaxKind.CloseBraceToken);
+        out.push(...specifiers(k, close, typeOnly));
+        k = close;
+      } else if (is(k, SyntaxKind.AsteriskToken) && word(k + 1, "as") && word(k + 2)) {
+        out.push({ name: "*", as: tokens[k + 2].text, typeOnly });
+        k += 2;
+      } else if (word(k)) {
+        out.push({ name: "default", as: tokens[k].text, typeOnly });
       }
     }
-    return count > 0 && typed === count;
+    return out;
   };
   /** A call such as `import(x)` or `require(x)` that is really a method declaration `import(x) { ... }`. */
   const isMethod = (open: number): boolean =>
     is(closing(open, SyntaxKind.OpenParenToken, SyntaxKind.CloseParenToken) + 1, SyntaxKind.OpenBraceToken);
+  const every = (typeOnly: boolean): TakenName[] => [{ name: "*", as: "", typeOnly }];
+
+  /** `export <declaration>` with its name at i, after `export` and any `declare`. Returns false when it is not one. */
+  const declaration = (i: number): boolean => {
+    let k = i;
+    for (;;) {
+      if (word(k, "declare") || word(k, "async") || word(k, "abstract")) k++;
+      else if (word(k, "const") && word(k + 1, "enum")) k++;
+      else break;
+    }
+    if (word(k, "function")) {
+      k++;
+      if (is(k, SyntaxKind.AsteriskToken)) k++;
+    } else if (["class", "interface", "enum", "namespace", "module", "import"].some((kind) => word(k, kind))) k++;
+    else if (word(k, "type") && word(k + 1) && !is(k + 1, SyntaxKind.OpenBraceToken)) k++;
+    else if (word(k, "const") || word(k, "let") || word(k, "var") || word(k, "using")) {
+      k++;
+      if (is(k, SyntaxKind.OpenBraceToken) || is(k, SyntaxKind.OpenBracketToken)) {
+        exports.opaque = true;
+        return true;
+      }
+    } else return false;
+    if (!word(k)) return false;
+    exports.declared.push(tokens[k].text);
+    return true;
+  };
 
   for (let i = 0; i < tokens.length; i++) {
     if (consumed.has(i) || afterDot(i)) continue;
@@ -402,7 +504,8 @@ export function extractImports(path: string, text: string): Extraction {
     if (word(i, "import") && tokens[i].kind === SyntaxKind.ImportKeyword) {
       if (is(i + 1, SyntaxKind.OpenParenToken)) {
         if (isLiteral(i + 2) && (is(i + 3, SyntaxKind.CloseParenToken) || is(i + 3, SyntaxKind.CommaToken))) {
-          add(i + 2, { typeOnly: word(i - 1, "typeof"), dynamic: true, reexport: false, wildcard: false });
+          const typeOnly = word(i - 1, "typeof");
+          add(i + 2, { typeOnly, dynamic: true, reexport: false, wildcard: false, names: every(typeOnly) });
         } else if (!is(i + 2, SyntaxKind.CloseParenToken) && !isMethod(i + 1)) {
           problems.push({
             line: tokens[i].line,
@@ -432,12 +535,13 @@ export function extractImports(path: string, text: string): Extraction {
         j++;
       }
       if (isString(j)) {
-        add(j, { typeOnly, dynamic: false, reexport: false, wildcard: false });
+        add(j, { typeOnly, dynamic: false, reexport: false, wildcard: false, names: [] });
         continue;
       }
       if (word(j) && is(j + 1, SyntaxKind.EqualsToken)) {
         if (word(j + 2, "require") && is(j + 3, SyntaxKind.OpenParenToken) && isString(j + 4)) {
-          add(j + 4, { typeOnly, dynamic: false, reexport: false, wildcard: false });
+          const names = [{ name: "*", as: tokens[j].text, typeOnly }];
+          add(j + 4, { typeOnly, dynamic: false, reexport: false, wildcard: false, names });
           consumed.add(j + 2);
         }
         continue;
@@ -454,7 +558,8 @@ export function extractImports(path: string, text: string): Extraction {
         }
         if (word(k, "from") && isString(k + 1)) {
           const typed = typeOnly || (typedNamed && !hasPlainBinding);
-          add(k + 1, { typeOnly: typed, dynamic: false, reexport: false, wildcard: false });
+          const names = importBindings(j, k, typeOnly);
+          add(k + 1, { typeOnly: typed, dynamic: false, reexport: false, wildcard: false, names });
           i = k + 1;
           break;
         }
@@ -475,26 +580,62 @@ export function extractImports(path: string, text: string): Extraction {
       }
       if (is(j, SyntaxKind.AsteriskToken)) {
         let k = j + 1;
+        const as = word(k, "as") && nameAt(k + 1) !== null ? (nameAt(k + 1) as string) : "*";
         if (word(k, "as")) k += 2;
         if (word(k, "from") && isString(k + 1)) {
-          add(k + 1, { typeOnly, dynamic: false, reexport: true, wildcard: true });
+          const names = [{ name: "*", as, typeOnly }];
+          add(k + 1, { typeOnly, dynamic: false, reexport: true, wildcard: true, names });
           i = k + 1;
         }
         continue;
       }
       if (is(j, SyntaxKind.OpenBraceToken)) {
         const close = closing(j, SyntaxKind.OpenBraceToken, SyntaxKind.CloseBraceToken);
+        const names = specifiers(j, close, typeOnly);
         if (word(close + 1, "from") && isString(close + 2)) {
-          add(close + 2, { typeOnly: typeOnly || allTyped(j, close), dynamic: false, reexport: true, wildcard: false });
+          add(close + 2, {
+            typeOnly: typeOnly || allTyped(j, close),
+            dynamic: false,
+            reexport: true,
+            wildcard: false,
+            names,
+          });
           i = close + 2;
+        } else {
+          exports.bindings.push(...names);
+          i = close;
         }
+        continue;
+      }
+      if (is(j, SyntaxKind.EqualsToken)) {
+        exports.opaque = true;
+        continue;
+      }
+      if (word(j, "default")) {
+        // `export default name;` exports a binding, which may be an import; anything else is declared here.
+        const named =
+          word(j + 1) &&
+          !DECLARATION_WORDS.has(tokens[j + 1].text) &&
+          (j + 2 >= tokens.length || is(j + 2, SyntaxKind.SemicolonToken) || tokens[j + 2].line > tokens[j + 1].line);
+        if (named) exports.bindings.push({ name: tokens[j + 1].text, as: "default", typeOnly: false });
+        else exports.declared.push("default");
+        continue;
       }
+      if (!word(j, "as")) declaration(j);
+      continue;
+    }
+
+    if (
+      (word(i, "module") && is(i + 1, SyntaxKind.DotToken) && word(i + 2, "exports")) ||
+      (word(i, "exports") && (is(i + 1, SyntaxKind.DotToken) || is(i + 1, SyntaxKind.OpenBracketToken)))
+    ) {
+      exports.opaque = true;
       continue;
     }
 
     if (word(i, "require") && is(i + 1, SyntaxKind.OpenParenToken) && !word(i - 1, "function")) {
       if (isLiteral(i + 2) && is(i + 3, SyntaxKind.CloseParenToken)) {
-        add(i + 2, { typeOnly: false, dynamic: true, reexport: false, wildcard: false });
+        add(i + 2, { typeOnly: false, dynamic: true, reexport: false, wildcard: false, names: every(false) });
       } else if (!is(i + 2, SyntaxKind.CloseParenToken) && !isMethod(i + 1)) {
         problems.push({
           line: tokens[i].line,
@@ -504,7 +645,12 @@ export function extractImports(path: string, text: string): Extraction {
     }
   }
 
-  return { imports, problems };
+  // A nested element is pushed before the one around it, so the first is the lowest line, not the first token.
+  let jsx: number | null = null;
+  for (const token of tokens) {
+    if (token.kind === SyntaxKind.JsxElement && (jsx === null || token.line < jsx)) jsx = token.line;
+  }
+  return { imports, problems, exports, jsx };
 }
 
 /** What an Amplify schema declares at its top level (profile §9, AMP009). */

package/src/finding.ts

@@ -19,6 +19,18 @@ export interface Finding {
   paths: string[];
   /** File-level and slice-level edges the finding concerns. */
   edges: SubjectEdge[];
+  /** For a finding about one import: what the baseline holds it by, one name at a time (VSA §9). */
+  taken?: Taken;
+}
+
+/** One import, as a baseline identifies it: how it imports, what it targets and the names it takes. */
+export interface Taken {
+  /** `import`, `re-export` or `dynamic`. */
+  kind: string;
+  /** The file it resolves to, or the package specifier. */
+  to: string;
+  /** `name`, `type name` for a type-only one, `*` for every name; empty for a side-effect import. */
+  names: string[];
 }
 
 export interface FindingFields {
@@ -32,6 +44,7 @@ export interface FindingFields {
   remediation: string;
   paths?: string[];
   edges?: SubjectEdge[];
+  taken?: Taken;
 }
 
 /** One diagnostic, members in contract order, optional members present only when known. */
@@ -49,7 +62,12 @@ export function finding(fields: FindingFields): Finding {
   };
   const paths = new Set(fields.paths ?? []);
   if (fields.path !== null) paths.add(fields.path);
-  return { diagnostic, paths: [...paths].sort(), edges: fields.edges ?? [] };
+  return {
+    diagnostic,
+    paths: [...paths].sort(),
+    edges: fields.edges ?? [],
+    ...(fields.taken !== undefined ? { taken: fields.taken } : {}),
+  };
 }
 
 /** "1 file" / "3 files". */

package/src/imports.ts

@@ -4,7 +4,8 @@
  * for a package outside the repository, the specifier alone. What could not
  * be read or resolved is returned beside the edges, never folded into them.
  */
-import { extractImports } from "./extract.ts";
+import { extractImports, type LocalExports, type TakenName } from "./extract.ts";
+import type { Taken } from "./finding.ts";
 import { isCode } from "./paths.ts";
 import { compareStrings } from "./patterns.ts";
 import type { Resolver, Via } from "./resolve.ts";
@@ -24,6 +25,8 @@ export interface ImportEdge {
   via: Via;
   /** Resolved through a `*` alias, an exports pattern or a package without exports (TS006). */
   wildcardAlias: boolean;
+  /** The names it takes from the target (`RawImport.names`). */
+  names: TakenName[];
 }
 
 export interface UnresolvedImport {
@@ -36,15 +39,23 @@ export interface UnresolvedImport {
 export interface ImportGraph {
   edges: ImportEdge[];
   unresolved: UnresolvedImport[];
+  /** What each code file exports of its own, by path. */
+  exports: Map<string, LocalExports>;
+  /** The line of the first JSX element in each file that renders one, by path. */
+  jsx: Map<string, number>;
 }
 
 /** Build the graph over every code file in `files` (already filtered of ignored paths). */
 export function buildImportGraph(files: ReadonlyMap<string, string>, resolver: Resolver): ImportGraph {
   const edges: ImportEdge[] = [];
   const unresolved: UnresolvedImport[] = [];
+  const exported = new Map<string, LocalExports>();
+  const rendered = new Map<string, number>();
   for (const path of [...files.keys()].sort(compareStrings)) {
     if (!isCode(path)) continue;
-    const { imports, problems } = extractImports(path, files.get(path) as string);
+    const { imports, problems, exports, jsx } = extractImports(path, files.get(path) as string);
+    exported.set(path, exports);
+    if (jsx !== null) rendered.set(path, jsx);
     for (const problem of problems) {
       unresolved.push({ path, line: problem.line, specifier: null, message: problem.message });
     }
@@ -70,8 +81,19 @@ export function buildImportGraph(files: ReadonlyMap<string, string>, resolver: R
         wildcardExport: raw.wildcard,
         via: resolution.via,
         wildcardAlias: resolution.wildcard,
+        names: raw.names,
       });
     }
   }
-  return { edges, unresolved };
+  return { edges, unresolved, exports: exported, jsx: rendered };
+}
+
+/** The import as a baseline identifies it (VSA §9): one entry per name it takes. */
+export function takenBy(edge: ImportEdge): Taken {
+  const names = edge.names.map((taken) => `${taken.typeOnly || edge.typeOnly ? "type " : ""}${taken.name}`);
+  return {
+    kind: edge.reexport ? "re-export" : edge.dynamic ? "dynamic" : "import",
+    to: edge.to ?? edge.specifier,
+    names: [...new Set(names)].sort(compareStrings),
+  };
 }

package/src/index.ts

@@ -7,14 +7,22 @@
 export { AREA_REVIEW_REQUIRED, areaOf, backendAreaOf, checkAreas, isAreaSchema } from "./areas.ts";
 export {
   applyBaseline,
+  type BaselineComparison,
   type BaselineEntry,
+  baselineKeys,
+  type BaselineSubject,
+  compareBaselines,
+  describeEntry,
+  FINGERPRINT_V2,
   fingerprint,
   type Mode,
   parseBaseline,
   plainMessage,
+  STALE_ENTRY_CODE,
+  staleEntryDiagnostics,
   writeBaseline,
 } from "./baseline.ts";
-export { type BoundaryResult, checkBoundaries, checkUnclassified, type SliceEdge } from "./boundaries.ts";
+export { type BoundaryResult, checkBoundaries, checkJsx, checkUnclassified, type SliceEdge } from "./boundaries.ts";
 export {
   type ArchitectureResult,
   type ArchitectureSummary,
@@ -32,6 +40,7 @@ export {
   MAX_AREAS,
   readArchitectureConfig,
   resolveConfig,
+  UI_FRAMEWORKS,
 } from "./config.ts";
 export { checkDependencies, shortestCycle, stronglyConnected } from "./dependencies.ts";
 export {
@@ -46,6 +55,7 @@ export {
 export {
   type Extraction,
   extractImports,
+  type LocalExports,
   extractSchema,
   findCalls,
   type RawImport,
@@ -54,10 +64,12 @@ export {
   type SchemaExtraction,
   type SchemaKind,
   type SchemaReference,
+  type TakenName,
 } from "./extract.ts";
-export type { Finding, SubjectEdge } from "./finding.ts";
-export { buildImportGraph, type ImportEdge, type ImportGraph, type UnresolvedImport } from "./imports.ts";
-export { inSeam, isPure, layerAllows, layerOf, purePatterns, seamPatterns } from "./layers.ts";
+export type { Finding, SubjectEdge, Taken } from "./finding.ts";
+export { buildImportGraph, type ImportEdge, type ImportGraph, takenBy, type UnresolvedImport } from "./imports.ts";
+export { type Definition, NameIndex, type Origin } from "./names.ts";
+export { fileLayer, inSeam, isPure, layerAllows, layerOf, purePatterns, seamPatterns } from "./layers.ts";
 export { checkOwnership } from "./ownership.ts";
 export { type ArchitectureSubjectSource, type SubjectSourceOptions, subjectSource } from "./subject-source.ts";
 export { expandClaims, matchAny, matchPattern, validatePattern } from "./patterns.ts";

package/src/layers.ts

@@ -30,6 +30,24 @@ export function layerOf(slice: SliceInfo, path: string): LayerOf {
   return { layer: null, reason: matches.length === 0 ? "none" : "ambiguous", candidates: matches };
 }
 
+/** The reference layout's folders for the layers a slice that declares none still has (profile §1). */
+const FALLBACK_LAYERS: [string, string][] = [
+  ["external", "client"],
+  ["policy", "domain/policies"],
+  ["model", "domain/models"],
+];
+
+/**
+ * The layer a file is in for the package and JSX rules (TS007, TS008): the one layer it is declared in, or, for a
+ * slice that declares no layers, its client/, domain/policies/ or domain/models/ folder under the entrypoint
+ * directory above it. Null when it is in none, or in more than one.
+ */
+export function fileLayer(slice: SliceInfo, path: string): string | null {
+  if (Object.keys(slice.meta.layers).length > 0) return layerOf(slice, path).layer;
+  for (const [layer, folder] of FALLBACK_LAYERS) if (matchAny(under(slice, [folder], path), path)) return layer;
+  return null;
+}
+
 /** The fallback folders under the root a path belongs to, or under every root when no path is given. */
 function under(slice: SliceInfo, folders: string[], path?: string): string[] {
   const roots = path === undefined ? slice.roots : [rootOf(slice, path)].filter((root) => root !== null);