@intentset/architecture 0.1.0 → 0.3.0

package/src/extract.ts

@@ -342,3 +342,153 @@ export function extractImports(path: string, text: string): Extraction {
 
   return { imports, problems };
 }
+
+/** What an Amplify schema declares at its top level (profile §9, AMP009). */
+export const SCHEMA_KINDS = ["model", "enum", "query", "mutation", "subscription", "customType"] as const;
+export type SchemaKind = (typeof SCHEMA_KINDS)[number];
+
+export interface SchemaDeclaration {
+  name: string;
+  /** Null when the value is not a builder call this reader recognizes, such as a variable defined elsewhere. */
+  kind: SchemaKind | null;
+  line: number;
+}
+
+/** A relationship or reference by name inside a schema (AMP010): `belongsTo("X")`, `hasMany`, `hasOne`, `ref`. */
+export interface SchemaReference {
+  target: string;
+  via: "belongsTo" | "hasMany" | "hasOne" | "ref";
+  line: number;
+}
+
+export interface SchemaExtraction {
+  /** False when the file holds no `<builder>.schema({ ... })` call at all. */
+  found: boolean;
+  declarations: SchemaDeclaration[];
+  references: SchemaReference[];
+  problems: ExtractProblem[];
+}
+
+const REFERENCE_CALLS = new Set(["belongsTo", "hasMany", "hasOne", "ref"]);
+const OPENERS = new Set<SyntaxKind>([
+  SyntaxKind.OpenBraceToken,
+  SyntaxKind.OpenParenToken,
+  SyntaxKind.OpenBracketToken,
+]);
+const CLOSERS = new Set<SyntaxKind>([
+  SyntaxKind.CloseBraceToken,
+  SyntaxKind.CloseParenToken,
+  SyntaxKind.CloseBracketToken,
+]);
+
+/**
+ * The top-level names an Amplify Gen 2 schema file declares, and the names its
+ * relationships and references point at, read from TypeScript's tokens as
+ * imports are. Every `<builder>.schema({ ... })` object literal counts: each
+ * key at its top level is a declaration, its kind read from a `<builder>.<kind>(`
+ * value or from a `const Name = <builder>.<kind>(` elsewhere in the file. A
+ * spread, or a value that is neither, is a problem rather than a guess.
+ */
+export function extractSchema(path: string, text: string): SchemaExtraction {
+  const { tokens, problems } = tokenize(path, text);
+  const declarations: SchemaDeclaration[] = [];
+  const references: SchemaReference[] = [];
+  const word = (i: number, value?: string): boolean => {
+    const token = tokens[i];
+    return (
+      token !== undefined && tokenIsIdentifierOrKeyword(token.kind) && (value === undefined || token.text === value)
+    );
+  };
+  const is = (i: number, kind: SyntaxKind): boolean => tokens[i]?.kind === kind;
+  /** `<builder>.<kind>(` starting at i, as the kind, or null. */
+  const builderCall = (i: number): SchemaKind | null => {
+    if (!word(i) || !is(i + 1, SyntaxKind.DotToken) || !word(i + 2) || !is(i + 3, SyntaxKind.OpenParenToken))
+      return null;
+    const kind = tokens[i + 2].text;
+    return (SCHEMA_KINDS as readonly string[]).includes(kind) ? (kind as SchemaKind) : null;
+  };
+  const bound = new Map<string, SchemaKind>();
+  for (let i = 0; i + 3 < tokens.length; i++) {
+    if ((word(i, "const") || word(i, "let")) && word(i + 1) && is(i + 2, SyntaxKind.EqualsToken)) {
+      const kind = builderCall(i + 3);
+      if (kind !== null) bound.set(tokens[i + 1].text, kind);
+    }
+  }
+
+  let found = false;
+  for (let i = 0; i + 4 < tokens.length; i++) {
+    if (!(word(i) && is(i + 1, SyntaxKind.DotToken) && word(i + 2, "schema"))) continue;
+    if (!(is(i + 3, SyntaxKind.OpenParenToken) && is(i + 4, SyntaxKind.OpenBraceToken))) continue;
+    found = true;
+    let depth = 0;
+    let k = i + 5;
+    for (; k < tokens.length; k++) {
+      const token = tokens[k];
+      if (CLOSERS.has(token.kind)) {
+        if (depth === 0) break;
+        depth--;
+        continue;
+      }
+      if (OPENERS.has(token.kind)) {
+        depth++;
+        continue;
+      }
+      if (
+        word(k) &&
+        REFERENCE_CALLS.has(token.text) &&
+        is(k - 1, SyntaxKind.DotToken) &&
+        is(k + 1, SyntaxKind.OpenParenToken)
+      ) {
+        if (is(k + 2, SyntaxKind.StringLiteral)) {
+          references.push({ target: tokens[k + 2].value, via: token.text as SchemaReference["via"], line: token.line });
+        }
+        continue;
+      }
+      if (depth !== 0) continue;
+      const startsMember = is(k - 1, SyntaxKind.OpenBraceToken) || is(k - 1, SyntaxKind.CommaToken);
+      if (!startsMember) continue;
+      if (is(k, SyntaxKind.DotDotDotToken)) {
+        problems.push({
+          line: token.line,
+          message: "the schema spreads another object in, and its members were not read",
+        });
+        continue;
+      }
+      const isKey = word(k) || is(k, SyntaxKind.StringLiteral);
+      if (!isKey) continue;
+      const name = is(k, SyntaxKind.StringLiteral) ? token.value : token.text;
+      if (is(k + 1, SyntaxKind.ColonToken)) {
+        const direct = builderCall(k + 2);
+        const named = word(k + 2) && !is(k + 3, SyntaxKind.DotToken) ? (bound.get(tokens[k + 2].text) ?? null) : null;
+        const kind = direct ?? named;
+        if (kind === null) {
+          problems.push({ line: token.line, message: `the kind of the schema member ${name} could not be read` });
+        }
+        declarations.push({ name, kind, line: token.line });
+      } else if (is(k + 1, SyntaxKind.CommaToken) || is(k + 1, SyntaxKind.CloseBraceToken)) {
+        const kind = bound.get(name) ?? null;
+        if (kind === null) {
+          problems.push({ line: token.line, message: `the kind of the schema member ${name} could not be read` });
+        }
+        declarations.push({ name, kind, line: token.line });
+      }
+    }
+    i = k;
+  }
+  return { found, declarations, references, problems };
+}
+
+/** 1-based lines where `name` is called, as `name(` or `name<T>(`, not as a method and not where it is declared. */
+export function findCalls(path: string, text: string, name: string): number[] {
+  const { tokens } = tokenize(path, text);
+  const lines: number[] = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!tokenIsIdentifierOrKeyword(token.kind) || token.text !== name) continue;
+    const before = tokens[i - 1];
+    if (before !== undefined && (before.kind === SyntaxKind.DotToken || before.text === "function")) continue;
+    const next = tokens[i + 1]?.kind;
+    if (next === SyntaxKind.OpenParenToken || next === SyntaxKind.LessThanToken) lines.push(token.line);
+  }
+  return lines;
+}

