@theholocron/cli 5.0.0-alpha.427 → 5.0.0-alpha.428

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.mjs CHANGED
@@ -20582,6 +20582,147 @@ function realDocsPresenceIo(repoRoot) {
20582
20582
  };
20583
20583
  /* v8 ignore stop */
20584
20584
  }
20585
+ // src/commands/token-expectations/token-expectations.ts
20586
+ /**
20587
+ * Reads what a plugin's tokens declare (`PluginToken.expect`) as one entry per token and layer that holds it, in the
20588
+ * order of `ENVIRONMENT_LAYERS`. The one reader the token probes, the doctor and the docs check share, so none of them
20589
+ * walks the declaration itself. A token with no `expect` yields nothing; a layer no token holds is never listed.
20590
+ */
20591
+ function tokenExpectations(tokens, filter = {}) {
20592
+ const found = [];
20593
+ for (const token of tokens) {
20594
+ if (!token.expect || filter.envName !== void 0 && token.envName !== filter.envName) continue;
20595
+ const { layers = [], permissions = {} } = token.expect;
20596
+ for (const layer of ENVIRONMENT_LAYERS) {
20597
+ if (filter.layer !== void 0 && filter.layer !== layer) continue;
20598
+ const rules = permissions[layer];
20599
+ if (!rules && !layers.includes(layer)) continue;
20600
+ const entries = Object.entries(rules ?? {});
20601
+ found.push({
20602
+ envName: token.envName,
20603
+ layer,
20604
+ rules: rules ?? {},
20605
+ required: entries.filter(([, rule]) => rule === "required").map(([name]) => name),
20606
+ absent: entries.filter(([, rule]) => rule === "absent").map(([name]) => name)
20607
+ });
20608
+ }
20609
+ }
20610
+ return found;
20611
+ }
20612
+ // src/commands/probe/docs-tokens/compare-permissions/compare-permissions.ts
20613
+ const mentions = (heading, name) => heading.toLowerCase().includes(name.toLowerCase());
20614
+ /**
20615
+ * Compares what a plugin's tokens declare (`PluginToken.expect.permissions`, read through `tokenExpectations()`) with its
20616
+ * permission table in `tokens.mdx`, in both directions: a declared permission the table lacks or words differently for
20617
+ * a layer, and a permission or layer rule the table has that the declaration does not. The table is the one whose
20618
+ * heading names the token's `envName`, else the plugin (`short`, `cloudflare` for `holocron-plugin-cloudflare`). A token
20619
+ * that declares no permission rules is not compared.
20620
+ */
20621
+ function comparePermissions(tokens, tables, short) {
20622
+ const problems = [];
20623
+ for (const token of tokens) {
20624
+ const declared = tokenExpectations([token]).filter((entry) => Object.keys(entry.rules).length > 0);
20625
+ if (declared.length === 0) continue;
20626
+ const { envName } = token;
20627
+ const table = tables.find((t) => mentions(t.heading, envName)) ?? tables.find((t) => mentions(t.heading, short));
20628
+ if (!table) {
20629
+ problems.push({
20630
+ envName,
20631
+ layer: "any",
20632
+ permission: "",
20633
+ detail: "no permission table in tokens.mdx"
20634
+ });
20635
+ continue;
20636
+ }
20637
+ const byLayer = new Map(declared.map((entry) => [entry.layer, Object.fromEntries(Object.entries(entry.rules).map(([id, rule]) => [id.toLowerCase(), rule]))]));
20638
+ const ids = new Set([...byLayer.values()].flatMap((rules) => Object.keys(rules)));
20639
+ for (const entry of declared) for (const [permission, rule] of Object.entries(entry.rules)) {
20640
+ const documented = table.rows[permission.toLowerCase()];
20641
+ if (!documented) problems.push({
20642
+ envName,
20643
+ layer: entry.layer,
20644
+ permission,
20645
+ detail: "not in the tokens.mdx table"
20646
+ });
20647
+ else if (documented[entry.layer] !== rule) problems.push({
20648
+ envName,
20649
+ layer: entry.layer,
20650
+ permission,
20651
+ detail: `declared ${rule}, tokens.mdx says ${documented[entry.layer] ?? "nothing"}`
20652
+ });
20653
+ }
20654
+ for (const [permission, documented] of Object.entries(table.rows)) {
20655
+ if (!ids.has(permission)) {
20656
+ problems.push({
20657
+ envName,
20658
+ layer: "any",
20659
+ permission,
20660
+ detail: "in the tokens.mdx table, not declared"
20661
+ });
20662
+ continue;
20663
+ }
20664
+ for (const [layer, rule] of Object.entries(documented)) if (byLayer.get(layer)?.[permission] === void 0) problems.push({
20665
+ envName,
20666
+ layer,
20667
+ permission,
20668
+ detail: `tokens.mdx says ${rule}, nothing declared`
20669
+ });
20670
+ }
20671
+ }
20672
+ return problems;
20673
+ }
20674
+ // src/commands/probe/docs-tokens/permission-tables/permission-tables.ts
20675
+ const clean = (cell) => cell.replace(/[`*_]/g, "").trim().toLowerCase();
20676
+ function cells(line) {
20677
+ return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
20678
+ }
20679
+ const isTableLine = (line) => line !== void 0 && line.trim().startsWith("|");
20680
+ const isSeparator = (line) => isTableLine(line) && /^[\s|:-]+$/.test(line);
20681
+ function rule(cell) {
20682
+ const word = clean(cell ?? "");
20683
+ return word === "required" || word === "absent" ? word : void 0;
20684
+ }
20685
+ /**
20686
+ * Reads the permission tables of `tokens.mdx`: a table whose header has an `Id` column and a column named for a layer
20687
+ * (`local`, `dev`, `ci`, `prod`). A cell says `required` or `absent`; anything else (a dash, blank) is no rule. Other
20688
+ * tables, extra columns and prose around a table are ignored, so a page can grow rows and columns without a change here.
20689
+ */
20690
+ function permissionTables(page) {
20691
+ const lines = page.split("\n");
20692
+ const tables = [];
20693
+ let heading = "";
20694
+ for (let i = 0; i < lines.length; i++) {
20695
+ const line = lines[i];
20696
+ const title = /^#{1,6}\s+(.*)$/.exec(line);
20697
+ if (title) heading = title[1].trim();
20698
+ if (!isTableLine(line) || !isSeparator(lines[i + 1])) continue;
20699
+ const header = cells(line).map(clean);
20700
+ const idColumn = header.indexOf("id");
20701
+ const layerColumns = ENVIRONMENT_LAYERS.map((layer) => [layer, header.indexOf(layer)]).filter(([, column]) => column >= 0);
20702
+ let end = i + 2;
20703
+ while (isTableLine(lines[end])) end++;
20704
+ if (idColumn >= 0 && layerColumns.length > 0) {
20705
+ const rows = {};
20706
+ for (const row of lines.slice(i + 2, end)) {
20707
+ const values = cells(row);
20708
+ const id = clean(values[idColumn] ?? "");
20709
+ if (id === "") continue;
20710
+ const documented = {};
20711
+ for (const [layer, column] of layerColumns) {
20712
+ const found = rule(values[column]);
20713
+ if (found) documented[layer] = found;
20714
+ }
20715
+ rows[id] = documented;
20716
+ }
20717
+ tables.push({
20718
+ heading,
20719
+ rows
20720
+ });
20721
+ }
20722
+ i = end - 1;
20723
+ }
20724
+ return tables;
20725
+ }
20585
20726
  // src/commands/probe/docs-tokens/docs-tokens-probe.ts
20586
20727
  const KEYS = [
20587
20728
  "envName",
@@ -20602,7 +20743,10 @@ function declared(text, keys) {
20602
20743
  * `keyringKey` in `plugins/<name>/src/auth.ts`) that `docs/src/content/docs/tokens.mdx` does not document. The Discord
20603
20744
  * and GitHub plugins have their own tables, so any row of the page counts; every other plugin has one row in the
20604
20745
  * provider table and its names must be in that row. A plugin that resolves nothing (1Password uses the `op` CLI's own
20605
- * auth) needs no row. The one resolver the setup command builds itself is checked against the whole page. It runs in
20746
+ * auth) needs no row. The one resolver the setup command builds itself is checked against the whole page. A token that
20747
+ * declares permissions per layer (`PluginToken.expect`, #2150) is also compared with its permission table, a table with
20748
+ * an `Id` column and a column per layer (`required` or `absent`): a permission, layer or rule that differs fails, naming
20749
+ * the token, layer and permission. A plugin whose declaration cannot be loaded (not built) is an `info` row. It runs in
20606
20750
  * the `validate:docs` task, through `docs validate`.
20607
20751
  */
20608
20752
  function docsTokensProbe(io) {
@@ -20657,6 +20801,39 @@ function docsTokensProbe(io) {
20657
20801
  label: "setup",
20658
20802
  detail: `${setupNames.length} documented`
20659
20803
  });
20804
+ ctx.say({
20805
+ status: "heading",
20806
+ label: "Documented permissions"
20807
+ });
20808
+ const tables = permissionTables(page);
20809
+ for (const { plugin, tokens, error } of await io.declarations()) {
20810
+ if (error !== void 0) {
20811
+ ctx.say({
20812
+ status: "info",
20813
+ label: plugin,
20814
+ detail: `declaration not loaded: ${error}`
20815
+ });
20816
+ continue;
20817
+ }
20818
+ const problems = comparePermissions(tokens, tables, plugin.replace("holocron-plugin-", ""));
20819
+ for (const { envName, layer, permission, detail } of problems) {
20820
+ const where = [
20821
+ envName,
20822
+ layer,
20823
+ permission
20824
+ ].filter((part) => part !== "").join(" ");
20825
+ ctx.say({
20826
+ status: "fail",
20827
+ label: where,
20828
+ detail
20829
+ });
20830
+ }
20831
+ if (problems.length === 0 && tokens.some((token) => token.expect?.permissions)) ctx.say({
20832
+ status: "ok",
20833
+ label: plugin,
20834
+ detail: "permissions match tokens.mdx"
20835
+ });
20836
+ }
20660
20837
  }
20661
20838
  };
20662
20839
  }
@@ -20673,6 +20850,24 @@ function realDocsTokensIo(repoRoot) {
20673
20850
  plugin,
20674
20851
  text: readFileSync(file, "utf8")
20675
20852
  })),
20853
+ declarations: async () => {
20854
+ const importer = createDefaultImporter(repoRoot);
20855
+ const plugins = readdirSync(join(repoRoot, "plugins")).filter((plugin) => existsSync(join(repoRoot, "plugins", plugin, "src/auth.ts")));
20856
+ return Promise.all(plugins.map(async (plugin) => {
20857
+ try {
20858
+ return {
20859
+ plugin,
20860
+ tokens: (await importer(`@theholocron/${plugin}`)).tokens ?? []
20861
+ };
20862
+ } catch (error) {
20863
+ return {
20864
+ plugin,
20865
+ tokens: [],
20866
+ error: error instanceof Error ? error.message : String(error)
20867
+ };
20868
+ }
20869
+ }));
20870
+ },
20676
20871
  setupSource: () => readFileSync(join(repoRoot, "cli/cli/src/commands/setup/run-setup.ts"), "utf8")
20677
20872
  };
20678
20873
  /* v8 ignore stop */