@topogram/cli 0.3.63 → 0.3.65

package/src/npm-safety.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const LOCAL_NPMRC_ENV = "TOPOGRAM_ALLOW_LOCAL_NPMRC";
+
+/**
+ * @param {string} spec
+ * @returns {string}
+ */
+export function assertSafeNpmSpec(spec) {
+  if (typeof spec !== "string" || spec.trim().length === 0) {
+    throw new Error("Empty npm package spec.");
+  }
+  if (spec.startsWith("-")) {
+    throw new Error(`Refusing npm package spec starting with '-': '${spec}'.`);
+  }
+  if (/[\s\r\n\0]/.test(spec)) {
+    throw new Error(`Invalid characters in npm package spec: '${spec}'.`);
+  }
+  return spec;
+}
+
+/**
+ * @param {string|undefined} value
+ * @returns {boolean}
+ */
+export function localNpmrcAllowedByEnv(value = process.env[LOCAL_NPMRC_ENV]) {
+  return value === "1" || value === "true" || value === "yes";
+}
+
+/**
+ * @param {string} cwd
+ * @returns {{ exists: boolean, path: string, enabled: boolean, reason: string }}
+ */
+export function localNpmrcStatus(cwd = process.cwd()) {
+  const npmrcPath = path.join(cwd, ".npmrc");
+  const exists = fs.existsSync(npmrcPath);
+  if (process.env.NPM_CONFIG_USERCONFIG) {
+    return {
+      exists,
+      path: npmrcPath,
+      enabled: false,
+      reason: "NPM_CONFIG_USERCONFIG is already set explicitly."
+    };
+  }
+  if (!exists) {
+    return {
+      exists,
+      path: npmrcPath,
+      enabled: false,
+      reason: "No local .npmrc was found."
+    };
+  }
+  if (!localNpmrcAllowedByEnv()) {
+    return {
+      exists,
+      path: npmrcPath,
+      enabled: false,
+      reason: `Local .npmrc is ignored unless ${LOCAL_NPMRC_ENV}=1 or --allow-local-npmrc is used.`
+    };
+  }
+  return {
+    exists,
+    path: npmrcPath,
+    enabled: true,
+    reason: `Local .npmrc is enabled by ${LOCAL_NPMRC_ENV}.`
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Record<string, string>}
+ */
+export function localNpmrcEnv(cwd = process.cwd()) {
+  const status = localNpmrcStatus(cwd);
+  return status.enabled ? { NPM_CONFIG_USERCONFIG: status.path } : {};
+}

package/src/parser.d.ts

@@ -0,0 +1,87 @@
+import type { TopogramDoc } from "./workspace-docs.js";
+
+export interface ParserPosition {
+  line: number;
+  column: number;
+  offset: number;
+}
+
+export interface LexerToken {
+  type: string;
+  value: string;
+  start: ParserPosition;
+  end: ParserPosition;
+}
+
+export interface AstLocation {
+  file: string;
+  start: ParserPosition;
+  end: ParserPosition;
+}
+
+export interface AstScalar {
+  type: "string" | "symbol";
+  value: string;
+  loc: AstLocation;
+}
+
+export interface AstList {
+  type: "list";
+  items: AstValue[];
+  loc: AstLocation;
+}
+
+export interface AstSequence {
+  type: "sequence";
+  items: AstValue[];
+  loc: AstLocation;
+}
+
+export interface AstBlock {
+  type: "block";
+  entries: AstBlockEntry[];
+  loc: AstLocation;
+}
+
+export type AstValue = AstScalar | AstList | AstSequence | AstBlock;
+
+export interface AstBlockEntry {
+  type: "block_entry";
+  items: AstValue[];
+  loc: AstLocation;
+}
+
+export interface AstField {
+  type: "field";
+  key: string;
+  value: AstValue;
+  loc: AstLocation;
+}
+
+export interface AstStatement {
+  type: "statement";
+  kind: string;
+  id: string;
+  from: AstScalar | null;
+  fields: AstField[];
+  loc: AstLocation;
+}
+
+export interface AstDocument {
+  type: "document";
+  file: string;
+  statements: AstStatement[];
+}
+
+export interface WorkspaceAst {
+  type: "workspace";
+  root: string;
+  files: AstDocument[];
+  docs: TopogramDoc[];
+}
+
+export function lex(source: string, filePath?: string): LexerToken[];
+export function parseSource(source: string, filePath?: string): AstDocument;
+export function parseFile(filePath: string): AstDocument;
+export function collectTopogramFiles(inputPath: string): string[];
+export function parsePath(root: string): WorkspaceAst;

package/src/parser.js

@@ -1,31 +1,76 @@
+// @ts-check
+
 import fs from "node:fs";
 import path from "node:path";
 import { parseDocsPath } from "./workspace-docs.js";
 
+/**
+ * @typedef {{ line: number, column: number, offset: number }} ParserPosition
+ * @typedef {{ type: string, value: string, start: ParserPosition, end: ParserPosition }} LexerToken
+ * @typedef {{ file: string, start: ParserPosition, end: ParserPosition }} AstLocation
+ * @typedef {{ type: "string" | "symbol", value: string, loc: AstLocation }} AstScalar
+ * @typedef {{ type: "list", items: AstValue[], loc: AstLocation }} AstList
+ * @typedef {{ type: "sequence", items: AstValue[], loc: AstLocation }} AstSequence
+ * @typedef {{ type: "block", entries: AstBlockEntry[], loc: AstLocation }} AstBlock
+ * @typedef {AstScalar | AstList | AstSequence | AstBlock} AstValue
+ * @typedef {{ type: "block_entry", items: AstValue[], loc: AstLocation }} AstBlockEntry
+ * @typedef {{ type: "field", key: string, value: AstValue, loc: AstLocation }} AstField
+ * @typedef {{ type: "statement", kind: string, id: string, from: AstScalar | null, fields: AstField[], loc: AstLocation }} AstStatement
+ * @typedef {{ type: "document", file: string, statements: AstStatement[] }} AstDocument
+ * @typedef {{ type: "workspace", root: string, files: AstDocument[], docs: any[] }} WorkspaceAst
+ */
+
+/**
+ * @param {number} line
+ * @param {number} column
+ * @param {number} offset
+ * @returns {ParserPosition}
+ */
 function createPos(line, column, offset) {
   return { line, column, offset };
 }
 
+/**
+ * @param {string} type
+ * @param {string} value
+ * @param {ParserPosition} start
+ * @param {ParserPosition} end
+ * @returns {LexerToken}
+ */
 function createToken(type, value, start, end) {
   return { type, value, start, end };
 }
 
+/**
+ * @param {string} filePath
+ * @param {string} message
+ * @param {LexerToken | null | undefined} token
+ * @returns {Error}
+ */
 function createError(filePath, message, token) {
   const line = token?.start?.line ?? 1;
   const column = token?.start?.column ?? 1;
   return new Error(`${filePath}:${line}:${column} ${message}`);
 }
 
+/**
+ * @param {string} source
+ * @param {string} [filePath]
+ * @returns {LexerToken[]}
+ */
 export function lex(source, filePath = "<memory>") {
+  /** @type {LexerToken[]} */
   const tokens = [];
   let i = 0;
   let line = 1;
   let column = 1;
 
+  /** @returns {ParserPosition} */
   function pos() {
     return createPos(line, column, i);
   }
 
+  /** @param {string} char */
   function advanceChar(char) {
     i += 1;
     if (char === "\n") {
@@ -36,6 +81,12 @@ export function lex(source, filePath = "<memory>") {
     }
   }
 
+  /**
+   * @param {string} type
+   * @param {string} value
+   * @param {ParserPosition} start
+   * @param {ParserPosition} end
+   */
   function push(type, value, start, end) {
     tokens.push(createToken(type, value, start, end));
   }
@@ -166,31 +217,48 @@ export function lex(source, filePath = "<memory>") {
 }
 
 class Parser {
+  /**
+   * @param {LexerToken[]} tokens
+   * @param {string} filePath
+   */
   constructor(tokens, filePath) {
     this.tokens = tokens;
     this.filePath = filePath;
     this.index = 0;
   }
 
+  /** @returns {LexerToken} */
   current() {
     return this.tokens[this.index];
   }
 
+  /** @returns {LexerToken | undefined} */
   previous() {
     return this.tokens[this.index - 1];
   }
 
+  /** @returns {LexerToken} */
   advance() {
     const token = this.current();
     this.index += 1;
     return token;
   }
 
+  /**
+   * @param {string} type
+   * @param {string} [value]
+   * @returns {boolean}
+   */
   check(type, value) {
     const token = this.current();
     return token.type === type && (value === undefined || token.value === value);
   }
 
+  /**
+   * @param {string} type
+   * @param {string} [value]
+   * @returns {LexerToken | null}
+   */
   match(type, value) {
     if (!this.check(type, value)) {
       return null;
@@ -198,6 +266,12 @@ class Parser {
     return this.advance();
   }
 
+  /**
+   * @param {string} type
+   * @param {string | undefined} value
+   * @param {string} message
+   * @returns {LexerToken}
+   */
   expect(type, value, message) {
     const token = this.current();
     if (!this.check(type, value)) {
@@ -206,13 +280,16 @@ class Parser {
     return this.advance();
   }
 
+  /** @returns {void} */
   skipNewlines() {
     while (this.match("newline")) {
       // Skip layout-only line breaks between statements and fields.
     }
   }
 
+  /** @returns {AstDocument} */
   parseDocument() {
+    /** @type {AstStatement[]} */
     const statements = [];
     this.skipNewlines();
 
@@ -228,11 +305,13 @@ class Parser {
     };
   }
 
+  /** @returns {AstStatement} */
   parseStatement() {
     const kind = this.expect("word", undefined, "Expected statement kind");
     const id = this.expect("word", undefined, "Expected statement identifier");
     const start = kind.start;
 
+    /** @type {LexerToken | null} */
     let from = null;
     if (this.match("word", "from")) {
       from = this.expect("word", undefined, "Expected identifier after 'from'");
@@ -242,6 +321,7 @@ class Parser {
     this.expect("lbrace", undefined, "Expected '{' to start statement body");
     this.skipNewlines();
 
+    /** @type {AstField[]} */
     const fields = [];
     while (!this.check("rbrace")) {
       fields.push(this.parseField());
@@ -260,6 +340,7 @@ class Parser {
     };
   }
 
+  /** @returns {AstField} */
   parseField() {
     const key = this.expect("word", undefined, "Expected field name");
     const start = key.start;
@@ -287,9 +368,11 @@ class Parser {
     };
   }
 
+  /** @returns {AstBlock} */
   parseBlock() {
     const open = this.expect("lbrace", undefined, "Expected '{' to start block");
     this.skipNewlines();
+    /** @type {AstBlockEntry[]} */
     const entries = [];
 
     while (!this.check("rbrace")) {
@@ -313,7 +396,12 @@ class Parser {
     };
   }
 
+  /**
+   * @param {string[]} stopTypes
+   * @returns {AstValue[]}
+   */
   parseSequenceUntil(stopTypes) {
+    /** @type {AstValue[]} */
     const items = [];
 
     while (!stopTypes.includes(this.current().type) && !this.check("eof")) {
@@ -326,6 +414,7 @@ class Parser {
     return items;
   }
 
+  /** @returns {AstValue} */
   parseAtom() {
     const token = this.current();
 
@@ -354,8 +443,10 @@ class Parser {
     throw createError(this.filePath, `Unexpected token '${token.value || token.type}'`, token);
   }
 
+  /** @returns {AstList} */
   parseList() {
     const open = this.expect("lbracket", undefined, "Expected '[' to start list");
+    /** @type {AstValue[]} */
     const items = [];
 
     while (!this.check("rbracket")) {
@@ -373,6 +464,10 @@ class Parser {
     };
   }
 
+  /**
+   * @param {LexerToken} token
+   * @returns {AstScalar}
+   */
   nodeFromToken(token) {
     return {
       type: "symbol",
@@ -381,6 +476,11 @@ class Parser {
     };
   }
 
+  /**
+   * @param {ParserPosition} start
+   * @param {ParserPosition} end
+   * @returns {AstLocation}
+   */
   loc(start, end) {
     return {
       file: this.filePath,
@@ -390,17 +490,30 @@ class Parser {
   }
 }
 
+/**
+ * @param {string} source
+ * @param {string} [filePath]
+ * @returns {AstDocument}
+ */
 export function parseSource(source, filePath = "<memory>") {
   const tokens = lex(source, filePath);
   const parser = new Parser(tokens, filePath);
   return parser.parseDocument();
 }
 
+/**
+ * @param {string} filePath
+ * @returns {AstDocument}
+ */
 export function parseFile(filePath) {
   const source = fs.readFileSync(filePath, "utf8");
   return parseSource(source, filePath);
 }
 
+/**
+ * @param {string} inputPath
+ * @returns {string[]}
+ */
 export function collectTopogramFiles(inputPath) {
   const absolutePath = path.resolve(inputPath);
   const stat = fs.statSync(absolutePath);
@@ -409,6 +522,7 @@ export function collectTopogramFiles(inputPath) {
     return absolutePath.endsWith(".tg") ? [absolutePath] : [];
   }
 
+  /** @type {string[]} */
   const files = [];
   for (const entry of fs.readdirSync(absolutePath, { withFileTypes: true })) {
     const childPath = path.join(absolutePath, entry.name);
@@ -427,6 +541,10 @@ export function collectTopogramFiles(inputPath) {
   return files.sort();
 }
 
+/**
+ * @param {string} inputPath
+ * @returns {WorkspaceAst}
+ */
 export function parsePath(inputPath) {
   const files = collectTopogramFiles(inputPath);
   const docs = parseDocsPath(inputPath);

package/src/path-helpers.d.ts

@@ -0,0 +1 @@
+export function relativeTo(from: string, to: string): string;

package/src/path-helpers.js

@@ -0,0 +1,20 @@
+// @ts-check
+
+import path from "node:path";
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function toPosixPath(value) {
+  return String(value || "").replaceAll("\\", "/").replaceAll(path.sep, "/");
+}
+
+/**
+ * @param {string} base
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function relativeTo(base, filePath) {
+  return toPosixPath(path.relative(base, filePath));
+}

package/src/policy/review-boundaries.d.ts

@@ -0,0 +1,15 @@
+export function defaultOwnershipBoundary(): any;
+export function ownershipBoundaryForMaintainedSurface(...args: any[]): any;
+export function reviewBoundaryForCapability(...args: any[]): any;
+export function reviewBoundaryForEntity(...args: any[]): any;
+export function reviewBoundaryForJourneyDoc(...args: any[]): any;
+export function reviewBoundaryForMaintainedClassification(...args: any[]): any;
+export function reviewBoundaryForProjection(...args: any[]): any;
+export function reviewBoundaryForWorkflowDoc(...args: any[]): any;
+export function reviewBoundaryForAcceptanceCriterion(...args: any[]): any;
+export function reviewBoundaryForBug(...args: any[]): any;
+export function reviewBoundaryForDocument(...args: any[]): any;
+export function reviewBoundaryForDomain(...args: any[]): any;
+export function reviewBoundaryForPitch(...args: any[]): any;
+export function reviewBoundaryForRequirement(...args: any[]): any;
+export function reviewBoundaryForTask(...args: any[]): any;