package/src/index.ts

@@ -4,6 +4,7 @@
  * (spec/profile-typescript-amplify-gen2-0.1.md). `checkArchitecture` is the
  * whole check; the rest is exported for reports, tools and tests.
  */
+export { AREA_REVIEW_REQUIRED, areaOf, backendAreaOf, checkAreas, isAreaSchema } from "./areas.ts";
 export {
   applyBaseline,
   type BaselineEntry,
@@ -19,13 +20,16 @@ export {
   type ArchitectureSummary,
   type CheckOptions,
   checkArchitecture,
+  ownershipReport,
   REVIEW_REQUIRED,
 } from "./check.ts";
 export { checkClaims } from "./claims.ts";
 export {
   ARCHITECTURE_CONFIG_PATH,
+  type AreaConfig,
   type ArchitectureConfig,
   DEFAULT_ARCHITECTURE_CONFIG,
+  MAX_AREAS,
   readArchitectureConfig,
   resolveConfig,
 } from "./config.ts";
@@ -39,7 +43,18 @@ export {
   readExceptionRecord,
   readExceptions,
 } from "./exceptions.ts";
-export { type Extraction, extractImports, type RawImport } from "./extract.ts";
+export {
+  type Extraction,
+  extractImports,
+  extractSchema,
+  findCalls,
+  type RawImport,
+  SCHEMA_KINDS,
+  type SchemaDeclaration,
+  type SchemaExtraction,
+  type SchemaKind,
+  type SchemaReference,
+} 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";

package/src/ownership.ts

@@ -10,7 +10,9 @@
  * inside one of the slice's own source claims, and no two lie in the same
  * package (the nearest directory above holding a package.json, or the
  * repository root): a slice has one public surface per package it spans. An
- * empty entrypoint module is allowed for a leaf.
+ * empty entrypoint module is allowed for a leaf. While the slice is draft, an
+ * entrypoint that is not a file yet is a warning: planned, not yet owned
+ * (VSA §3).
  *
  * VSA012 (deleting or splitting a slice dispositions its behavior, paths and
  * contracts) is a diff between two snapshots. This check sees one snapshot,
@@ -98,13 +100,17 @@ export function checkOwnership(model: Model, graph: Graph, level: Level): Findin
         );
       } else byPackage.set(pkg, entrypoint);
       if (!model.files.has(entrypoint)) {
+        const planned = slice.artifact.meta.status === "draft";
         findings.push(
           finding({
             code: "VSA002",
+            ...(planned ? { severity: "warning" as const } : {}),
             artifact: slice.id,
             path: slice.path,
             field,
-            message: `The entrypoint ${entrypoint} of ${slice.id} is not a file in the repository.`,
+            message: planned
+              ? `The entrypoint ${entrypoint} of draft slice ${slice.id} is not a file yet; it is planned, and an error once the slice leaves draft.`
+              : `The entrypoint ${entrypoint} of ${slice.id} is not a file in the repository.`,
             remediation: "Create the entrypoint, empty if the slice exposes nothing yet, or correct the path (VSA002).",
             paths: [entrypoint],
           }),

package/src/regions.ts

@@ -171,7 +171,9 @@ export function buildModel(
       validatePattern(resource.path) === null ? production.filter((file) => matchPattern(resource.path, file)) : [],
   }));
 
-  const underBackend = (path: string) => matchAny(config.backendRoots, path);
+  // An area's backend is backend for AMP001, AMP002 and AMP004 as the unified one is (profile §9).
+  const backendPatterns = [...config.backendRoots, ...config.areas.flatMap((area) => area.backend)];
+  const underBackend = (path: string) => matchAny(backendPatterns, path);
   const regions = new Map<string, Region>();
   const regionOf = (path: string): Region => {
     const cached = regions.get(path);